blume 1.1.0 → 1.1.1

package/src/core/schema.ts

@@ -870,6 +870,13 @@ const ogConfigSchema = z.strictObject({
   logo: z.string().optional(),
   /** Optional generated-card colors. */
   palette: ogPaletteSchema.optional(),
+  /**
+   * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+   * A custom page has no frontmatter to read, so its card is otherwise titled
+   * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+   * Content pages always take their card headline from the page title.
+   */
+  titles: z.record(z.string(), z.string()).optional(),
 });
 
 const rssConfigSchema = z.strictObject({

package/src/core/sources/github-releases.ts

@@ -56,6 +56,63 @@ const LEADING_V = /^v/iu;
 const NON_SLUG = /[^a-z0-9]+/gu;
 const EDGE_DASHES = /^-+|-+$/gu;
 
+// `blume audit` grades meta descriptions against the 110–160 character search
+// snippet range (audit/types.ts thresholds), so the derived summary aims for
+// the longest word-boundary cut under the cap.
+const DESCRIPTION_MAX = 160;
+const DESCRIPTION_MIN = 110;
+
+const CODE_FENCE = /```[\s\S]*?```/gu;
+const HEADING_LINE = /^#{1,6}\s.*$/gmu;
+const LIST_MARK = /^\s*(?:[-*+]|\d+[.)])\s+/u;
+// Changesets-generated release bullets open with the changeset's short commit
+// hash (`- cf8fa22: Fix …`) — noise in a search snippet.
+const CHANGESET_HASH = /^[0-9a-f]{7,40}:\s+/u;
+const IMAGE = /!\[[^\]]*\]\([^)]*\)/gu;
+const LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const INLINE_CODE = /`(?<code>[^`]+)`/gu;
+// Tag-shaped only: a bare `<` in prose must not swallow text up to a later `>`.
+const HTML_OR_JSX = /<\/?[a-zA-Z][^\n<>]*>|<\/?>/gu;
+const MARKDOWN_PUNCT = /[*_~>]+/gu;
+const WHITESPACE = /\s+/gu;
+const TRAILING_FRAGMENT = /[\s,;:.—–-]+$/u;
+
+/**
+ * Derive a meta description from release notes: markdown reduced to plain
+ * text — section headings ("### Patch Changes") and changesets' commit-hash
+ * bullet prefixes dropped — then cut at a word boundary to fit the search
+ * snippet cap. Undefined when the notes have no prose at all.
+ */
+const releaseDescription = (body: string): string | undefined => {
+  const text = body
+    .replaceAll(CODE_FENCE, " ")
+    .replaceAll(HEADING_LINE, "")
+    .split("\n")
+    .map((line) => line.replace(LIST_MARK, "").replace(CHANGESET_HASH, ""))
+    .join("\n")
+    .replaceAll(IMAGE, " ")
+    .replaceAll(LINK, "$<text>")
+    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(HTML_OR_JSX, " ")
+    .replaceAll(MARKDOWN_PUNCT, " ")
+    .replaceAll(WHITESPACE, " ")
+    .trim();
+  if (!text) {
+    return undefined;
+  }
+  if (text.length <= DESCRIPTION_MAX) {
+    return text;
+  }
+  // Cut before the cap at a word boundary (kept only when it doesn't drop the
+  // summary under the minimum), shed any dangling punctuation, and mark the cut.
+  const slice = text.slice(0, DESCRIPTION_MAX - 1);
+  const boundary = slice.lastIndexOf(" ");
+  const head = (
+    boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice
+  ).replace(TRAILING_FRAGMENT, "");
+  return `${head}…`;
+};
+
 /** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
 const slugifyTag = (tag: string): string =>
   tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
@@ -71,9 +128,10 @@ const githubHeaders = (): Headers => {
 };
 
 /**
- * Lower one release to a staged Markdown entry: the notes become the body and
+ * Lower one release to a staged Markdown entry: the notes become the body,
  * `type: changelog` frontmatter (title/date/version/category) drives the
- * generated `/changelog` timeline and RSS feed.
+ * generated `/changelog` timeline and RSS feed, and a summary derived from the
+ * notes becomes the release page's meta description.
  */
 const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const version = release.tag_name.replace(LEADING_V, "");
@@ -81,9 +139,14 @@ const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const date = release.published_at ?? release.created_at;
   const category = release.prerelease ? "Prerelease" : "Release";
   const body = (release.body ?? "").replaceAll("\r\n", "\n").trim();
+  // A summary in `seo.description` gives each release page a unique meta
+  // description (instead of the site-wide fallback) without also rendering the
+  // visible lede paragraph a top-level `description` would add.
+  const description = releaseDescription(body);
   const data = {
     changelog: { category, version },
     date,
+    ...(description ? { seo: { description } } : {}),
     title,
     type: "changelog",
   };

package/src/core/types.ts

@@ -108,6 +108,13 @@ export interface PageRecord {
    * `/guides/x`). Pages with the same key are translations of each other.
    */
   translationKey: string;
+  /**
+   * True for entries filled in from the fallback locale to pad a locale's
+   * navigation for pages it hasn't translated yet. The record's content —
+   * title included — belongs to the fallback locale, so per-locale content
+   * checks skip these.
+   */
+  fallback?: boolean;
   /**
    * Content-relative path with the leading locale directory stripped, used for
    * sidebar grouping so the locale dir is not surfaced as a nav group. Equals

package/src/markdown/index.ts

@@ -37,6 +37,7 @@ export { calloutTypeFor } from "./directives.ts";
 export { headingAnchorPlugin } from "./heading-anchors.ts";
 export { mermaidPlugin } from "./mermaid.ts";
 export { packageInstallPlugin } from "./package-install.ts";
+export { blumeTwoslashTransformer } from "./twoslash.ts";
 
 /** Element type of Satteri's `mdastPlugins`, sourced from the (alpha) core. */
 type MdastPlugin = NonNullable<

package/src/markdown/twoslash.ts

@@ -0,0 +1,60 @@
+/**
+ * The Twoslash transformer for fenced code blocks, compiled with Blume's own
+ * pinned TypeScript instead of whatever copy the user's project hoists.
+ *
+ * The stock `transformerTwoslash` from `@shikijs/twoslash` resolves the
+ * ambient `typescript` package, which is whatever version the surrounding
+ * project installed. Under TypeScript 7 (the native tsgo compiler) the
+ * package's main export is a version stub with no classic compiler API — no
+ * `ts.sys`, no language service — and its `lib/` directory ships no
+ * `lib.*.d.ts` files, so Twoslash breaks the moment a fence uses it. Blume
+ * ships a classic `typescript` as its own runtime dependency, so this factory
+ * resolves that copy from inside the package and hands it to Twoslash
+ * explicitly (`tsModule` for the compiler, `tsLibDirectory` for the default
+ * lib files), leaving the user's project free to use any TypeScript version.
+ *
+ * Composed from the `core` entrypoints of both packages: the main `twoslash`
+ * entry eagerly imports the ambient `typescript` (harmless under TS7 — the
+ * stub loads fine — but pointless), and its `transformerTwoslash` wrapper
+ * forwards `tsModule` to `createTwoslasher` while dropping `tsLibDirectory`.
+ * The core entries import no `typescript` at all and take both options.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { createTransformerFactory, rendererRich } from "@shikijs/twoslash/core";
+import type { ShikiTransformer } from "shiki";
+import { createTwoslasher } from "twoslash/core";
+import type TS from "typescript";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Twoslash transformer preconfigured for Blume: opt-in per fence via the
+ * `twoslash` meta keyword (explicitTrigger), compiling with Blume's own
+ * pinned classic TypeScript. The compiler is resolved lazily at call time —
+ * this runs once, at Astro config load — so merely importing this module
+ * never pays the TypeScript parse cost.
+ */
+export const blumeTwoslashTransformer = (): ShikiTransformer => {
+  const tsModule = require("typescript") as typeof TS;
+  const twoslasher = createTwoslasher({
+    // Match the stock transformer's default: fence snippets are authored
+    // bundler-style (extensionless relative imports, package imports).
+    compilerOptions: {
+      moduleResolution: tsModule.ModuleResolutionKind.Bundler,
+    },
+    // `require.resolve("typescript")` is the package's main entry,
+    // `lib/typescript.js`; its directory holds the `lib.*.d.ts` default libs.
+    tsLibDirectory: path.dirname(require.resolve("typescript")),
+    tsModule,
+    vfsRoot: process.cwd(),
+  });
+  return createTransformerFactory(
+    twoslasher,
+    rendererRich()
+  )({
+    explicitTrigger: true,
+  });
+};

package/src/registry/eject.ts

@@ -472,7 +472,9 @@ export const eject = async (
 
   if (config.seo.og.enabled) {
     files.push({
-      content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
+      content: ogEndpointTemplate(
+        customOgRoutes(pages, config.title, config.seo.og.titles)
+      ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }