blume 1.0.2 → 1.0.4

package/src/markdown/table-wrap.ts

@@ -0,0 +1,43 @@
+/**
+ * Wraps each `<table>` in a scroll container. Satteri does not re-descend into a
+ * visitor's returned replacement, so the wrapped table is not re-visited.
+ *
+ * The wrapper carries `tabindex="0"` so a horizontally scrolling table is
+ * reachable and scrollable by keyboard, not just pointer (WCAG 2.1.1; axe's
+ * `scrollable-region-focusable`). It's added unconditionally — whether a given
+ * table overflows isn't known at build time — which costs a tab stop on tables
+ * that happen to fit; no ARIA label is set to avoid an untranslated string.
+ */
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface TableWrapPlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode) => HastNode;
+  };
+}
+
+export const tableWrapPlugin = (): TableWrapPlugin => ({
+  element: {
+    filter: ["table"],
+    visit(node) {
+      return {
+        children: [node],
+        properties: { className: ["blume-table-scroll"], tabIndex: 0 },
+        tagName: "div",
+        type: "element",
+      };
+    },
+  },
+  name: "blume:table-wrap",
+});

package/src/og/card.ts

@@ -35,6 +35,17 @@ const resolveAccent = (accent: string): string => {
   return HEX_COLOR.test(accent) ? accent : "#3b82f6";
 };
 
+const resolveColor = (color: string | undefined, fallback: string): string =>
+  color && HEX_COLOR.test(color) ? color : fallback;
+
+export interface OgCardPalette {
+  accent?: string;
+  background?: string;
+  border?: string;
+  foreground?: string;
+  muted?: string;
+}
+
 export interface OgCardOptions {
   /** Large headline — the page title. */
   title: string;
@@ -45,10 +56,12 @@ export interface OgCardOptions {
   /** Muted subtitle under the headline (usually the site description). */
   description?: string;
   /**
-   * Inlined SVG markup of the configured logo (`config.logo.svg`), painted into
+   * Inlined SVG markup of the configured logo, painted into
    * the brand lockup. Falls back to an accent mark when absent.
    */
   logo?: string;
+  /** Optional colors for the generated card. */
+  palette?: OgCardPalette;
   /** Footer-left repository slug, e.g. `owner/repo`. */
   repo?: string;
   /** Footer-right site host, e.g. `docs.acme.com`. */
@@ -67,6 +80,17 @@ const MUTED = "#737373";
 const FAINT = "#a3a3a3";
 const BORDER = "#e5e5e5";
 
+const resolvePalette = (
+  options: OgCardOptions
+): Required<OgCardPalette> & { faint: string } => ({
+  accent: resolveAccent(options.palette?.accent ?? options.accent ?? "blue"),
+  background: resolveColor(options.palette?.background, BG),
+  border: resolveColor(options.palette?.border, BORDER),
+  faint: resolveColor(options.palette?.muted, FAINT),
+  foreground: resolveColor(options.palette?.foreground, FOREGROUND),
+  muted: resolveColor(options.palette?.muted, MUTED),
+});
+
 /**
  * Truncate to `max` code points with an ellipsis. Slices by code points, not
  * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
@@ -103,8 +127,8 @@ const logoAspect = (svg: string): number | null => {
 // Render the configured logo as the brand mark. A `currentColor` logo carries
 // no intrinsic color, so it is painted in the foreground to read on the light
 // card, then handed to Takumi as a data URI sized from the SVG's aspect ratio.
-const logoMark = (svg: string): Node => {
-  const painted = svg.replaceAll("currentColor", FOREGROUND);
+const logoMark = (svg: string, foreground: string): Node => {
+  const painted = svg.replaceAll("currentColor", foreground);
   const aspect = logoAspect(painted);
   let height = MARK_HEIGHT;
   let width = aspect ? MARK_HEIGHT * aspect : MARK_HEIGHT;
@@ -151,7 +175,8 @@ const titleSize = (title: string): number => {
 
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
-  const accent = resolveAccent(options.accent ?? "blue");
+  const { accent, background, border, faint, foreground, muted } =
+    resolvePalette(options);
   const brand = options.brand?.trim();
   const logo = options.logo?.trim();
   // Slice by code point, not code unit — `charAt(0)` would split a leading
@@ -166,14 +191,16 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   // ("Ultracite  Ultracite"). Without a logo, the accent tile with the brand
   // initial stands in.
   const header = container({
-    children: [logo ? logoMark(logo) : initialMark(accent, initial)],
+    children: [
+      logo ? logoMark(logo, foreground) : initialMark(accent, initial),
+    ],
     style: { alignItems: "center", display: "flex" },
   });
 
   const body = container({
     children: [
       text(truncate(options.title, 64), {
-        color: FOREGROUND,
+        color: foreground,
         fontSize: titleSize(options.title),
         fontWeight: 600,
         letterSpacing: "-0.03em",
@@ -183,7 +210,7 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
       }),
       description
         ? text(truncate(description, 140), {
-            color: MUTED,
+            color: muted,
             fontSize: 30,
             lineHeight: 1.4,
             marginTop: 28,
@@ -200,15 +227,15 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
       ? container({
           children: [
             container({
-              style: { backgroundColor: BORDER, height: 1, width: "100%" },
+              style: { backgroundColor: border, height: 1, width: "100%" },
             }),
             container({
               children: [
                 repo
-                  ? text(repo, { color: MUTED, fontSize: 22 })
+                  ? text(repo, { color: muted, fontSize: 22 })
                   : container({}),
                 site
-                  ? text(site, { color: FAINT, fontSize: 22 })
+                  ? text(site, { color: faint, fontSize: 22 })
                   : container({}),
               ],
               style: {
@@ -227,8 +254,8 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const node = container({
     children: [header, body, footer],
     style: {
-      backgroundColor: BG,
-      color: FOREGROUND,
+      backgroundColor: background,
+      color: foreground,
       display: "flex",
       flexDirection: "column",
       height: HEIGHT,

package/src/og/index.ts

@@ -1,2 +1,2 @@
 export { renderOgImage } from "./card.ts";
-export type { OgCardOptions } from "./card.ts";
+export type { OgCardOptions, OgCardPalette } from "./card.ts";

package/src/og/logo.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { join } from "pathe";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+
+/** Resolve a configured local SVG for use in generated Open Graph cards. */
+export const resolveOgLogo = (
+  project: BlumeProject,
+  source: string | undefined
+): string | undefined => {
+  if (!source?.toLowerCase().endsWith(".svg")) {
+    return;
+  }
+  const relative = source.replace(/^\//u, "");
+  const file = [
+    join(project.context.root, "public", relative),
+    join(project.context.root, relative),
+  ].find((path) => existsSync(path));
+  return file ? readFileSync(file, "utf-8") : undefined;
+};

package/src/openapi/references.ts

@@ -1,14 +1,13 @@
 import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar, trimEnd } from "../core/trim.ts";
-import type { NavTab } from "../core/types.ts";
 
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
- * labels, and a renderer choice — no file IO, so the content source, the nav
- * tabs, the Scalar page generator, and the `blume:openapi` data module all share
- * one source of truth. Kept free of any Astro/template imports so `core` can
- * depend on it without a cycle.
+ * labels, and a renderer choice — no file IO, so the content source, the
+ * nav-target validation, the Scalar page generator, and the `blume:openapi`
+ * data module all share one source of truth. Kept free of any Astro/template
+ * imports so `core` can depend on it without a cycle.
  */
 
 export type ReferenceKind = "openapi" | "asyncapi";
@@ -155,18 +154,22 @@ export const resolveReferences = (
   ),
 ];
 
-/** Nav tabs (header links) for every reference, regardless of renderer. */
-export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
-  resolveReferences(config).map((ref) => ({
-    label: ref.label,
+/**
+ * Mounted route for every reference, regardless of renderer. References no
+ * longer add a header tab automatically — authors point a `navigation.tabs`
+ * entry at one of these routes to surface it (and, for Blume-rendered specs, to
+ * scope its operations sidebar). These routes are whitelisted as valid nav
+ * targets so such a tab doesn't read as a broken link.
+ */
+export const referenceRoutes = (config: ResolvedConfig): string[] =>
+  resolveReferences(config).map((ref) =>
     // Blume-rendered operation pages flow through the content pipeline and are
-    // mounted under `basePath`, so their tab must be too. Scalar references are
-    // a single embedded page injected at the raw `route`, left root-anchored.
-    path:
-      ref.renderer === "blume"
-        ? withBasePath(config.basePath, ref.route)
-        : ref.route,
-  }));
+    // mounted under `basePath`. Scalar references are a single embedded page
+    // injected at the raw `route`, left root-anchored.
+    ref.renderer === "blume"
+      ? withBasePath(config.basePath, ref.route)
+      : ref.route
+  );
 
 /**
  * Accept one resolved reference into the deduped Blume-rendered set, or return

package/src/registry/eject.ts

@@ -20,6 +20,7 @@ import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
   askEndpointTemplate,
+  askComponentTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
@@ -135,8 +136,8 @@ const hostsMcp = (
   project: BlumeProject,
   userPages: { pattern: string }[]
 ): boolean =>
-  project.config.mcp.enabled &&
-  !routeIsTaken(userPages, project.graph.pages, project.config.mcp.route);
+  project.config.ai.mcp.enabled &&
+  !routeIsTaken(userPages, project.graph.pages, project.config.ai.mcp.route);
 
 /**
  * The `.well-known` MCP discovery routes, injected as prerendered pages
@@ -174,7 +175,7 @@ const mcpFiles = async (
   if (!hostsMcp(project, userPages)) {
     return [];
   }
-  const { route } = project.config.mcp;
+  const { route } = project.config.ai.mcp;
   const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
@@ -356,6 +357,7 @@ export const eject = async (
   }[] = [
     {
       content: astroConfigTemplate({
+        askPath: "./src/generated/Ask.astro",
         config,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
@@ -390,7 +392,6 @@ export const eject = async (
     },
     {
       content: catchAllPageTemplate({
-        askEnabled,
         exportEpub,
         exportPdf,
         mathEnabled: usesMath,
@@ -441,6 +442,12 @@ export const eject = async (
       path: join(genDir, "app.css"),
     },
     { content: buildRuntimeData(project), path: join(genDir, "data.json") },
+    // The header's Ask trigger behind the `blume:ask` alias. Always written — it
+    // renders nothing when Ask is off — so the alias always resolves.
+    {
+      content: askComponentTemplate(askEnabled),
+      path: join(genDir, "Ask.astro"),
+    },
     {
       content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
       path: join(genDir, "openapi.json"),
@@ -475,7 +482,6 @@ export const eject = async (
   files.push(
     ...(await mcpFiles(project, pages, srcDir, genDir)),
     ...changelogFiles(project, pages, srcDir, {
-      askEnabled,
       exportEpub,
       exportPdf,
       needsReact,

package/src/theme/entry.ts

@@ -16,6 +16,15 @@ interface TailwindEntryOptions {
 const DARK_VARIANT = `/* Dark mode is driven by data-theme on the <html> element. */
 @custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));`;
 
+/** Keep browser-provided UI in sync with the active theme in both sheets. */
+const COLOR_SCHEME_DEFAULTS = `:root {
+  color-scheme: light;
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+}`;
+
 /**
  * The default `--blume-*` design tokens (light + dark), shared by the app
  * sheet and the isolated example-preview sheet so previews inherit the site's
@@ -141,6 +150,8 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 
 ${DARK_VARIANT}
 
+${COLOR_SCHEME_DEFAULTS}
+
 ${TOKEN_DEFAULTS}
 
 ${THEME_MAPPING}
@@ -386,13 +397,16 @@ blume-diff {
 
 /* Language icon (simple-icons) sits at the header's left edge; the label shifts
    right to make room. Injected at build time by the language-icon transformer.
-   Shown only for top-level prose blocks, which have a header — flush code in
-   tabs and API panels is nested deeper, so the child combinator skips it. */
+   The icon is gated on data-language (the header bar), not just data-icon: the
+   transformer runs whenever icons are on, but a header-less standalone
+   CodeBlock (no title) never gets data-language, so without this gate the
+   absolutely-positioned icon would overlap the first code line. Fenced code
+   and titled blocks always have a header, so the icon shows there. */
 .blume-lang-icon {
   display: none;
 }
 
-.prose > :where(pre[data-icon]) > .blume-lang-icon {
+.prose > :where(pre[data-language][data-icon]) > .blume-lang-icon {
   color: var(--blume-muted-foreground);
   display: block;
   height: 0.875rem;
@@ -402,7 +416,7 @@ blume-diff {
   width: 0.875rem;
 }
 
-.prose > :where(pre[data-icon])::before {
+.prose > :where(pre[data-language][data-icon])::before {
   padding-left: 2.5rem;
 }
 
@@ -453,11 +467,40 @@ blume-diff {
   font-size: 0.8125rem;
 }
 
+/* Scroll wide tables in place; the wrapper is added by the blume:table-wrap hast
+   plugin. The border+radius frames the scroll viewport so a clipped wide table
+   reads as scrollable rather than cut off, and carries the table's vertical
+   rhythm (the inner table's own margin is zeroed so it fills the frame). */
+.blume-table-scroll {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  margin: 1.5rem 0;
+  border: 1px solid var(--blume-border);
+  border-radius: var(--blume-radius);
+}
+.blume-table-scroll > table {
+  margin: 0;
+}
+/* Restore inner padding on every cell. Typography zeroes the first/last cell's
+   inline padding so a borderless table aligns to the prose margin; inside the
+   framed wrapper that leaves edge text touching the border. The :is() selector
+   outweighs Typography's :where()-scoped rules so the outer columns get it too. */
+.blume-table-scroll :is(th, td) {
+  padding: 0.5rem 0.75rem;
+}
+/* Keep column labels on one line so a two-word header does not wrap into a
+   ragged stack; the table just scrolls a little wider instead. Body cells keep
+   wrapping so a wide table stays a scroll away, not an endless horizontal run. */
+.blume-table-scroll th {
+  white-space: nowrap;
+}
+
 /* GFM renders cells as <td><code> directly, which the descendant form alone
    never matches (a cell is not its own descendant). */
 .prose :where(td, th) > code,
 .prose :where(td, th) :not(pre) > code {
-  white-space: nowrap;
+  overflow-wrap: break-word;
+  white-space: normal;
 }
 
 blume-tabs pre,
@@ -717,6 +760,8 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 
 ${DARK_VARIANT}
 
+${COLOR_SCHEME_DEFAULTS}
+
 ${TOKEN_DEFAULTS}
 
 ${THEME_MAPPING}