blume 1.6.3 → 1.6.4

package/src/markdown/package-commands.ts

@@ -2,7 +2,14 @@ import type { Agent, Command } from "package-manager-detector";
 import { resolveCommand } from "package-manager-detector/commands";
 
 /** Supported package managers, in the order tabs are displayed. */
-export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+export const PACKAGE_MANAGERS = [
+  "npm",
+  "pnpm",
+  "yarn",
+  "bun",
+  "nub",
+  "aube",
+] as const;
 
 export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 
@@ -15,14 +22,29 @@ export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
  * npm's form, matching `ni`'s table.
  */
 const AGENT_FOR = {
+  aube: "aube",
   bun: "bun",
   npm: "npm",
+  nub: "nub",
   pnpm: "pnpm",
   yarn: "yarn@berry",
 } satisfies Record<PackageManager, Agent>;
 
 /** Words that mark the input as an explicit command rather than a bare list. */
-const MANAGER_PREFIXES = new Set(["bun", "bunx", "npm", "npx", "pnpm", "yarn"]);
+const MANAGER_PREFIXES = new Set([
+  "aube",
+  "bun",
+  "bunx",
+  "npm",
+  "npx",
+  "nub",
+  "nubx",
+  "pnpm",
+  "yarn",
+]);
+
+/** Standalone runner binaries that spell `<manager> exec` as one word. */
+const EXEC_BINARIES = new Set(["bunx", "npx", "nubx"]);
 
 const WHITESPACE = /\s+/u;
 const WHITESPACE_RUN = /\s+/gu;
@@ -104,7 +126,7 @@ const parseIntent = (input: string): Intent => {
   if (!MANAGER_PREFIXES.has(first)) {
     return { args: normalizeFlags(tokens), operation: "add" };
   }
-  if (first === "npx" || first === "bunx") {
+  if (EXEC_BINARIES.has(first)) {
     return { args: rest, operation: "exec" };
   }
 
@@ -193,8 +215,10 @@ export const toPackageCommands = (input: string) => {
   const normalize = (command: string): string =>
     command.replaceAll(WHITESPACE_RUN, " ").trim();
   return {
+    aube: normalize(buildCommand("aube", intent)),
     bun: normalize(buildCommand("bun", intent)),
     npm: normalize(buildCommand("npm", intent)),
+    nub: normalize(buildCommand("nub", intent)),
     pnpm: normalize(buildCommand("pnpm", intent)),
     yarn: normalize(buildCommand("yarn", intent)),
   } satisfies Record<PackageManager, string>;

package/src/openapi/graphql.ts

@@ -124,6 +124,35 @@ export const isGraphqlOperationKind = (
 ): method is GraphqlOperationKind =>
   GRAPHQL_OPERATION_KINDS.some((kind) => kind === method);
 
+/** The SDL keyword that declares each named-type kind: `type Pet`, `enum Status`. */
+const GRAPHQL_TYPE_KEYWORDS = {
+  enum: "enum",
+  input: "input",
+  interface: "interface",
+  object: "type",
+  scalar: "scalar",
+  union: "union",
+} satisfies Record<GraphqlTypeKind, string>;
+
+/**
+ * A GraphQL member in the schema's own notation — `query pets` for a root
+ * field, `type Pet` / `input PetInput` / `enum Status` for a named type. The
+ * rendered page shows the same pair as a kind badge beside the name; the
+ * text form spells the kind the way SDL does, so a reader who knows GraphQL
+ * and not Blume's badges reads it right.
+ */
+export const graphqlSignature = (
+  operation: Pick<ApiOperationRef, "method" | "path">
+): string => {
+  // SAFETY: the GraphQL extractor only ever assigns member kinds as the
+  // method (see `extractGraphqlOperations`).
+  const member = operation.method as GraphqlMember;
+  const keyword = isGraphqlOperationKind(member)
+    ? member
+    : GRAPHQL_TYPE_KEYWORDS[member];
+  return `${keyword} ${operation.path}`;
+};
+
 // Deterministic name order for type pages, independent of schema declaration
 // order and of the platform's collation (localeCompare varies across ICU
 // builds; codepoint order does not).

package/src/openapi/model.ts

@@ -143,6 +143,75 @@ export interface ApiSpecData {
 /** The generated `blume:openapi` module: specs keyed by {@link ApiSpecData.slug}. */
 export type OpenApiData = Record<string, ApiSpecData>;
 
+/**
+ * The spec a `<Operation source>` / `<ApiOverview source>` names, or nothing.
+ * `blume:openapi` crosses a JSON boundary as a plain object, so a lookup must
+ * be an own-property one: `source="toString"` would otherwise resolve to the
+ * inherited function, which is truthy and carries no `operations`, and every
+ * consumer would throw where it means to decline. Shared by the components
+ * and the agent-surface serializers so they miss the same way.
+ */
+export const specOf = (
+  specs: OpenApiData,
+  source: string
+): ApiSpecData | undefined =>
+  Object.hasOwn(specs, source) ? specs[source] : undefined;
+
+/** The operation an `<Operation id>` names within its spec, or nothing. */
+export const operationOf = (
+  spec: ApiSpecData,
+  id: string
+): ApiOperationRef | undefined =>
+  Object.hasOwn(spec.operations, id) ? spec.operations[id] : undefined;
+
+/** The addresses an API overview lists, and what to call them. */
+export interface SpecAddresses {
+  /** `Base URL` (OpenAPI), `Servers` (AsyncAPI) or `Endpoint` (GraphQL). */
+  label: string;
+  addresses: string[];
+}
+
+/**
+ * Where the API lives, flattened into one list for the overview page. OpenAPI
+ * declares `servers` as an array of URLs; AsyncAPI as a named map of
+ * host/protocol/pathname; a GraphQL schema names no server, so its configured
+ * live endpoint stands in.
+ */
+export const specAddresses = (spec: ApiSpecData): SpecAddresses => {
+  const addresses: string[] = [];
+  if (spec.kind === "graphql") {
+    if (spec.endpoint) {
+      addresses.push(spec.endpoint);
+    }
+    return { addresses, label: "Endpoint" };
+  }
+  if (spec.kind === "asyncapi") {
+    // SAFETY: an `asyncapi` spec's document is the AsyncAPI shape (`parse.ts`
+    // routes each kind to its own parser).
+    const servers = (spec.document as AsyncApiDocument).servers ?? {};
+    for (const server of Object.values(servers)) {
+      if (server?.host) {
+        addresses.push(
+          `${server.protocol ? `${server.protocol}://` : ""}${server.host}${server.pathname ?? ""}`
+        );
+      }
+    }
+    return { addresses, label: "Servers" };
+  }
+  // Hand-written specs sometimes declare `servers` as a bare object; degrade
+  // to no addresses instead of throwing mid-build.
+  // SAFETY: the remaining kind is OpenAPI, whose document declares `servers`
+  // as an array of server objects; the array check below guards a spec that
+  // wrote something else there.
+  const declared = (spec.document as { servers?: { url?: string }[] }).servers;
+  for (const server of Array.isArray(declared) ? declared : []) {
+    if (server.url) {
+      addresses.push(server.url);
+    }
+  }
+  return { addresses, label: "Base URL" };
+};
+
 // The runtime object check stands guard because the document was parsed from
 // arbitrary YAML/JSON: a spec can put a scalar where the type promises an
 // operation object.

package/src/openapi/render-mdx.ts

@@ -8,6 +8,7 @@ import type { GraphqlMember } from "./graphql.ts";
 import { isGraphqlOperationKind } from "./graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
+import { operationSignature } from "./signature.ts";
 
 /**
  * Lower a parsed spec into MDX for the staged content source. Each operation and
@@ -226,11 +227,11 @@ export const operationMdx = (
 ): RenderedPage => {
   const method = operation.method.toUpperCase();
   const graphql = spec.kind === "graphql";
-  // A GraphQL page IS its field/type — `QUERY pets` would double the badge the
+  // A GraphQL page IS its field/type — `query pets` would double the badge the
   // page already renders; the other kinds title an endpoint or channel action.
   const fallbackTitle = graphql
     ? operation.path
-    : `${method} ${operation.path}`;
+    : operationSignature(spec, operation);
   const title = operation.summary || fallbackTitle;
   // Skip the body description when it only repeats the summary (the `<h1>`) —
   // common in specs that set summary and description to the same string.

package/src/openapi/signature.ts

@@ -0,0 +1,18 @@
+import { graphqlSignature } from "./graphql.ts";
+import type { ApiOperationRef, ApiSpecData } from "./model.ts";
+
+/**
+ * The one-line name of what an operation page documents, in the notation of
+ * its spec kind: `GET /pets/{id}` for an HTTP endpoint, `SEND user/signup`
+ * for an AsyncAPI channel action, `query pets` or `type Pet` for a GraphQL
+ * member. The page titles an untitled operation with it and the agent
+ * surfaces (`<route>.md`, llms-full.txt, MCP `get_page`) downlevel
+ * `<Operation>` to it, so the two can never disagree about the endpoint.
+ */
+export const operationSignature = (
+  spec: Pick<ApiSpecData, "kind">,
+  operation: Pick<ApiOperationRef, "method" | "path">
+): string =>
+  spec.kind === "graphql"
+    ? graphqlSignature(operation)
+    : `${operation.method.toUpperCase()} ${operation.path}`;

package/src/search/documents.ts

@@ -5,13 +5,13 @@ import {
   componentRegistry,
   downlevelComponentNode,
   downlevelComponents,
-  exampleComponentSerializers,
 } from "../ai/component-markdown.ts";
 import type {
   ComponentMarkdown,
   DownlevelWalk,
   MdastNode as DownlevelNode,
 } from "../ai/component-markdown.ts";
+import { projectComponentSerializers } from "../ai/serializers.ts";
 import { applyAudienceVisibility } from "../ai/visibility.ts";
 import type { VisibilityAudience } from "../ai/visibility.ts";
 import matter from "../core/frontmatter.ts";
@@ -437,14 +437,9 @@ export const buildSearchDocuments = async (
     return page ? contentIndexable(page, project.config) : false;
   });
 
-  // Serializers for downleveling, layered the way `buildRawMarkdown` layers
-  // them: examples first, so a user `markdownComponents` entry of the same
-  // name still wins. Built once — `downlevelComponents` rebuilds its registry
-  // per call otherwise.
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...project.config.ai.markdownComponents,
-  };
+  // Built once — `downlevelComponents` rebuilds its registry per call
+  // otherwise.
+  const components = projectComponentSerializers(project);
 
   return await Promise.all(
     indexable.map(async (route) => {

package/src/theme/entry.ts

@@ -1,5 +1,13 @@
 import { CODE_PADDING_BLOCK_REM } from "./code-block-padding.ts";
 
+/**
+ * Bottom inset of the scrolling code element, in rem: keeps a horizontal
+ * scrollbar thumb off the last line's descenders. It is carved out of the
+ * pre's block padding rather than added to it, so a block's height is the
+ * same whether or not it scrolls.
+ */
+const CODE_SCROLL_INSET_REM = 0.375;
+
 interface TailwindEntryOptions {
   /**
    * Globs to scan for utility classes. Typically the Blume package source and
@@ -495,8 +503,9 @@ blume-diff {
   max-height: 24rem;
   overflow: auto;
   /* The small bottom inset keeps the horizontal thumb off the last line's
-     descenders now that scrollbars are visible. */
-  padding: 0 1.25rem 0.375rem;
+     descenders now that scrollbars are visible. The pre gives up the same
+     amount below (next rule), so the inset adds no height to the block. */
+  padding: 0 1.25rem ${CODE_SCROLL_INSET_REM}rem;
   /* Thin theme-colored scrollbars, matching the sidebar treatment, so a
      height-capped block reads as scrollable instead of simply ending.
      Safari before 18.2 supports neither property and falls back to the
@@ -505,6 +514,14 @@ blume-diff {
   scrollbar-width: thin;
 }
 
+/* The scroller's bottom inset comes out of the pre's own block padding: the
+   text still sits one full inset above the frame's bottom edge, the thumb sits
+   in the gap, and a one-line command is no taller than it was before the
+   scroller existed. */
+.prose :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *):has(> code)) {
+  padding-bottom: calc(${CODE_PADDING_BLOCK_REM}rem - ${CODE_SCROLL_INSET_REM}rem);
+}
+
 /* The dark border token is too close to the page background to read as a
    scrollbar thumb; derive a brighter one from the muted foreground instead. */
 :root[data-theme="dark"]

package/src/translate/anchors.ts

@@ -0,0 +1,91 @@
+import { scanBody } from "../core/sources/normalize.ts";
+
+/**
+ * Keep heading anchors identical across languages. A translated heading slugs
+ * to a different id (`## Ordering` → `#ordering`, `## Reihenfolge` →
+ * `#reihenfolge`), so a `/guide#ordering` link — which the runtime keeps
+ * inside the reader's locale — would land at the top of the translated page.
+ * After a translation validates, every heading whose rendered id would differ
+ * from its source counterpart gets the source id pinned as a trailing
+ * `[#id]` marker, so the anchor index (and every `#fragment` link) agrees in
+ * every locale. Headings the translation already pins are left alone: the
+ * agent is told to copy markers verbatim, and a hand-authored pin is the
+ * translator's choice.
+ *
+ * Headings pair positionally, so the translation must mirror the source's
+ * heading structure (the prompt demands exactly that); when it doesn't, no
+ * pins are added and the text is returned unchanged with a reason.
+ */
+
+export interface PinResult {
+  /** Number of headings that received a pin. */
+  pinned: number;
+  /** Why no pins were added, when the structures don't line up. */
+  skipped?: string;
+  text: string;
+}
+
+/** An ATX heading's optional closing hash run, which a marker must precede. */
+const ATX_CLOSE = /\s+#+$/u;
+
+const structureOf = (headings: readonly { depth: number }[]): string =>
+  headings.map((heading) => heading.depth).join(",");
+
+/** Append `[#id]` to a heading line, ahead of any closing `##` and line end. */
+const pinLine = (line: string, id: string): string => {
+  const eol = line.endsWith("\r") ? "\r" : "";
+  const body = line.slice(0, line.length - eol.length).trimEnd();
+  const close = body.match(ATX_CLOSE)?.[0] ?? "";
+  const head = body.slice(0, body.length - close.length);
+  return `${head} [#${id}]${close}${eol}`;
+};
+
+export const pinHeadingAnchors = (
+  sourceText: string,
+  translatedText: string
+): PinResult => {
+  const source = scanBody(sourceText);
+  const translated = scanBody(translatedText);
+  if (structureOf(source.headings) !== structureOf(translated.headings)) {
+    return {
+      pinned: 0,
+      skipped: `heading structure differs (source has ${source.headings.length} headings, translation has ${translated.headings.length})`,
+      text: translatedText,
+    };
+  }
+
+  const lines = translatedText.split("\n");
+  let pinned = 0;
+  for (const [index, heading] of translated.headings.entries()) {
+    const site = translated.sites[index];
+    const sourceId = source.headings[index]?.slug;
+    if (
+      !site ||
+      site.pinned ||
+      sourceId === undefined ||
+      heading.slug === sourceId
+    ) {
+      continue;
+    }
+    lines[site.line - 1] = pinLine(lines[site.line - 1] ?? "", sourceId);
+    pinned += 1;
+  }
+  if (pinned === 0) {
+    return { pinned, text: translatedText };
+  }
+
+  // The pins must reproduce the source ids exactly once rendered; anything
+  // else (a heading the line-based rewrite couldn't reach) keeps the text as
+  // the agent wrote it rather than shipping a half-pinned page.
+  const text = lines.join("\n");
+  const rendered = scanBody(text).headings.map((heading) => heading.slug);
+  const expected = source.headings.map((heading) => heading.slug);
+  if (rendered.join("\n") !== expected.join("\n")) {
+    return {
+      pinned: 0,
+      skipped: "pinned anchors did not reproduce the source heading ids",
+      text: translatedText,
+    };
+  }
+  return { pinned, text };
+};

package/src/translate/validate.ts

@@ -1,4 +1,5 @@
 import matter from "../core/frontmatter.ts";
+import { pinHeadingAnchors } from "./anchors.ts";
 import { TRANSLATABLE_KEY_PATHS } from "./prompts.ts";
 
 /**
@@ -123,13 +124,13 @@ export const validateTranslation = (
     return { ok: false, reason: "frontmatter does not parse as YAML" };
   }
 
-  const body = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));
-  if (body.trim() === "") {
+  const rawBody = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));
+  if (rawBody.trim() === "") {
     return { ok: false, reason: "translation has an empty body" };
   }
 
   const sourceFences = countFenceLines(source.content);
-  const candidateFences = countFenceLines(body);
+  const candidateFences = countFenceLines(rawBody);
   if (sourceFences !== candidateFences) {
     return {
       ok: false,
@@ -137,6 +138,10 @@ export const validateTranslation = (
     };
   }
 
+  // Anchors stay identical across languages: each translated heading is
+  // pinned to its source heading's id (see `anchors.ts`).
+  const body = pinHeadingAnchors(source.content, rawBody).text;
+
   if (!sourceHasFrontmatter) {
     // A frontmatter-less source writes the body alone; any frontmatter the
     // agent invented is dropped with it.