blume 1.0.3 → 1.1.0

package/src/core/schema.ts

@@ -7,6 +7,8 @@ import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
 import type { ContentSource } from "./sources/types.ts";
+import { isStandardSchema } from "./standard-schema.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 
 /**
  * Public Blume schemas.
@@ -514,6 +516,13 @@ const PROVIDER_CONFIG_KEY = {
   typesense: "typesense",
 } as const;
 
+/** Curated link for the search dialog empty state (internal route or external URL). */
+const searchPopularLinkSchema = z.strictObject({
+  href: z.string(),
+  icon: iconName.optional(),
+  label: z.string(),
+});
+
 const searchConfigSchema = z
   .strictObject({
     algolia: algoliaSearchSchema.optional(),
@@ -524,6 +533,8 @@ const searchConfigSchema = z
       .default({}),
     mixedbread: mixedbreadSearchSchema.optional(),
     oramaCloud: oramaCloudSearchSchema.optional(),
+    /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
+    popular: z.array(searchPopularLinkSchema).default([]),
     provider: z.enum(searchProviders).default("orama"),
     typesense: typesenseSearchSchema.optional(),
   })
@@ -672,7 +683,7 @@ const navigationConfigSchema = z.strictObject({
     .transform((value) =>
       Array.isArray(value) ? { display: "flat" as const, items: value } : value
     ),
-  tabs: z.array(navTabSchema).optional(),
+  tabs: z.array(navTabSchema).default([]),
 });
 
 export type AskAiProvider = (typeof askAiProviders)[number];
@@ -802,6 +813,45 @@ const xConfigSchema = z.strictObject({
   handle: xHandleSchema,
 });
 
+/**
+ * Any CSS color. Takumi parses the full grammar, so this stays unvalidated
+ * here and a bad value fails the OG prerender with a parse error naming it —
+ * the same fail-fast the card's accent relies on. Validating hex-only here
+ * would reject `oklch(…)`, which `theme.accent` (the card's default accent)
+ * already accepts.
+ */
+const ogColorSchema = z.string();
+
+const ogPaletteSchema = z.strictObject({
+  accent: ogColorSchema.optional(),
+  background: ogColorSchema.optional(),
+  border: ogColorSchema.optional(),
+  foreground: ogColorSchema.optional(),
+  muted: ogColorSchema.optional(),
+});
+
+/**
+ * A Google Font family to load into the OG card renderer. A bare string is the
+ * family name; the object form pins the weight (a number, a list, or a variable
+ * range like `"100..900"`) and style. Fetched from Google Fonts at build and
+ * handed to Takumi, which does per-glyph fallback so a family covering a script
+ * (e.g. Noto Sans JP for CJK) fixes tofu without touching how Latin renders.
+ */
+const ogFontWeightSchema = z.union([
+  z.number().int().positive(),
+  z.array(z.number().int().positive()),
+  z.string().regex(/^\d+\.\.\d+$/u),
+]);
+const ogFontStyleSchema = z.enum(["normal", "italic"]);
+const ogFontSchema = z.union([
+  z.string(),
+  z.strictObject({
+    name: z.string(),
+    style: z.union([ogFontStyleSchema, z.array(ogFontStyleSchema)]).optional(),
+    weight: ogFontWeightSchema.optional(),
+  }),
+]);
+
 const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
@@ -810,6 +860,16 @@ const ogConfigSchema = z.strictObject({
    * `loadConfig`. An explicit value here always wins.
    */
   enabled: z.boolean().optional(),
+  /**
+   * Google Font families for the generated card, extending Takumi's Latin-only
+   * default so non-Latin titles (CJK, and so on) render instead of tofu.
+   * Fetched from Google Fonts at build.
+   */
+  fonts: z.array(ogFontSchema).optional(),
+  /** Local SVG used in the generated card instead of the site logo. */
+  logo: z.string().optional(),
+  /** Optional generated-card colors. */
+  palette: ogPaletteSchema.optional(),
 });
 
 const rssConfigSchema = z.strictObject({
@@ -1025,6 +1085,41 @@ const asyncapiConfigSchema = z.strictObject({
   theme: z.string().optional(),
 });
 
+/**
+ * Opt-in custom frontmatter keys. `extend` maps each extra key a project's
+ * pages may carry (e.g. `owner`, `reviewedAt`) to a validation schema; the
+ * page schema stays strict for everything else, so typo-catching is preserved.
+ * Schemas are consumed through the Standard Schema `~standard` contract —
+ * never Zod's own API — so the consumer's zod (any version), Valibot, or
+ * ArkType all work (see `standard-schema.ts`). Every declared key is validated
+ * on every page, absent ones included, so a required schema enforces the key
+ * site-wide; mark it `.optional()` to validate only when present. Built-in
+ * frontmatter fields can't be redeclared — they're load-bearing (routing,
+ * sidebar, SEO), and shadowing one would silently change its semantics.
+ */
+const frontmatterConfigSchema = z.strictObject({
+  extend: z
+    .record(
+      z.string(),
+      z.custom<StandardSchema>(isStandardSchema, {
+        message:
+          "Expected a Standard Schema (e.g. a Zod schema — any Zod version works).",
+      })
+    )
+    .default({})
+    .superRefine((value, ctx) => {
+      for (const key of Object.keys(value)) {
+        if (Object.hasOwn(pageMetaBaseSchema.shape, key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `"${key}" is a built-in frontmatter field and cannot be redeclared via frontmatter.extend.`,
+            path: [key],
+          });
+        }
+      }
+    }),
+});
+
 /** Full user-facing config schema. All fields optional with defaults. */
 /**
  * Table-of-contents config. `true`/`false` toggles it; an object narrows the
@@ -1085,6 +1180,8 @@ export const blumeConfigSchema = z.strictObject({
   examples: examplesConfigSchema.default("examples"),
   export: exportConfigSchema.default(false),
   feedback: z.boolean().default(true),
+  /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
+  frontmatter: frontmatterConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
   lastModified: lastModifiedConfigSchema.default(false),
@@ -1103,6 +1200,8 @@ export const blumeConfigSchema = z.strictObject({
 
 /** Resolved config: every field present after defaults are applied. */
 export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
+/** Resolved `frontmatter.extend`: custom key → user-supplied schema. */
+export type FrontmatterExtend = Record<string, StandardSchema>;
 /** Resolved i18n block (present only when the project opts into i18n). */
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */

package/src/core/sources/normalize.ts

@@ -4,10 +4,10 @@ import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
 import { withBasePath } from "../base-path.ts";
-import { diagnosticsFromZod } from "../diagnostics.ts";
+import { diagnosticsFromIssues, diagnosticsFromZod } from "../diagnostics.ts";
 import { localePlacement, localizeRoute } from "../i18n.ts";
 import { pageMetaSchema } from "../schema.ts";
-import type { PageMeta } from "../schema.ts";
+import type { FrontmatterExtend, PageMeta } from "../schema.ts";
 import type { Diagnostic, Heading, PageLink, PageRecord } from "../types.ts";
 import type { NormalizeContext, SourceEntry } from "./types.ts";
 
@@ -131,6 +131,21 @@ const PARAGRAPH_INTERRUPT = /^ {0,3}(?:[-+*][ \t]|\d{1,9}[.)][ \t]|>)/u;
 const THEMATIC_BREAK =
   /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/u;
 const FRONT_MATTER_CLOSE = /^(?:-{3}|\.{3})\s*$/u;
+// `<Prompt>` renders its children into a permanently `hidden` DOM node (see
+// `Prompt.astro`) — the agent-facing prompt text is never visible page
+// content, only read by client JS for the copy button. Any `##` inside it
+// must not surface in the page's heading-derived table of contents. Tracked
+// as an open/close depth, the same way fenced code blocks are tracked above.
+// The opening tag is matched only at the start of a trimmed line: block-level
+// JSX in MDX starts its own line, so a mention mid-prose or mid-heading —
+// "the `<Prompt>` component", `## Using <Prompt>` — never opens a hidden
+// region (an unanchored match here silently ate every heading after the
+// mention). The lookahead rejects longer tag names that share the prefix,
+// like `<PromptCard>` or `<Prompt-Custom>`.
+const PROMPT_OPEN = /^<Prompt(?![\w-])/u;
+// Unanchored: while inside a prompt the close tag may trail the hidden
+// children text (`...copy this.</Prompt>`), not just sit on its own line.
+const PROMPT_CLOSE = /<\/Prompt>/u;
 
 /**
  * The body lines, minus a leading front matter block. Bodies from the
@@ -155,13 +170,46 @@ interface HeadingScanState {
   fence: FenceState;
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
+  /** Nesting depth inside `<Prompt>...</Prompt>` — 0 when outside one. */
+  promptDepth: number;
+  /** True inside a multi-line `<Prompt` opening tag, awaiting its `>`. */
+  promptTag: boolean;
 }
 
+/**
+ * Consume the rest of a `<Prompt` opening tag, scanning a trimmed line from
+ * `start`. The tag's attributes may spread over several lines
+ * (`state.promptTag` carries the search onto the next one), and until the
+ * terminating `>` arrives it isn't known whether the tag even has children —
+ * so the depth only rises once that `>` is found, and not when it turns out
+ * to be `/>` or when the element also closes on the same line
+ * (`<Prompt ...>copy this</Prompt>`). Attribute values containing `>` are not
+ * parsed: the first `>` ends the tag, which errs toward opening a region a
+ * real close tag will still exit.
+ */
+const finishPromptTag = (
+  line: string,
+  start: number,
+  state: HeadingScanState
+): void => {
+  const end = line.indexOf(">", start);
+  if (end === -1) {
+    state.promptTag = true;
+    return;
+  }
+  state.promptTag = false;
+  if (line[end - 1] === "/" || line.includes("</Prompt>", end)) {
+    return;
+  }
+  state.promptDepth += 1;
+};
+
 /**
  * Extract ATX and setext headings from a markdown body, skipping fenced code
- * blocks, exactly as the renderer sees them: ATX headings may be indented up
- * to 3 spaces, and a paragraph underlined with `=`/`-` is a level 1/2 setext
- * heading. Each heading's anchor slug comes from a per-document
+ * blocks and `<Prompt>` children, exactly as the renderer sees them: ATX
+ * headings may be indented up to 3 spaces, and a paragraph underlined with
+ * `=`/`-` is a level 1/2 setext heading. Each heading's anchor slug comes
+ * from a per-document
  * `github-slugger` — the exact slugger the renderer uses
  * (`markdown/heading-anchors`) — advanced over every heading in document
  * order. Matching it (rather than a hand-rolled slugify) keeps the manifest's
@@ -185,6 +233,28 @@ const scanHeadingLine = (
     state.paragraph = [];
     return;
   }
+  // Prompt tags may be indented arbitrarily (MDX has no indented code
+  // blocks), so they match against the trimmed line. A tag line can't also
+  // be a heading, so each just updates the state and moves on, same as a
+  // fence delimiter line. Outside a prompt, a `</Prompt>` line is plain text.
+  const trimmed = line.trimStart();
+  if (state.promptTag) {
+    finishPromptTag(trimmed, 0, state);
+    state.paragraph = [];
+    return;
+  }
+  if (PROMPT_OPEN.test(trimmed)) {
+    finishPromptTag(trimmed, "<Prompt".length, state);
+    state.paragraph = [];
+    return;
+  }
+  if (state.promptDepth > 0) {
+    if (PROMPT_CLOSE.test(line)) {
+      state.promptDepth -= 1;
+    }
+    state.paragraph = [];
+    return;
+  }
   const atx = line.match(ATX_HEADING);
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
@@ -220,7 +290,12 @@ const scanHeadingLine = (
 export const extractHeadings = (body: string): Heading[] => {
   const headings: Heading[] = [];
   const slugger = new GithubSlugger();
-  const state: HeadingScanState = { fence: null, paragraph: [] };
+  const state: HeadingScanState = {
+    fence: null,
+    paragraph: [],
+    promptDepth: 0,
+    promptTag: false,
+  };
 
   for (const line of linesWithoutFrontMatter(body)) {
     scanHeadingLine(line, state, slugger, headings);
@@ -364,6 +439,118 @@ const withPrefix = (prefix: string | undefined, path: string): string => {
   return clean ? `${clean}/${path}` : path;
 };
 
+/** A custom-key validation failure, lowered to a joinable diagnostic path. */
+interface CustomKeyIssue {
+  message: string;
+  path: (string | number)[];
+}
+
+/** Lower a Standard Schema path segment (`key` or `{ key }`) for joining. */
+const segmentKey = (
+  segment: PropertyKey | { readonly key: PropertyKey }
+): string | number => {
+  const key =
+    typeof segment === "object" && segment !== null ? segment.key : segment;
+  return typeof key === "symbol" ? String(key) : key;
+};
+
+/**
+ * Validate the opt-in custom frontmatter keys (`frontmatter.extend`) through
+ * the Standard Schema contract — the consumer's own Zod (any version),
+ * Valibot, or ArkType, never Blume's bundled zod (see `standard-schema.ts`).
+ * Every declared key is checked, absent ones included, so a required schema
+ * enforces its key on every page. Async schemas are rejected with a
+ * diagnostic: this funnel is synchronous, and frontmatter validation has no
+ * business awaiting I/O.
+ */
+const validateCustomKeys = (
+  data: Record<string, unknown>,
+  extend: FrontmatterExtend
+): { custom?: Record<string, unknown>; issues: CustomKeyIssue[] } => {
+  const custom: Record<string, unknown> = {};
+  const issues: CustomKeyIssue[] = [];
+  for (const [key, schema] of Object.entries(extend)) {
+    const outcome = schema["~standard"].validate(data[key]);
+    if (outcome instanceof Promise) {
+      issues.push({
+        message: "Async schemas are not supported in frontmatter.extend.",
+        path: [key],
+      });
+      continue;
+    }
+    if (outcome.issues !== undefined) {
+      issues.push(
+        ...outcome.issues.map((issue) => ({
+          message: issue.message,
+          path: [key, ...(issue.path ?? []).map(segmentKey)],
+        }))
+      );
+      continue;
+    }
+    // Preserve the validated (schema-output) value; skip keys that are absent
+    // and stay absent, so `.optional()` extras don't materialize as undefined.
+    if (outcome.value !== undefined || Object.hasOwn(data, key)) {
+      custom[key] = outcome.value;
+    }
+  }
+  return {
+    custom: Object.keys(custom).length > 0 ? custom : undefined,
+    issues,
+  };
+};
+
+/**
+ * Parse an entry's frontmatter: built-in keys through the strict page schema,
+ * custom keys (`frontmatter.extend`) through their user-supplied schemas. The
+ * custom keys are carved out before the strict parse, so the page schema stays
+ * strict for everything else and unknown-key typo catching is unchanged.
+ * Returns diagnostics instead of meta when either side rejects.
+ */
+const parseEntryMeta = (
+  entry: SourceEntry,
+  ctx: NormalizeContext
+):
+  | { meta: PageMeta; custom?: Record<string, unknown>; diagnostics?: never }
+  | { meta?: never; diagnostics: Diagnostic[] } => {
+  const extend = ctx.frontmatterExtend;
+  const known = extend
+    ? Object.fromEntries(
+        Object.entries(entry.data).filter(
+          ([key]) => !Object.hasOwn(extend, key)
+        )
+      )
+    : entry.data;
+
+  const result = pageMetaSchema.safeParse(known);
+  const customResult = extend ? validateCustomKeys(entry.data, extend) : null;
+
+  if (result.success && (customResult?.issues.length ?? 0) === 0) {
+    return { custom: customResult?.custom, meta: result.data };
+  }
+
+  // Source text lets the error carry a line/column into the frontmatter block:
+  // `entry.raw` for non-filesystem sources, else the file itself (read only on
+  // this rare error path, so filesystem entries stay cheap in the happy path).
+  const source =
+    entry.raw ??
+    (entry.sourcePath && existsSync(entry.sourcePath)
+      ? readFileSync(entry.sourcePath, "utf-8")
+      : undefined);
+  const location = {
+    code: "BLUME_FRONTMATTER_INVALID",
+    file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
+    source,
+  };
+  return {
+    diagnostics: [
+      ...(result.success ? [] : diagnosticsFromZod(result.error, location)),
+      ...(customResult
+        ? diagnosticsFromIssues(customResult.issues, location)
+        : []),
+    ],
+  };
+};
+
 /**
  * Normalize one source entry into per-locale `PageRecord`s. This is the single
  * funnel every adapter's entries pass through, so route mapping, heading/link
@@ -376,27 +563,12 @@ export const normalizeEntry = (
   const { format } = entry.body;
   const ext = format === "mdx" ? ".mdx" : ".md";
 
-  const result = pageMetaSchema.safeParse(entry.data);
-  if (!result.success) {
-    // Source text lets the error carry a line/column into the frontmatter block:
-    // `entry.raw` for non-filesystem sources, else the file itself (read only on
-    // this rare error path, so filesystem entries stay cheap in the happy path).
-    const source =
-      entry.raw ??
-      (entry.sourcePath && existsSync(entry.sourcePath)
-        ? readFileSync(entry.sourcePath, "utf-8")
-        : undefined);
-    return {
-      diagnostics: diagnosticsFromZod(result.error, {
-        code: "BLUME_FRONTMATTER_INVALID",
-        file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
-        source,
-      }),
-      pages: [],
-    };
+  const parsed = parseEntryMeta(entry, ctx);
+  if (parsed.diagnostics) {
+    return { diagnostics: parsed.diagnostics, pages: [] };
   }
 
-  const meta = result.data;
+  const { meta } = parsed;
 
   // Top-level `hidden`/`noindex` are accepted as shorthands for their nested
   // equivalents — the schema declares them, so silently ignoring them would
@@ -439,6 +611,7 @@ export const normalizeEntry = (
     componentsUsed:
       format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
     contentType: meta.type ?? ctx.defaultType,
+    custom: parsed.custom,
     description: meta.description,
     editUrl: entry.editUrl,
     entryId: staged ? `${ctx.source.name}/${entry.ref}` : undefined,

package/src/core/sources/types.ts

@@ -1,4 +1,4 @@
-import type { ResolvedI18nConfig } from "../schema.ts";
+import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
 /**
@@ -109,5 +109,7 @@ export interface NormalizeContext {
   /** Site-wide route mount point (`""` or `/seg`), prepended to every route. */
   basePath?: string;
   defaultType: string;
+  /** Opt-in custom frontmatter keys (`frontmatter.extend`), schema per key. */
+  frontmatterExtend?: FrontmatterExtend;
   i18n?: ResolvedI18nConfig;
 }

package/src/core/sources/watch.ts

@@ -23,6 +23,11 @@ import type { WatchListener } from "node:fs";
  */
 export const BLUME_IGNORE_DIRS = [
   ".blume",
+  // The isolated `blume check --isolated` runtime. A sibling of `.blume`, it is
+  // written while a dev server runs; without this the content-layer watcher (or
+  // a `.`-rooted fs.watch) would treat its generation as a content change and
+  // reload — the very thing `--isolated` promises not to do.
+  ".blume-verify",
   ".cache",
   ".git",
   ".next",

package/src/core/standard-schema.ts

@@ -0,0 +1,54 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), the minimal
+ * `~standard` surface shared by Zod 3.24+, Zod 4, Valibot, ArkType, and
+ * friends. Blume accepts user-supplied validation schemas (e.g.
+ * `frontmatter.extend`) through this interface instead of Zod's own types:
+ * `blume.config.ts` imports zod from the *consumer's* node_modules, which may
+ * be a different major version than the zod Blume bundles, and calling Zod
+ * methods (`.extend()`, `.safeParse()`) across instances is unsupported. The
+ * `~standard.validate` contract is version- and library-agnostic.
+ */
+
+/** One validation failure, with an optional path into the checked value. */
+export interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?:
+    | readonly (PropertyKey | { readonly key: PropertyKey })[]
+    | undefined;
+}
+
+/** A passing validation: the (possibly transformed) output value. */
+export interface StandardSchemaSuccess<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+
+/** A failing validation: one or more issues. */
+export interface StandardSchemaFailure {
+  readonly issues: readonly StandardSchemaIssue[];
+}
+
+export type StandardSchemaResult<Output> =
+  | StandardSchemaSuccess<Output>
+  | StandardSchemaFailure;
+
+/** A validation schema exposing the Standard Schema `~standard` contract. */
+export interface StandardSchema<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown
+    ) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?:
+      | { readonly input: Input; readonly output: Output }
+      | undefined;
+  };
+}
+
+/** Whether a config-supplied value implements the `~standard` contract. */
+export const isStandardSchema = (value: unknown): value is StandardSchema =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { "~standard"?: { validate?: unknown } })["~standard"]
+    ?.validate === "function";

package/src/core/types.ts

@@ -19,6 +19,13 @@ export interface Diagnostic {
   file?: string;
   line?: number;
   column?: number;
+  /**
+   * The built URL this diagnostic is about, for findings that are a property of
+   * the output rather than of a source file (`blume audit`). Set alongside
+   * `file`/`line` where the page maps back to authored content, so a finding can
+   * name both the URL that's wrong and the frontmatter line that fixes it.
+   */
+  url?: string;
   schemaPath?: string;
   suggestion?: string;
   docsUrl?: string;
@@ -115,6 +122,12 @@ export interface PageRecord {
   description?: string;
   contentType: string;
   meta: PageMeta;
+  /**
+   * Custom frontmatter values declared via `frontmatter.extend`, validated by
+   * the user-supplied schemas (schema output, so transforms apply). Present
+   * only when the project opts in and the page carries at least one value.
+   */
+  custom?: Record<string, unknown>;
   headings: Heading[];
   /** Whether the file is `.md`/`.mdx`. */
   format: "md" | "mdx";
@@ -159,7 +172,17 @@ export type NavNode =
 /** Top-level tab/section. */
 export interface NavTab {
   label: string;
+  /**
+   * The tab's section prefix, used to scope the sidebar and match the active
+   * tab. Not necessarily a linkable route — a section may have no index page.
+   */
   path: string;
+  /**
+   * The clickable target. Equals `path` when the section has an index page;
+   * otherwise it's resolved to the section's first page so the tab never links
+   * to a 404. Absent when it matches `path`.
+   */
+  href?: string;
   icon?: string;
   items?: NavSelectorItem[];
 }

package/src/deploy/adapter-output.ts

@@ -8,6 +8,18 @@ import type { ProjectContext } from "../core/types.ts";
 
 type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
 
+/**
+ * Top-level directory each server adapter writes its deploy bundle into, for
+ * `.gitignore` — the bundle is a build artifact, and the platform's own state
+ * lives alongside it (`.vercel/project.json`, `.netlify/state.json`), so the
+ * whole directory is ignored. `node` and `cloudflare` emit into `dist/`, which
+ * `blume init` already ignores.
+ */
+export const ADAPTER_IGNORE_DIRS: Partial<Record<Adapter, string>> = {
+  netlify: ".netlify/",
+  vercel: ".vercel/",
+};
+
 /**
  * Server adapters whose deploy bundle lands *outside* Astro's `outDir`, at a
  * path relative to the Astro project root. Blume points the Astro root at the
@@ -15,18 +27,21 @@ type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
  * `<root>/.blume/<path>` — where the deploy platform never looks. Each value is
  * the sub-path to surface up to the real project root.
  *
- * `vercel` writes a Build Output API v3 tree at `.vercel/output`; only that
- * subtree is moved, so a `vercel pull`-ed `.vercel/project.json` sitting at the
- * project root survives the relocation. `netlify` writes a Frameworks API tree
- * at `.netlify/v1` (its `.netlify/build` sibling is only the intermediate SSR
- * bundle, already traced into `v1/functions`); only `v1` is moved, so the
- * `.netlify/state.json` written by `netlify link` survives too. `node` and
- * `cloudflare` emit into `dist/` (already at the project root), so they are
- * absent here and need no relocation.
+ * `netlify` writes a Frameworks API tree at `.netlify/v1` (its `.netlify/build`
+ * sibling is only the intermediate SSR bundle, already traced into
+ * `v1/functions`); only `v1` is moved, so the `.netlify/state.json` written by
+ * `netlify link` survives too. `node` and `cloudflare` emit into `dist/`
+ * (already at the project root), so they are absent here and need no
+ * relocation.
+ *
+ * `vercel` is absent for a different reason: it is shown the real project root
+ * up front (see `withAdapterRoot`), because its `@vercel/nft` dependency trace
+ * is rooted there too and tracing from `.blume` silently drops the function's
+ * chunks and `node_modules`. Given the right root it writes its Build Output
+ * tree straight to `<root>/.vercel/output`, so there is nothing left to move.
  */
 export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
   netlify: ".netlify/v1",
-  vercel: ".vercel/output",
 };
 
 /**
@@ -53,10 +68,10 @@ export const deployStaticDir = (
   return dist;
 };
 
-/** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
+/** Outcome of {@link surfaceAdapterOutput}, for logging. */
 export type SurfaceResult =
   | { moved: false }
-  | { from: string; ignore: string; moved: true; to: string };
+  | { from: string; moved: true; to: string };
 
 /**
  * Move a server adapter's deploy bundle out of the hidden `.blume` runtime and
@@ -95,8 +110,5 @@ export const surfaceAdapterOutput = async (
   // bundle at `/var/task`).
   await cp(from, to, { recursive: true, verbatimSymlinks: true });
   await rm(from, { force: true, recursive: true });
-  // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
-  // never the moved sub-path — the platform's own state (`.vercel/project.json`,
-  // `.netlify/state.json`) lives there too and must also be ignored.
-  return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
+  return { from, moved: true, to };
 };