blume 1.7.3 → 2.0.0

package/src/deploy/platforms/vercel.ts

@@ -0,0 +1,193 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import { crossOriginDiscoveryPaths } from "../../ai/ai-catalog.ts";
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  hasApiCatalog,
+} from "../../ai/api-catalog.ts";
+import { buildHomeLinkHeader } from "../../ai/link-headers.ts";
+import {
+  agentMarkdown,
+  buildRawMarkdown,
+  markdownRoutePaths,
+  markdownTokenCount,
+} from "../../ai/markdown.ts";
+import {
+  SIGNATURES_DIRECTORY_PATH,
+  SIGNATURES_DIRECTORY_TYPE,
+} from "../../ai/web-bot-auth.ts";
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ProjectContext } from "../../core/types.ts";
+import { VERCEL_ADAPTER_PACKAGE } from "../adapters/vercel.ts";
+import {
+  addDevDependencyCommand,
+  auditVercelFunctions,
+  blumeDependencyNames,
+  functionBundleVerdict,
+} from "../function-bundle.ts";
+import { buildVercelConfig } from "../redirects.ts";
+import { injectNegotiationRoutes } from "../vercel-negotiation.ts";
+import { adapterRoot, toSiteUrl } from "./paths.ts";
+import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
+
+/** `vercel.json` with a `redirects` array, for a static deploy of `dist/`. */
+export const VERCEL_JSON_FILE: RedirectFile = {
+  build: buildVercelConfig,
+  name: "vercel.json",
+};
+
+/**
+ * The Build Output tree. The adapter is shown the project root (see
+ * `hiddenRuntime.showProjectRoot`), so for a real build this is
+ * `<project>/.vercel/output`; an isolated build keeps it under the relocated
+ * runtime.
+ */
+const buildOutputDir = (context: ProjectContext): string =>
+  join(adapterRoot(context), ".vercel", "output");
+
+/**
+ * Refuse to ship a function bundle that would crash at runtime: a bare import
+ * the adapter's dependency trace silently dropped (see
+ * `deploy/function-bundle.ts`). A missing package that is one of Blume's own
+ * dependencies is fatal — the generated runtime imports it, so every request
+ * would die; a project's own external import is reported as a warning and
+ * left to the author. Resolves to whether the bundle may ship.
+ */
+export const checkVercelFunctionBundles = async (
+  outputDir: string,
+  root: string,
+  log: BuildLog
+): Promise<boolean> => {
+  const audits = await auditVercelFunctions(outputDir);
+  const own = blumeDependencyNames();
+  // The remedy names the project's own package manager (`pnpm add -D`, …).
+  const addDevCommand = await addDevDependencyCommand(root);
+  let fatal = false;
+  for (const audit of audits) {
+    const verdict = functionBundleVerdict(audit, root, own, addDevCommand);
+    if (verdict.fatal) {
+      fatal = true;
+      log.error(verdict.message);
+    } else {
+      log.warn(verdict.message);
+    }
+  }
+  return !fatal;
+};
+
+/**
+ * Splice `Accept: text/markdown` negotiation routes into the adapter's Build
+ * Output config, so a content-page request that prefers Markdown gets the
+ * page's prerendered `.md` mirror (content pages are prerendered even in
+ * server output, so Astro middleware never sees them — the routing layer is
+ * the only request-time hook). The adapter writes the config straight to the
+ * root it was shown.
+ */
+export const emitVercelNegotiation = async (
+  project: BlumeProject,
+  log: BuildLog
+): Promise<void> => {
+  const { config, context } = project;
+  const outputDir = buildOutputDir(context);
+  const configPath = join(outputDir, "config.json");
+  if (!existsSync(configPath)) {
+    return;
+  }
+  const routePaths = markdownRoutePaths(project);
+  const overrides: Record<string, string> = {};
+  if (hasApiCatalog(config)) {
+    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+  }
+  if (config.agents.webBotAuth.keys.length > 0) {
+    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+  }
+  // The homepage rewrite serves `/index.md` from the static layer, so its
+  // `x-markdown-tokens` estimate has to ride the routing config; the runtime
+  // endpoint stamps it on dev/server-rendered responses itself.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const home = rawMarkdown["/"];
+  // The Markdown and JSON 404 routes point at the prerendered twins; only
+  // wire each when the build actually emitted it (a project that owns `/404`
+  // gets none).
+  const staticDir = join(outputDir, "static");
+  const injected = injectNegotiationRoutes(
+    await readFile(configPath, "utf-8"),
+    routePaths,
+    buildHomeLinkHeader(config, routePaths),
+    overrides,
+    home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+    {
+      json: existsSync(join(staticDir, "404.json")),
+      markdown: existsSync(join(staticDir, "404.md")),
+    },
+    crossOriginDiscoveryPaths(config)
+  );
+  if (injected === null) {
+    log.warn(
+      "Could not wire Accept: text/markdown negotiation into .vercel/output/config.json — raw Markdown stays available at the .md URLs."
+    );
+    return;
+  }
+  await writeFile(configPath, injected, "utf-8");
+  log.success(
+    "Wired Accept: text/markdown negotiation into the Vercel routing config"
+  );
+};
+
+/**
+ * Vercel. A server build's Build Output tree lands at `.vercel/output` — at
+ * the project root, because the adapter is handed that root up front: its
+ * `@vercel/nft` dependency trace is rooted there too, and tracing from the
+ * hidden runtime silently drops the function's chunks and `node_modules`.
+ * Static assets are served from the tree's `static/` half, so the deploy
+ * artifacts are written there; headers arrive through the routing config
+ * rather than a `_headers` file, which Vercel never reads.
+ */
+export const vercelPlatform: DeployPlatform = {
+  astro: {
+    config: {},
+    options: () => ({}),
+    package: VERCEL_ADAPTER_PACKAGE,
+  },
+  env: {
+    detect: (env) => Boolean(env.VERCEL),
+    // The stable production domain wins over the per-deployment preview URL
+    // so the inferred origin (sitemap, OG, RSS) stays put across deploys;
+    // the chain falls through per resolved value, so an empty
+    // VERCEL_PROJECT_PRODUCTION_URL doesn't dead-end it.
+    site: (env) =>
+      toSiteUrl(env.VERCEL_PROJECT_PRODUCTION_URL) ?? toSiteUrl(env.VERCEL_URL),
+  },
+  finalizeBuild: async ({ isolated, log, project }) => {
+    const { context } = project;
+    const ok = await checkVercelFunctionBundles(
+      buildOutputDir(context),
+      context.root,
+      log
+    );
+    if (!ok) {
+      return false;
+    }
+    // An isolated verify only proves the bundle would ship; the routing
+    // config is a deploy artifact and stays untouched.
+    if (!isolated) {
+      await emitVercelNegotiation(project, log);
+    }
+    return true;
+  },
+  hiddenRuntime: {
+    ignoreDir: ".vercel/",
+    showProjectRoot: true,
+    surfacePath: null,
+  },
+  kind: "vercel",
+  negotiatesMarkdown: true,
+  readsHeaderFiles: { server: false, static: false },
+  redirectFiles: [VERCEL_JSON_FILE],
+  serverOutputDir: buildOutputDir,
+  serverStaticDir: (context) => join(buildOutputDir(context), "static"),
+};

package/src/deploy/redirects.ts

@@ -4,13 +4,14 @@ import {
   withComposedBasePath,
 } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import type { VercelHeader } from "./headers.ts";
 
 /**
  * Platform redirect files for a static build. Astro already emits redirect HTML
- * (meta-refresh) pages for `deployment.output: "static"`, but that's a soft
- * client redirect. These give the host a real HTTP 3xx: Netlify/Cloudflare read
- * `_redirects`, Vercel reads `vercel.json`, and `blume-redirects.json` is a
- * structured manifest for anything else (Apache/nginx rules, an edge worker).
+ * (meta-refresh) pages for static output, but that's a soft client redirect.
+ * These give the host a real HTTP 3xx: Netlify/Cloudflare read `_redirects`,
+ * Vercel reads `vercel.json`, and `blume-redirects.json` is a structured
+ * manifest for anything else (Apache/nginx rules, an edge worker).
  */
 
 type Redirect = ResolvedConfig["redirects"][number];
@@ -78,7 +79,7 @@ export const platformRedirects = (config: ResolvedConfig): Redirect[] =>
   applyBaseToPlatformRedirects(
     config.redirects,
     config.basePath,
-    config.deployment.base ?? ""
+    config.deployment.options.base ?? ""
   );
 
 /** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
@@ -87,24 +88,35 @@ export const buildNetlifyRedirects = (redirects: Redirect[]): string =>
     .map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`)
     .join("\n")}\n`;
 
+/** The `vercel.json` Blume writes for a static deploy of `dist/`. */
+interface VercelConfig {
+  headers?: readonly VercelHeader[];
+  redirects: { destination: string; source: string; statusCode: number }[];
+}
+
 /**
- * `vercel.json` contents with a `redirects` array. Uses `statusCode` (Vercel's
+ * `vercel.json` contents with a `redirects` array, and a `headers` array when
+ * header rules are given (see `buildVercelHeaders`). Uses `statusCode` (Vercel's
  * alternative to the boolean `permanent`) so the configured code ships exactly:
  * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
  * from the `_redirects` file, which preserves exact codes.
  */
-export const buildVercelConfig = (redirects: Redirect[]): string =>
-  `${JSON.stringify(
-    {
-      redirects: redirects.map((redirect) => ({
-        destination: redirect.to,
-        source: redirect.from,
-        statusCode: redirect.status,
-      })),
-    },
-    null,
-    2
-  )}\n`;
+export const buildVercelConfig = (
+  redirects: Redirect[],
+  headers: readonly VercelHeader[] = []
+): string => {
+  const config: VercelConfig = {
+    redirects: redirects.map((redirect) => ({
+      destination: redirect.to,
+      source: redirect.from,
+      statusCode: redirect.status,
+    })),
+  };
+  if (headers.length > 0) {
+    config.headers = headers;
+  }
+  return `${JSON.stringify(config, null, 2)}\n`;
+};
 
 /** Structured manifest for hosts that need manual wiring. */
 export const buildRedirectManifest = (redirects: Redirect[]): string =>

package/src/deploy/robots.ts

@@ -41,16 +41,16 @@ export const buildRobots = (project: BlumeProject): string | null => {
   }
 
   const lines = ["User-agent: *"];
-  const signal = contentSignalLine(config.seo.contentSignals);
+  const signal = contentSignalLine(config.agents.contentSignals);
   if (signal) {
     lines.push(signal);
   }
   lines.push("Allow: /");
 
-  const { site } = config.deployment;
+  const { site } = config.deployment.options;
   if (site && config.seo.sitemap) {
     const sitemapPath = withBasePath(
-      normalizeBasePath(config.deployment.base),
+      normalizeBasePath(config.deployment.options.base),
       "/sitemap.xml"
     );
     lines.push("", `Sitemap: ${absoluteUrl(site, sitemapPath)}`);

package/src/deploy/rss.ts

@@ -52,7 +52,7 @@ const pageDate = (page: PageRecord): Date | undefined => {
 export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   const { config } = project;
   const { rss } = config.seo;
-  const { site } = config.deployment;
+  const { site } = config.deployment.options;
   if (!(rss.enabled && site)) {
     return [];
   }
@@ -60,7 +60,7 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   // The feed's own `link`/self URL points at the docs root under that base, while
   // `path` stays base-less (it's also the on-disk output location).
-  const deployBase = normalizeBasePath(config.deployment.base);
+  const deployBase = normalizeBasePath(config.deployment.options.base);
   const rootLink = `${base}${deployBase}`;
 
   const feeds: RssFeed[] = [];

package/src/deploy/sitemap.ts

@@ -72,14 +72,14 @@ ${urls.join("\n")}
 export const buildSitemapFiles = (
   project: BlumeProject
 ): SitemapFile[] | null => {
-  const { site } = project.config.deployment;
+  const { site } = project.config.deployment.options;
   if (!(site && project.config.seo.sitemap)) {
     return null;
   }
 
   const base = siteRoot(site);
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
-  const deployBase = normalizeBasePath(project.config.deployment.base);
+  const deployBase = normalizeBasePath(project.config.deployment.options.base);
 
   // Archived-version pages leave the sitemap when the version is noindexed,
   // or when their canonical points at a still-existing latest equivalent —

package/src/deploy/vercel-negotiation.ts

@@ -1,8 +1,8 @@
 /**
  * `Accept: text/markdown` content negotiation for Vercel server builds.
  *
- * Blume prerenders every content page — even under `deployment.output:
- * "server"` — so a page request never reaches Astro middleware: Vercel serves
+ * Blume prerenders every content page — even in a server build (`deployment:
+ * vercel()`) — so a page request never reaches Astro middleware: Vercel serves
  * the prerendered HTML straight from its static layer. Request-time negotiation
  * therefore has to live in the platform's routing config. The Vercel adapter
  * emits a Build Output API `config.json`; these helpers splice extra routes

package/src/eval/agents.ts

@@ -48,6 +48,8 @@ export interface HeadlessResult {
 
 export interface HeadlessOptions {
   cwd: string;
+  /** How long the SIGTERM gets before SIGKILL follows (default 5s). */
+  killGraceMs?: number;
   prompt: string;
   timeoutMs: number;
 }
@@ -89,10 +91,14 @@ export const runAgentHeadless = (
       stderr += chunk.toString("utf-8");
     });
 
+    let hardKill: ReturnType<typeof setTimeout> | undefined;
     const deadline = setTimeout(() => {
       timedOut = true;
       child.kill("SIGTERM");
-      const hardKill = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+      hardKill = setTimeout(
+        () => child.kill("SIGKILL"),
+        options.killGraceMs ?? KILL_GRACE_MS
+      );
       hardKill.unref();
     }, options.timeoutMs);
     deadline.unref();
@@ -109,6 +115,9 @@ export const runAgentHeadless = (
     // (an MCP server, a shell) can hold open past the SIGTERM. A timed-out
     // run's output is discarded anyway, so the process dying is enough.
     child.once("exit", (code) => {
+      // Once the process is gone the SIGKILL follow-up has nothing to do, and
+      // firing it later could signal an unrelated process that reused the pid.
+      clearTimeout(hardKill);
       if (timedOut) {
         clearTimeout(deadline);
         resolve({ code: code ?? 1, stderr, stdout, timedOut });
@@ -197,6 +206,27 @@ const claudeArgs = (context: InvocationContext): string[] => {
   ];
 };
 
+/**
+ * Codex config overrides that leave an eval run nothing but its prompt and the
+ * docs MCP tools. `--sandbox read-only` blocks writes and the network but still
+ * lets the shell tool read any file the user can, and the docs a reader
+ * searches — or the answer a judge grades — can come from a remote source, so
+ * an instruction planted there could otherwise pull a local secret into the
+ * transcript sent to the model provider. With both command tools and the
+ * local-image tool off, and any subprocess started with no inherited
+ * environment, there is nothing on the machine for a run to read.
+ */
+const CODEX_LOCKDOWN = [
+  "-c",
+  "features.shell_tool=false",
+  "-c",
+  "features.unified_exec=false",
+  "-c",
+  "tools.view_image=false",
+  "-c",
+  'shell_environment_policy.inherit="none"',
+];
+
 const codexArgs = (context: InvocationContext): string[] => {
   const base = [
     "exec",
@@ -205,6 +235,7 @@ const codexArgs = (context: InvocationContext): string[] => {
     "--ephemeral",
     "--sandbox",
     "read-only",
+    ...CODEX_LOCKDOWN,
     "--output-last-message",
     context.lastMessagePath,
   ];

package/src/eval/findings.ts

@@ -3,7 +3,7 @@ import type { Diagnostic } from "../core/types.ts";
 import { locateQuestion } from "./schema.ts";
 import type { EvalQuestion } from "./schema.ts";
 
-const DOCS_URL = "https://useblume.dev/docs/reference/eval";
+const DOCS_URL = "https://useblume.dev/docs/cli/evals";
 
 /** Where a finding should anchor when no route hint matches a page. */
 export interface EvalsAnchor {
@@ -58,9 +58,12 @@ export interface QuestionOutcome {
 }
 
 /**
- * The diagnostic for a failed or errored question, anchored to the page that
- * should have answered it (via the first matching route hint) or, failing
- * that, to the question's line in the evals file.
+ * The diagnostic for a failed or errored question. A failure is anchored to
+ * the page that should have answered it (via the first matching route hint)
+ * or, failing that, to the question's line in the evals file. An errored run —
+ * the agent crashed, timed out, or answered in a shape Blume couldn't read —
+ * says nothing about the docs, so it always points at the question instead of
+ * a page there's nothing to fix in.
  */
 export const questionFinding = (
   question: EvalQuestion,
@@ -68,25 +71,30 @@ export const questionFinding = (
   project: BlumeProject,
   anchor: EvalsAnchor
 ): Diagnostic => {
-  const route = hintedRoute(question, project);
-  const site = route
-    ? { file: route.sourcePath, url: route.path }
-    : { file: anchor.path, line: locateQuestion(anchor.raw, question.id) };
+  const questionSite = {
+    file: anchor.path,
+    line: locateQuestion(anchor.raw, question.id),
+  };
 
   if (outcome.status === "error") {
     return {
       code: "BLUME_EVAL_QUESTION_ERROR",
       docsUrl: DOCS_URL,
-      message: `Eval run failed for "${question.question}"${
+      message: `The agent run failed for "${question.question}"${
         outcome.detail ? ` — ${outcome.detail}` : ""
-      }.`,
+      }, so the docs weren't graded.`,
       severity: question.severity,
       suggestion:
         "Rerun `blume eval`; if it persists, check the agent CLI installation and the failure detail.",
-      ...site,
+      ...questionSite,
     };
   }
 
+  const route = hintedRoute(question, project);
+  const site = route
+    ? { file: route.sourcePath, url: route.path }
+    : questionSite;
+
   const missing =
     outcome.missing.length > 0
       ? ` — missing: ${outcome.missing.join("; ")}`

package/src/eval/report.ts

@@ -94,7 +94,11 @@ export const headerLine = (total: number, agent: EvalResult["agent"]): string =>
 export const startLine = (id: string, index: number, total: number): string =>
   `  ${colors.dim(`▸ ${id} (${index + 1}/${total})`)}`;
 
-/** `fix:` pointers for failed questions, naming the file that resolves each. */
+/**
+ * `fix:` pointers for failed questions, naming the file that resolves each. A
+ * question whose agent run errored gets a `run failed:` line pointing at the
+ * question instead: the run never graded the docs, so there's no page to fix.
+ */
 export const fixLines = (result: EvalResult, root: string): string[] =>
   result.diagnostics
     .filter((diagnostic) => diagnostic.code !== "BLUME_EVAL_ROUTE_UNKNOWN")
@@ -102,7 +106,11 @@ export const fixLines = (result: EvalResult, root: string): string[] =>
       const site = finding.file
         ? `${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
         : "";
-      return `  ${colors.cyan("fix:")} ${site} ${colors.dim(finding.message)}`;
+      const label =
+        finding.code === "BLUME_EVAL_QUESTION_ERROR"
+          ? colors.red("run failed:")
+          : colors.cyan("fix:");
+      return `  ${label} ${site} ${colors.dim(finding.message)}`;
     });
 
 /** Dim warnings for route hints that no longer match a page. */

package/src/markdown/external-links.ts

@@ -0,0 +1,65 @@
+/**
+ * Opens external Markdown links in a new tab (`markdown.externalLinks`). A
+ * Satteri hast plugin: every `<a>` whose href passes the shared
+ * `isExternalUrl` predicate — the one behind the header actions and featured
+ * sidebar links — gets `target="_blank"`, `rel="noreferrer"`, an
+ * `aria-describedby` pointing at the layout's hidden "Opens in a new tab"
+ * element, and a `data-blume-external` marker the theme draws the arrow icon
+ * from. So a Markdown link and a chrome link to the same place behave alike.
+ *
+ * Site routes, fragments, relative paths, and other schemes (`mailto:`,
+ * `tel:`) stay in the current tab. Raw `<a>` tags written in Markdown, and JSX
+ * or components in MDX, keep whatever attributes their author gave them. Only
+ * constructed when the option is on (see `markdown/index.ts`).
+ */
+
+import { isExternalUrl } from "../core/base-path.ts";
+import { NEW_TAB_HINT_ID } from "../core/new-tab.ts";
+
+/** A hast property value: an attribute primitive or a token list. */
+type HastPropertyValue = string | number | boolean | (string | number)[];
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  properties?: Record<string, HastPropertyValue>;
+  tagName?: string;
+  type: string;
+}
+
+/**
+ * The slice of Satteri's hast visitor context this plugin needs. Satteri
+ * serializes an unchanged node by identity, so attributes are recorded via
+ * `setProperty` rather than by mutating `node.properties`.
+ */
+interface HastContext {
+  setProperty: (node: HastNode, key: string, value: HastPropertyValue) => void;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface ExternalLinksPlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: HastContext) => void;
+  };
+}
+
+/** Only a string href can be tested; hast allows numbers and token lists. */
+const isHref = (value: HastPropertyValue | undefined): value is string =>
+  typeof value === "string";
+
+export const externalLinksPlugin = (): ExternalLinksPlugin => ({
+  element: {
+    filter: ["a"],
+    visit(node, ctx) {
+      const href = node.properties?.href;
+      if (isHref(href) && isExternalUrl(href)) {
+        ctx.setProperty(node, "target", "_blank");
+        ctx.setProperty(node, "rel", ["noreferrer"]);
+        ctx.setProperty(node, "ariaDescribedBy", [NEW_TAB_HINT_ID]);
+        ctx.setProperty(node, "dataBlumeExternal", "");
+      }
+    },
+  },
+  name: "blume:external-links",
+});

package/src/markdown/include.ts

@@ -7,7 +7,7 @@ import {
   advanceHtmlCommentState,
   expandIncludeTarget,
   hasIncludeStatements,
-  parseIncludeLine,
+  matchIncludeStatement,
 } from "../core/includes.ts";
 import type { MdastNode, MdastValue } from "./mdast.ts";
 
@@ -151,32 +151,42 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
   };
 
   /**
-   * Splice every statement line in a text block; `null` when none matched.
-   * Statement detection mirrors the string-level scanner's `.md` line rules
-   * (`parseIncludeLine`, HTML comment tracking) so the rendered page and the
-   * indexed/mirrored surfaces agree on which lines splice: a statement inside
-   * `<!-- -->` or indented like code stays verbatim on both sides.
+   * Splice every statement in a text block; `null` when none matched.
+   * Statement detection is the string-level scanner's (`matchIncludeStatement`
+   * with its `.md` rules, plus HTML comment tracking), so the rendered page and
+   * the indexed/mirrored surfaces agree on what splices: a statement inside
+   * `<!-- -->` or indented like code stays verbatim on both sides, and a
+   * wrapped statement splices whole on both.
    */
   const spliceLines = async (
     node: MdastNode,
     text: string,
     ctx: IncludeVisitorContext
   ): Promise<string | null> => {
+    const source = text.split("\n");
+    const pieces: (string | Promise<string>)[] = [];
     let matched = false;
     let inComment = false;
-    const lines = await Promise.all(
-      text.split("\n").map((line) => {
-        const wasInComment = inComment;
-        inComment = advanceHtmlCommentState(line, inComment);
-        const statement = wasInComment ? null : parseIncludeLine(line);
-        if (!statement) {
-          return line;
-        }
-        matched = true;
-        return splice(node, statement, ctx);
-      })
-    );
-    return matched ? lines.join("\n") : null;
+    for (let index = 0; index < source.length; index += 1) {
+      const line = source[index] ?? "";
+      const wasInComment = inComment;
+      inComment = advanceHtmlCommentState(line, inComment);
+      const match = wasInComment
+        ? null
+        : matchIncludeStatement(source, index, "md");
+      if (match?.kind !== "statement") {
+        pieces.push(line);
+        continue;
+      }
+      matched = true;
+      pieces.push(splice(node, match.statement, ctx));
+      index = match.end;
+    }
+    if (!matched) {
+      return null;
+    }
+    const spliced = await Promise.all(pieces);
+    return spliced.join("\n");
   };
 
   return {
@@ -195,17 +205,25 @@ export const includePlugin = (options: IncludePluginOptions = {}) => {
       if (node.name !== "include") {
         return;
       }
-      // The string-level scanner (search, mirrors, llms-full.txt, the HMR
-      // graph) only recognizes single-line statements; a wrapped element
-      // would render content those surfaces never see, so reject it loudly
-      // instead of splicing it invisibly.
+      // A wrapped element splices only when the string-level scanner (search,
+      // mirrors, llms-full.txt, the HMR graph) reads the same lines as one
+      // statement; anything it can't read would render content those surfaces
+      // never see, so it's rejected loudly instead of spliced invisibly.
       const start = node.position?.start?.line;
       const end = node.position?.end?.line;
       if (start !== undefined && end !== undefined && start !== end) {
-        const message =
-          "<include> must be written on a single line: <include>./path.mdx</include>.";
-        ctx.report({ message, node, severity: "warning" });
-        ctx.replaceNode(node, { raw: errorBlock(message) });
+        const lines = ctx.source.split("\n").slice(start - 1, end);
+        const match = matchIncludeStatement(lines, 0, "mdx");
+        if (match.kind !== "statement" || match.end !== lines.length - 1) {
+          const message =
+            "<include> must sit on a line of its own, or wrap with the path on its own line and no blank lines: <include>./path.mdx</include>.";
+          ctx.report({ message, node, severity: "warning" });
+          ctx.replaceNode(node, { raw: errorBlock(message) });
+          return;
+        }
+        ctx.replaceNode(node, {
+          raw: await splice(node, match.statement, ctx),
+        });
         return;
       }
       ctx.replaceNode(node, {