blume 1.6.2 → 1.6.4

package/src/core/locale-links.ts

@@ -0,0 +1,163 @@
+import {
+  isInternalPath,
+  normalizePath,
+  stripBasePath,
+  withBasePath,
+} from "./base-path.ts";
+import { localePrefix, localizeRoute } from "./i18n.ts";
+import type { LocaleRouting } from "./i18n.ts";
+
+/**
+ * Locale-aware resolution of content links.
+ *
+ * Authors write internal links as if mounted at the default locale's root
+ * (`[x](/guide)`, `<Card href="/guide">`), and translated pages are usually
+ * copies of the source with the same links — so read on `/fr/…`, a link would
+ * otherwise drop the reader back into the default language. These helpers move
+ * such a link to the reader's locale (`/fr/guide`) when that route is served
+ * (a real translation or a materialized fallback page), and leave it alone
+ * otherwise: an explicit cross-locale link (`/de/guide`), a custom `.astro`
+ * page or generated route that has no per-locale variant, or a missing
+ * translation on a site with fallbacks disabled all keep their authored
+ * target rather than pointing at a 404.
+ *
+ * The rewrite runs at render time (`components/layout/LocaleLinks.astro`)
+ * because content is compiled once per file but served per route: a fallback
+ * route renders the fallback locale's file under the missing locale's URL, and
+ * a shared `page.$.mdx` renders under every locale. The link checker applies
+ * the same resolution so anchors are validated against the page a reader lands
+ * on.
+ */
+
+/** A route set, as the runtime (`Set`) or the checker (a predicate) sees it. */
+export interface RouteSet {
+  has: (route: string) => boolean;
+}
+
+export interface LocalizeLinkOptions {
+  /** Site-wide route mount point (`""` or `/seg`); routes carry it. */
+  basePath: string;
+  i18n: LocaleRouting;
+  /** Locale of the page the link is rendered on. */
+  locale: string;
+  /** Every served route, base-prefixed like `path` (no `deployment.base`). */
+  routes: RouteSet;
+}
+
+/**
+ * Mirrors the asset heuristic in `markdown/base-links.ts`: a path whose final
+ * segment carries a file extension is a `public/` asset (or a raw `.md` twin),
+ * served at the site root and never localized.
+ */
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Decode a percent-encoded path for a route lookup; leave junk as-is. */
+const decodePercent = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/** Whether `path` (base-stripped) already sits under some locale's prefix. */
+const hasLocalePrefix = (path: string, i18n: LocaleRouting): boolean =>
+  i18n.locales.some((locale) => {
+    const prefix = localePrefix(locale.code, i18n);
+    return prefix !== "" && (path === prefix || path.startsWith(`${prefix}/`));
+  });
+
+/**
+ * Move a base-prefixed, fragment-less internal path into `locale` when that
+ * route is served, else return it unchanged. Idempotent: a path already under
+ * any configured locale prefix is never re-prefixed.
+ */
+export const localizeLinkPath = (
+  path: string,
+  options: LocalizeLinkOptions
+): string => {
+  const { basePath, i18n, locale, routes } = options;
+  if (localePrefix(locale, i18n) === "") {
+    return path;
+  }
+  const rest = normalizePath(stripBasePath(basePath, path));
+  if (hasLocalePrefix(rest, i18n)) {
+    return path;
+  }
+  const localized = withBasePath(basePath, localizeRoute(rest, locale, i18n));
+  // Routes are stored decoded; a browser-copied `/caf%C3%A9` must still find
+  // its translation, but the emitted href keeps the author's encoding.
+  return routes.has(localized) || routes.has(decodePercent(localized))
+    ? localized
+    : path;
+};
+
+export interface LocalizeHrefOptions extends LocalizeLinkOptions {
+  /** `deployment.base` (Astro's `BASE_URL`), layered over `basePath` in hrefs. */
+  deployBase: string;
+}
+
+/**
+ * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
+ * asset links pass through; a root-relative page link keeps its `?query` and
+ * `#fragment` and its `deployment.base` layer around the localized path.
+ */
+export const localizeHref = (
+  href: string,
+  options: LocalizeHrefOptions
+): string => {
+  if (!isInternalPath(href)) {
+    return href;
+  }
+  const suffixAt = href.search(/[#?]/u);
+  const path = suffixAt === -1 ? href : href.slice(0, suffixAt);
+  const suffix = suffixAt === -1 ? "" : href.slice(suffixAt);
+  if (ASSET_PATH.test(path)) {
+    return href;
+  }
+  const based = stripBasePath(options.deployBase, path);
+  const localized = localizeLinkPath(based, options);
+  if (localized === based) {
+    return href;
+  }
+  return `${withBasePath(options.deployBase, localized)}${suffix}`;
+};
+
+/** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */
+const ANCHOR_TAG = /<a\s[^>]*>/giu;
+/** The tag's `href` attribute, double- or single-quoted. */
+const HREF_ATTR = /(?<attr>\shref=)(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/iu;
+
+/**
+ * Rewrite every `<a href>` in rendered content HTML through `rewrite`. Code
+ * blocks are HTML-escaped (`&lt;a`), and island props live on
+ * `<astro-island>`, so neither is touched.
+ */
+export const localizeContentLinks = (
+  html: string,
+  rewrite: (href: string) => string
+): string =>
+  html.replace(ANCHOR_TAG, (tag) =>
+    tag.replace(HREF_ATTR, (_match, attr: string, dq?: string, sq?: string) => {
+      const quote = dq === undefined ? "'" : '"';
+      return `${attr}${quote}${rewrite(dq ?? sq ?? "")}${quote}`;
+    })
+  );
+
+/**
+ * The served route set for `blume:data`'s routes, built once per routes array
+ * (the virtual module is evaluated once, so every page render shares it).
+ */
+const routeSets = new WeakMap<readonly { path: string }[], Set<string>>();
+
+export const routeSetFor = (
+  routes: readonly { path: string }[]
+): Set<string> => {
+  const cached = routeSets.get(routes);
+  if (cached) {
+    return cached;
+  }
+  const built = new Set(routes.map((route) => route.path));
+  routeSets.set(routes, built);
+  return built;
+};

package/src/core/sources/normalize.ts

@@ -280,6 +280,8 @@ interface HeadingScanState {
   fence: FenceState;
   /** 1-based body line of the line being scanned. */
   line: number;
+  /** Where each heading in `headings` sits, index-aligned. */
+  sites: HeadingSite[];
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
   /** Body line of the first line in `paragraph`. */
@@ -399,23 +401,43 @@ const refDefinitionLabels = (lines: readonly string[]): Set<string> => {
  * regardless of TOC visibility. A heading that is nothing but markers keeps
  * them as literal text, mirroring the renderer.
  */
+/** A scanned heading plus whether its id came from an author pin. */
+interface ScannedHeading {
+  heading: Heading;
+  pinned: boolean;
+}
+
 const toHeading = (
   depth: number,
   raw: string,
   slugger: GithubSlugger,
   isRefDefined: (label: string) => boolean
-): Heading => {
+): ScannedHeading => {
   const unescaped = raw.replaceAll(ESCAPED_PUNCTUATION, "$<char>");
   const markers = parseHeadingMarkers(unescaped, isRefDefined);
   const text = markers.text.trim();
   if (text === "" && (markers.id !== undefined || markers.toc !== undefined)) {
-    return { depth, slug: slugger.slug(unescaped), text: unescaped };
+    return {
+      heading: { depth, slug: slugger.slug(unescaped), text: unescaped },
+      pinned: false,
+    };
   }
   if (markers.id !== undefined) {
     occupySlug(slugger, markers.id);
-    return { depth, slug: markers.id, text };
+    return { heading: { depth, slug: markers.id, text }, pinned: true };
   }
-  return { depth, slug: slugger.slug(text), text };
+  return { heading: { depth, slug: slugger.slug(text), text }, pinned: false };
+};
+
+/** Record a heading and where a trailing marker would be written for it. */
+const pushHeading = (
+  headings: Heading[],
+  state: HeadingScanState,
+  scanned: ScannedHeading,
+  line: number
+): void => {
+  headings.push(scanned.heading);
+  state.sites.push({ line, pinned: scanned.pinned });
 };
 
 /** Record a heading's unescaped trailing `{#id}` so `.mdx` pages can be warned. */
@@ -444,7 +466,12 @@ const scanContentLine = (
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
     const text = (atx.groups.text ?? "").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line
+    );
     noteCurlyMarker(text, state.line, state);
     state.paragraph = [];
     return;
@@ -455,7 +482,14 @@ const scanContentLine = (
     // a multi-line paragraph renders as one heading, soft breaks as spaces.
     const depth = setext.groups.marker?.startsWith("=") ? 1 : 2;
     const text = state.paragraph.join(" ").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    // A setext heading's markers trail its last text line, just above the
+    // underline — that is where a pin is appended.
+    pushHeading(
+      headings,
+      state,
+      toHeading(depth, text, slugger, isRefDefined),
+      state.line - 1
+    );
     noteCurlyMarker(text, state.paragraphStart, state);
     state.paragraph = [];
     return;
@@ -515,6 +549,14 @@ const scanHeadingLine = (
   scanContentLine(line, state, slugger, headings, isRefDefined);
 };
 
+/** Where a heading's text ends in the scanned text, for appending a marker. */
+export interface HeadingSite {
+  /** 1-based line (of the text passed to `scanBody`) that any trailing marker ends. */
+  line: number;
+  /** True when the heading already pins its id with `[#id]`/`{#id}`. */
+  pinned: boolean;
+}
+
 /** Everything one walk over a body yields for the anchor index. */
 export interface BodyScan {
   /**
@@ -527,6 +569,8 @@ export interface BodyScan {
   /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
   curlyMarkers: CurlyMarker[];
   headings: Heading[];
+  /** Index-aligned with `headings`: where each one's markers would go. */
+  sites: HeadingSite[];
 }
 
 /**
@@ -546,6 +590,7 @@ export const scanBody = (body: string): BodyScan => {
     paragraphStart: 0,
     promptDepth: 0,
     promptTag: false,
+    sites: [],
   };
 
   const { lines, offset } = linesWithoutFrontMatter(body);
@@ -568,7 +613,12 @@ export const scanBody = (body: string): BodyScan => {
       anchors.add(id);
     }
   }
-  return { anchors: [...anchors], curlyMarkers: state.curlyMarkers, headings };
+  return {
+    anchors: [...anchors],
+    curlyMarkers: state.curlyMarkers,
+    headings,
+    sites: state.sites,
+  };
 };
 
 export const extractHeadings = (body: string): Heading[] =>

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/code-block-padding.ts

@@ -6,11 +6,3 @@
 
 /** Top and bottom inset of a plain prose block with no chrome, in rem. */
 export const CODE_PADDING_BLOCK_REM = 1;
-
-/**
- * Top inset of a flush block — inside tabs or a `not-prose` component, or an
- * untitled block with no language bar — where the layout's copy button is
- * absolutely positioned over the first line: `top-2.5` plus a 1.875rem button
- * lands at 2.5rem, so the first line starts there.
- */
-export const FLUSH_CODE_PADDING_TOP_REM = 2.5;

package/src/theme/entry.ts

@@ -1,7 +1,12 @@
-import {
-  CODE_PADDING_BLOCK_REM,
-  FLUSH_CODE_PADDING_TOP_REM,
-} from "./code-block-padding.ts";
+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 {
   /**
@@ -498,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
@@ -508,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"]
@@ -614,27 +628,19 @@ blume-tabs pre[data-language],
   padding-top: ${CODE_PADDING_BLOCK_REM}rem;
 }
 
-/* Room for the copy button. The docs layout injects it into every \`.prose pre\`
-   — absolutely positioned against the pre's border box, 1.875rem tall, at
-   \`top-2.5\` in the flush contexts above and \`top-2\` elsewhere — and it is
-   unconditional, so wherever no language bar exists to hold it, it painted
-   over the first line of code: any line long enough to reach the button's
-   strip (a curl invocation, an install command, an import path) went under
-   it. Keyed on the attribute the docs layout stamps on <body>, so the strip
-   only appears where the injector runs (PageLayout pages run none), and on
-   \`.astro-code\` so the playground's response pre — created after the
-   injector ran, never given a button — keeps its plain inset. The first
-   selector is the injector's own flush predicate; the second covers the
-   remaining bar-less Shiki case, an untitled <CodeBlock> in plain prose, from
-   first paint. The third covers a raw \`<pre><code>\` written in prose — no
-   \`.astro-code\`, no language bar, but the injector gives it a button all
-   the same — keyed on that injected button, which is exactly what separates
-   it from the playground's pre. API panel blocks match, but their own
-   !important padding wins and they hide the injected button. */
-[data-blume-code-copy] :is(blume-tabs, .not-prose) pre.astro-code,
-[data-blume-code-copy] .prose pre.astro-code:not([data-language]),
-[data-blume-code-copy] .prose pre:not([data-language]):has(> [data-blume-copy]) {
-  padding-top: ${FLUSH_CODE_PADDING_TOP_REM}rem;
+/* Where no language bar holds the copy button — a flush block in tabs or a
+   not-prose component, a bar-less block in prose — the docs layout still pins
+   one over the block's top-right corner, so a first line long enough to reach
+   it would end underneath. A code switcher (CodeGroup, ts2js) hosts the button
+   in its tab strip instead and needs nothing here; for every block that keeps
+   an overlay button, give the scrolling code element enough end padding that
+   the line's tail clears the button at the end of its scroll. Keyed on the
+   injected button itself (which the playground's client-created response pre
+   never gets), and \`.prose\`-scoped to outrank the base \`:where(pre code)\`
+   inset. Not a vertical inset — that reserved a strip above every one-line
+   command and read as a rendering bug. */
+.prose :is(blume-tabs pre, .not-prose pre, pre:not([data-language])):not(.twoslash, .twoslash pre, blume-panel-tabs *):has(> [data-blume-copy]) > code {
+  padding-inline-end: 3.5rem;
 }
 
 blume-tabs pre[data-language]::before,