blume 2.1.0 → 2.1.1

package/dist/types/core/sources/remote.d.ts

@@ -1,3 +1,5 @@
+import { BlumeError } from "../diagnostics.ts";
+import type { Diagnostic } from "../types.ts";
 import type { JsonObject, JsonValue } from "./json.ts";
 import type { ContentSource, SourceContext, SourceEntry } from "./types.ts";
 /** What every REST-backed CMS source needs to be a staged, cached source. */
@@ -9,8 +11,13 @@ export interface RemoteSourceOptions {
      * offline warning.
      */
     assertConfigured?: () => void;
-    /** Pull every entry from the API; called on refresh and on each poll. */
-    fetchEntries: () => Promise<SourceEntry[]>;
+    /**
+     * Pull every entry from the API; called on refresh and on each poll.
+     * `warn` reports a problem with the content itself (an embed the API
+     * couldn't resolve, a node with no Markdown), which the load returns
+     * beside the entries; a load served from the snapshot repeats none.
+     */
+    fetchEntries: (warn: (diagnostic: Diagnostic) => void) => Promise<SourceEntry[]>;
     name: string;
     /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
     pollInterval?: number;
@@ -29,6 +36,9 @@ export declare const remoteSource: (options: RemoteSourceOptions, ctx?: SourceCo
 export interface RemoteFrontmatter {
     description?: string;
     draft?: boolean;
+    sidebar?: {
+        order: number;
+    };
     title?: string;
 }
 /**
@@ -37,6 +47,13 @@ export interface RemoteFrontmatter {
  * `writesMdx`).
  */
 export declare const stagedEntry: (slug: string, data: RemoteFrontmatter, markdown: string, lastModified: string | undefined, format?: "md" | "mdx") => SourceEntry;
+/**
+ * The error a source throws before its first request when the token its API
+ * always requires is unset (Notion, Contentful's Delivery API). Sent without
+ * one, the request could only fail, and the build would report the API's
+ * wording as a fetch failure instead of the variable to set.
+ */
+export declare const missingSecretError: (name: string, env: string) => BlumeError;
 /** How a source calls its CMS: the API's auth headers and an injectable fetch. */
 export interface RestClient {
     /** Injected for tests; defaults to the global `fetch`. */
@@ -67,18 +84,28 @@ export interface RemoteFieldMap {
     description?: string;
     /** Field holding the last-modified ISO date. */
     lastModified?: string;
+    /** Field holding the sidebar order (a number); no default. */
+    order?: string;
     /** Field holding the route slug. */
     slug?: string;
     /** Field holding the page title. */
     title?: string;
 }
+/** A field map with its defaults filled in; `order` is read only when set. */
+export type RemoteFields = Required<Omit<RemoteFieldMap, "order">> & Pick<RemoteFieldMap, "order">;
+/**
+ * The slug a document's staged entry is named by. It falls back to the
+ * document's id when the slug field is missing or slugifies to nothing (pure
+ * punctuation), so distinct documents never collapse onto one
+ * `untitled.md`; a slashed slug keeps its segments.
+ */
+export declare const documentSlug: (doc: JsonObject, slugField: string, id: string) => string;
 /**
- * Map a document to a staged entry. The slug falls back to the document's id
- * when the slug field is missing or slugifies to nothing (pure punctuation),
- * so distinct documents never collapse onto one `untitled.md`; a slashed
- * slug keeps its segments. A string body is Markdown and passes through as
- * `.md`, its unsafe links reduced to their labels; any other shape goes to
- * the CMS's lowerer, and is written as `.mdx`
- * when `lowersToMdx` (the source has serializers, see `writesMdx`).
+ * Map a document to a staged entry named by its {@link documentSlug}. A
+ * number in the `order` field, when one is mapped, becomes the page's
+ * sidebar order. A string body is Markdown and passes through as `.md`, its
+ * unsafe links reduced to their labels; any other shape goes to the CMS's
+ * lowerer, and is written as `.mdx` when `lowersToMdx` (the source has
+ * serializers, see `writesMdx`).
  */
-export declare const documentEntry: (doc: JsonObject, fields: Required<RemoteFieldMap>, id: string, lower: (body: JsonValue) => string, draft?: boolean, lowersToMdx?: boolean) => SourceEntry;
+export declare const documentEntry: (doc: JsonObject, fields: RemoteFields, id: string, lower: (body: JsonValue) => string, draft?: boolean, lowersToMdx?: boolean) => SourceEntry;

package/dist/types/core/sources/sanity.d.ts

@@ -12,7 +12,7 @@ export interface SanityFieldMap {
     description?: string;
     /** Route slug (dot path); default `slug.current`. */
     slug?: string;
-    /** Portable Text body field; default `body`. */
+    /** Body field, Portable Text or a Markdown string; default `body`. */
     body?: string;
     /** Last-modified ISO date; default `_updatedAt`. */
     lastModified?: string;

package/dist/types/core/types.d.ts

@@ -51,6 +51,10 @@ export interface PageLink {
      * only those go through the image pipeline; a plain link to the same path
      * resolves as a site route. */
     image?: boolean;
+    /** Set when the target is a lowercase `<a href>`, which ships as written:
+     * the Markdown pipeline neither resolves its relative path file-style nor
+     * mounts the base path on it, so it's checked the way a browser reads it. */
+    raw?: boolean;
     /** 1-based line number in the source file. */
     line: number;
     /** 1-based column of the target within the line. */
@@ -60,6 +64,17 @@ export interface PageLink {
      * here so authors fix the partial, not the page that spliced it. */
     file?: string;
 }
+/** A `<Component path="…">` in a page, located like a {@link PageLink}. */
+export interface ExampleUse {
+    /** The example's key as written: its path under `examples/`, sans extension. */
+    path: string;
+    /** 1-based line number in the source file. */
+    line: number;
+    /** 1-based column of the `path` value within the line. */
+    column: number;
+    /** Absolute path of the included partial it was written in, if not the page. */
+    file?: string;
+}
 /**
  * Resolved project paths. Computed once per CLI invocation and threaded
  * through the core pipeline.
@@ -185,6 +200,8 @@ export interface PageRecord {
     links: PageLink[];
     /** Capitalized JSX component tags used in the body (`.mdx` only). */
     componentsUsed?: string[];
+    /** The string `path` of each `<Component>` example in the body (`.mdx` only). */
+    examplesUsed?: ExampleUse[];
     /** Resolved "last updated" ISO date, when the feature is enabled. */
     lastModified?: string;
     /** Absolute paths of files this page `<include>`s, transitively. Drives the

package/dist/types/deploy/adapter-output.d.ts

@@ -13,7 +13,8 @@ export declare const deployOutputDir: (config: ResolvedConfig, context: ProjectC
  * served. A static build serves `dist/` wherever it lands; a server build
  * serves what its platform declares — the Build Output tree's `static/` half
  * on Vercel, Astro's `build.client` dir (`dist/client/`) on Node and
- * Cloudflare, `dist/` on Netlify.
+ * Cloudflare, `dist/` on Netlify. On Vercel and Cloudflare that's its
+ * `<base>/` directory under `deployment.base`, where the files land.
  */
 export declare const deployStaticDir: (config: ResolvedConfig, context: ProjectContext) => string;
 /**

package/dist/types/deploy/adapters/cloudflare.d.ts

@@ -31,10 +31,12 @@ export declare const cloudflareAdapterSchema: import("zod").ZodObject<{
     runtimeDeps: import("zod").ZodArray<import("zod").ZodString>;
 }, import("zod/v4/core").$strict>;
 /**
- * Cloudflare Workers and Pages. A server build emits a Worker into
- * `dist/server` (with a generated wrapper that answers `Accept:
- * text/markdown`) and serves `dist/client` through the ASSETS binding.
- * `@astrojs/cloudflare` is an optional peer: install it in the project
- * (`npm install @astrojs/cloudflare`).
+ * Cloudflare. A server build targets Workers only (`@astrojs/cloudflare`
+ * dropped Pages in v13): it emits a Worker into `dist/server` (with a
+ * generated wrapper that answers `Accept: text/markdown`) and serves
+ * `dist/client` through the ASSETS binding. A static build
+ * (`output: "static"`) never loads the adapter, and its `dist/` deploys to
+ * Pages or to Workers static assets. `@astrojs/cloudflare` is an optional
+ * peer: install it in the project (`npm install @astrojs/cloudflare`).
  */
 export declare const cloudflare: (options?: CloudflareOptions) => CloudflareAdapter;

package/dist/types/deploy/adapters/node.d.ts

@@ -1,37 +1,72 @@
+import { z } from "zod";
 import type { DeployAdapter, DeployOptions } from "./types.ts";
 /** The Astro adapter package a Node server build imports. */
 export declare const NODE_ADAPTER_PACKAGE = "@astrojs/node";
 /**
- * Options for {@link node}: `output`, `site`, and `base`, plus any option of
- * `@astrojs/node` forwarded verbatim (`mode`, `staticHeaders`, …). Blume
- * defaults `mode` to `"standalone"`; an option you pass wins. `host` and
- * `port` are forwarded too, but `@astrojs/node` replaces both with Astro's
- * own server settings, so the standalone server listens on `localhost:4321`
- * unless the `HOST` and `PORT` environment variables are set when it starts.
+ * A host the server trusts forwarded headers for, in Astro's
+ * `security.allowedDomains` shape: each field set must match.
  */
-export type NodeOptions = DeployOptions;
-export type NodeAdapter = DeployAdapter<"node">;
-export declare const nodeOptionsSchema: import("zod").ZodObject<{
-    base: import("zod").ZodOptional<import("zod").ZodString>;
-    output: import("zod").ZodOptional<import("zod").ZodEnum<{
+export type NodeAllowedDomain = {
+    /** The host, like `docs.example.com`; `*.example.com` matches subdomains. */
+    hostname?: string;
+    /** The port, as a string. */
+    port?: string;
+    /** The scheme, like `https`. */
+    protocol?: string;
+};
+/**
+ * Options for {@link node}: `output`, `site`, `base`, and `allowedDomains`,
+ * plus any option of `@astrojs/node` forwarded verbatim (`mode`,
+ * `staticHeaders`, …). Blume defaults `mode` to `"standalone"`; an option you
+ * pass wins. `host` and `port` are forwarded too, but `@astrojs/node`
+ * replaces both with Astro's own server settings, so the standalone server
+ * listens on `localhost:4321` unless the `HOST` and `PORT` environment
+ * variables are set when it starts.
+ */
+export type NodeOptions = DeployOptions & {
+    /**
+     * The hosts a reverse proxy in front of the server answers for, set as
+     * Astro's `security.allowedDomains`. A request whose `Host` (or
+     * `X-Forwarded-Host`) matches one is trusted to name the reader in
+     * `X-Forwarded-For`, which the rate limit counts by; otherwise every
+     * reader counts as the proxy's address. Only list them when a proxy sets
+     * that header on every request, since a reader could otherwise send their
+     * own.
+     */
+    allowedDomains?: NodeAllowedDomain[];
+};
+export type NodeAdapter = DeployAdapter<"node", NodeOptions>;
+export declare const nodeOptionsSchema: z.ZodObject<{
+    base: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodEnum<{
         static: "static";
         server: "server";
     }>>;
-    site: import("zod").ZodOptional<import("zod").ZodURL>;
-}, import("zod/v4/core").$catchall<import("zod").ZodJSONSchema>>;
-export declare const nodeAdapterSchema: import("zod").ZodObject<{
-    kind: import("zod").ZodLiteral<"node">;
-    options: import("zod").ZodObject<{
-        base: import("zod").ZodOptional<import("zod").ZodString>;
-        output: import("zod").ZodOptional<import("zod").ZodEnum<{
+    site: z.ZodOptional<z.ZodURL>;
+    allowedDomains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export declare const nodeAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"node">;
+    options: z.ZodObject<{
+        base: z.ZodOptional<z.ZodString>;
+        output: z.ZodOptional<z.ZodEnum<{
             static: "static";
             server: "server";
         }>>;
-        site: import("zod").ZodOptional<import("zod").ZodURL>;
-    }, import("zod/v4/core").$catchall<import("zod").ZodJSONSchema>>;
-    requiredSecrets: import("zod").ZodArray<import("zod").ZodString>;
-    runtimeDeps: import("zod").ZodArray<import("zod").ZodString>;
-}, import("zod/v4/core").$strict>;
+        site: z.ZodOptional<z.ZodURL>;
+        allowedDomains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            hostname: z.ZodOptional<z.ZodString>;
+            port: z.ZodOptional<z.ZodString>;
+            protocol: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
 /**
  * A self-hosted Node server (containers, VMs). The standalone server in
  * `dist/server/entry.mjs` serves `dist/client` itself. `@astrojs/node` is one

package/dist/types/deploy/adapters/registry.d.ts

@@ -67,6 +67,11 @@ export declare const resolvedDeploymentSchema: z.ZodPipe<z.ZodDiscriminatedUnion
             server: "server";
         }>>;
         site: z.ZodOptional<z.ZodURL>;
+        allowedDomains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            hostname: z.ZodOptional<z.ZodString>;
+            port: z.ZodOptional<z.ZodString>;
+            protocol: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
     }, z.core.$catchall<z.ZodJSONSchema>>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
@@ -113,6 +118,11 @@ export declare const resolvedDeploymentSchema: z.ZodPipe<z.ZodDiscriminatedUnion
         base?: string | undefined;
         output?: "static" | "server" | undefined;
         site?: string | undefined;
+        allowedDomains?: {
+            hostname?: string | undefined;
+            port?: string | undefined;
+            protocol?: string | undefined;
+        }[] | undefined;
     };
     requiredSecrets: string[];
     runtimeDeps: string[];

package/dist/types/deploy/adapters/types.d.ts

@@ -67,9 +67,10 @@ export declare const deployOptionsSchema: z.ZodObject<{
 }, z.core.$catchall<z.ZodJSONSchema>>;
 /**
  * The options Blume does not name — what reaches the `@astrojs/*` adapter's
- * constructor verbatim.
+ * constructor verbatim. `configOptions` are the ones a host adapter names
+ * itself, for the Astro config rather than the constructor.
  */
-export declare const deployPassthrough: (options: DeployOptions) => Record<string, JsonValue>;
+export declare const deployPassthrough: (options: DeployOptions, configOptions?: readonly string[]) => Record<string, JsonValue>;
 /**
  * The runtime dependency a host adapter declares: its `@astrojs/*` package,
  * which the generated `astro.config.mjs` imports for a server build and

package/dist/types/deploy/platforms/cloudflare.d.ts

@@ -34,12 +34,15 @@ export declare const nameCloudflareWorker: (project: BlumeProject, log: BuildLog
  */
 export declare const bindCloudflareRateLimit: (project: BlumeProject, log: BuildLog) => Promise<void>;
 /**
- * Cloudflare Workers and Pages. A server build emits the Worker into
- * `dist/server` and serves `dist/client` through the ASSETS binding, which
- * honors `_headers` from that directory exactly as Pages does — so the file
- * applies to both output modes here. Without a configured driver the adapter
- * force-enables KV-backed sessions and declares a `SESSION` binding that
- * `wrangler deploy` then demands a namespace for, even though Blume never
- * reads `Astro.session`; `session: false` opts the project out.
+ * Cloudflare. A server build targets Workers only (`@astrojs/cloudflare`
+ * dropped Pages in v13): it emits the Worker into `dist/server` and serves
+ * `dist/client` through the ASSETS binding, which honors `_headers` from that
+ * directory exactly as Pages does — so the file applies to both output modes
+ * here. A static build never loads the adapter; its `dist/` deploys to Pages,
+ * whose build environment `env` detects, or to Workers static assets (Workers
+ * Builds exposes no site URL to detect). Without a configured driver the
+ * adapter force-enables KV-backed sessions and declares a `SESSION` binding
+ * that `wrangler deploy` then demands a namespace for, even though Blume
+ * never reads `Astro.session`; `session: false` opts the project out.
  */
 export declare const cloudflarePlatform: DeployPlatform;

package/dist/types/deploy/platforms/node.d.ts

@@ -7,6 +7,8 @@ import type { DeployPlatform } from "./types.ts";
  * discovery files and downloaded SVGs need instead, and answers the
  * configured redirects with their exact status, which Astro's own handler
  * would default to 301 or 308. No platform env to detect: the site URL has to
- * be configured.
+ * be configured. `allowedDomains` becomes Astro's `security.allowedDomains`,
+ * which a server behind a reverse proxy needs before Astro reads the reader's
+ * address from `X-Forwarded-For`.
  */
 export declare const nodePlatform: DeployPlatform;

package/dist/types/deploy/platforms/types.d.ts

@@ -2,7 +2,7 @@ import type { JsonValue } from "../../core/adapter.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import type { ProjectContext } from "../../core/types.ts";
-import type { DeployAdapterKind } from "../adapters/registry.ts";
+import type { DeployAdapterKind, ResolvedDeployOptions } from "../adapters/registry.ts";
 import type { DeployOutput } from "../adapters/types.ts";
 /**
  * Everything Blume does differently per deployment target, keyed by the
@@ -13,8 +13,16 @@ import type { DeployOutput } from "../adapters/types.ts";
  */
 /** How the generated `astro.config.mjs` constructs the `@astrojs/*` adapter. */
 export interface AstroAdapterSpec {
-    /** Top-level `defineConfig` entries the adapter needs beside itself. */
-    config: Record<string, JsonValue>;
+    /**
+     * Top-level `defineConfig` entries the adapter needs beside itself, some
+     * of them set from the deployment's own options.
+     */
+    config: (options: ResolvedDeployOptions) => Record<string, JsonValue>;
+    /**
+     * The deployment options `config` reads, which therefore stay out of the
+     * passthrough to the `@astrojs/*` constructor.
+     */
+    configOptions: string[];
     /** Blume's own constructor options; the user's passthrough is spread over them. */
     options: (context: ProjectContext) => Record<string, JsonValue>;
     /** The package the config imports the adapter from. */
@@ -106,14 +114,17 @@ export interface DeployPlatform {
     /**
      * Whether the adapter moves a server build's client output under
      * `deployment.base` (`dist/client/<base>/`, the directory Astro then hands
-     * `astro:build:done`) while the platform keeps serving `serverStaticDir`
-     * as the assets root. The files the platform reads there, like `_headers`,
+     * `astro:build:done`) while the platform keeps serving `dist/client` as
+     * the assets root. The files the platform reads there, like `_headers`,
      * belong above the directory Astro reports.
      */
     serverClientUnderBase: boolean;
     /** Where a server build's deploy bundle lands. */
     serverOutputDir: (context: ProjectContext) => string;
-    /** The directory a server build serves as static files. */
-    serverStaticDir: (context: ProjectContext) => string;
+    /**
+     * The directory a server build serves as static files, given the normalized
+     * `deployment.base` for a platform that serves them from `<dir>/<base>/`.
+     */
+    serverStaticDir: (context: ProjectContext, base: string) => string;
 }
 export {};

package/dist/types/deploy/platforms/vercel.d.ts

@@ -1,4 +1,5 @@
 import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ProjectContext } from "../../core/types.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 /** `vercel.json` with a `redirects` array, for a static deploy of `dist/`. */
 export declare const VERCEL_JSON_FILE: RedirectFile;
@@ -26,6 +27,22 @@ export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLo
  * prerender a pattern's pages, so the adapter never sees these.
  */
 export declare const emitVercelPatternRedirects: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Move a server build's static files under `deployment.base`.
+ * `@astrojs/vercel` copies them to the root of the Build Output tree's
+ * `static/`, while the pages request `<base>/_astro/…` and link to
+ * `<base>/…`, so nothing the site asks for would be found. Moved to
+ * `static/<base>/`, they're served at the base, as the routes that
+ * {@link rebaseVercelRoutes} moves there expect.
+ */
+export declare const moveStaticUnderBase: (context: ProjectContext, base: string) => Promise<void>;
+/**
+ * Move the adapter's routing config under `deployment.base` to match the
+ * static files (see `rebaseAdapterRoutes`), its exact redirects rebuilt from
+ * the configured ones. Resolves to false when the config can't be read: the
+ * adapter's routes would then miss every path under the base.
+ */
+export declare const rebaseVercelRoutes: (project: BlumeProject, log: BuildLog) => Promise<boolean>;
 /**
  * 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
@@ -34,6 +51,8 @@ export declare const emitVercelPatternRedirects: (project: BlumeProject, log: Bu
  * Static assets are served from the tree's `static/` half, so the deploy
  * artifacts are written there; headers (the discovery files', the sandbox on
  * downloaded SVGs) arrive through the routing config rather than a
- * `_headers` file, which Vercel never reads.
+ * `_headers` file, which Vercel never reads. The adapter ignores
+ * `deployment.base`, so under one the build moves the static files and the
+ * routes beneath it.
  */
 export declare const vercelPlatform: DeployPlatform;

package/dist/types/deploy/redirects.d.ts

@@ -41,9 +41,25 @@ export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath
  * public file (see {@link baseRedirectTarget}).
  */
 export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => Redirect[];
+/**
+ * Based `redirects`, each exact one that moves a page followed by the same
+ * redirect for the page's Markdown copies: from a path no page is served at
+ * to one a page is, `/old.md` goes to `/new.md` (and `.mdx` alike), where it
+ * would otherwise 404 for an agent still reading the old URL. A pattern gets
+ * none; one that carries its capture over (`/beta/:slug*` → `/v2/:slug*`)
+ * already moves `/beta/guide.md` along. `pages` are the served page routes
+ * (carrying `basePath`, not `deployment.base`), and `bases` the deployment
+ * base each end carries: Astro's config leaves it off `from` (see
+ * {@link applyBaseToAstroRedirects}).
+ */
+export declare const withMirrorRedirects: (redirects: Redirect[], pages: RouteSet, bases: {
+    from: string;
+    to: string;
+}) => Redirect[];
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}, exact paths ahead of patterns: hosts
+ * {@link applyBaseToPlatformRedirects} plus the Markdown copies of each moved
+ * page ({@link withMirrorRedirects}), exact paths ahead of patterns: hosts
  * try rules in order, and an exact redirect wins over a pattern that also
  * covers its path. The one basing every consumer must share: the emitted
  * redirect files and the server wrappers all compare these paths against

package/dist/types/deploy/sitemap.d.ts

@@ -11,7 +11,8 @@ export declare const describeSitemapFiles: (files: readonly SitemapFile[]) => st
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
  * the generated `/changelog` index. Returns null when the sitemap is disabled
  * or no `site` is configured (absolute URLs are required for a valid sitemap).
- * Drafts, hidden, and `noindex` pages are excluded.
+ * Drafts, hidden, and `noindex` pages are excluded, and so is a page whose
+ * `seo.canonical` points elsewhere.
  *
  * Sites within the per-file URL cap get the single classic `sitemap.xml`;
  * larger sites get `sitemap.xml` as a sitemap index over numbered

package/dist/types/deploy/vercel-negotiation.d.ts

@@ -14,25 +14,31 @@
  * prerendered Markdown 404 body with the 404 status, instead of the HTML
  * shell, and one that prefers JSON (or asks for a `.json` URL) gets the
  * prerendered problem-details 404.
+ *
+ * Under `deployment.base` every route here matches the served URL, base
+ * included, and names the files where Blume moves them (`static/<base>/`, see
+ * {@link rebaseAdapterRoutes}); `base` is the normalized base, `""` for none.
  */
-/**
- * Regex for the `accept` header condition. Written to hold under both matching
- * semantics a router may apply — full-string and substring — by anchoring the
- * end and letting `(.*,)?` absorb any earlier list entries: it requires a
- * `text/markdown` or `text/x-markdown` entry terminated by `;`, `,`, or the end
- * of the header. Kept lookaround-free so it stays valid in RE2, and lowercase
- * only — real agents send lowercase media types, and q-values are not compared
- * (a client sending `text/markdown` at `q=0` is pathological). Browsers never
- * send `text/markdown`, so ordinary page requests are unaffected.
- */
-export declare const ACCEPT_MARKDOWN_HEADER_VALUE = "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
+/** One header condition on a Build Output route. */
+export interface VercelCondition {
+    key?: string;
+    type: string;
+    value?: string;
+}
+/** The conditions of one route: all of `has`, none of `missing`. */
+export interface AcceptConditions {
+    has: VercelCondition[];
+    missing?: VercelCondition[];
+}
+/** When a client prefers `text/markdown` (or `text/x-markdown`) over HTML. */
+export declare const ACCEPT_MARKDOWN_CONDITIONS: AcceptConditions[];
 /**
  * The JSON counterpart, for the problem-details 404: `application/json` or
  * `application/problem+json`. Browsers never send either on a navigation
  * (the catch-all wildcard does not match), so ordinary page requests are
  * unaffected.
  */
-export declare const ACCEPT_JSON_HEADER_VALUE = "(.*,)?\\s*application/(problem\\+)?json(\\s*[;,].*)?$";
+export declare const ACCEPT_JSON_CONDITIONS: AcceptConditions[];
 /**
  * A Build Output API route — the subset these helpers read and write. Parsed
  * routes keep whatever other fields they carry at runtime; only these are
@@ -42,12 +48,9 @@ export interface VercelRoute {
     continue?: boolean;
     dest?: string;
     handle?: string;
-    has?: {
-        key?: string;
-        type: string;
-        value?: string;
-    }[];
+    has?: VercelCondition[];
     headers?: Record<string, string>;
+    missing?: VercelCondition[];
     src?: string;
     status?: number;
 }
@@ -82,9 +85,10 @@ export interface NegotiationRoutes {
  * rewrite also stamps `x-markdown-tokens` — the estimated token count of the
  * homepage mirror (Cloudflare's Markdown for Agents convention). Only the home
  * route can carry it: the other rewrites are chunked alternations spanning
- * many pages, and a count is per-page.
+ * many pages, and a count is per-page. Under a `base`, each path is matched
+ * and rewritten where it's served (`/docs` → `/docs/index.md`).
  */
-export declare const buildNegotiationRoutes: (routePaths: readonly string[], homeTokens?: number) => NegotiationRoutes;
+export declare const buildNegotiationRoutes: (routePaths: readonly string[], homeTokens?: number, base?: string) => NegotiationRoutes;
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
  * given — a homepage `Link` header route for agent discovery (see
@@ -102,12 +106,14 @@ export declare const buildNegotiationRoutes: (routePaths: readonly string[], hom
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
  * nothing. With `svgAssets`, a main-phase route also sandboxes the SVGs a
- * content source downloaded (see {@link svgAssetRoute}). Returns the updated JSON
+ * content source downloaded (see {@link svgAssetRoute}). Under a `base`, every
+ * route matches and names paths beneath it, and the fallback anchor is the
+ * one {@link rebaseAdapterRoutes} moved there. Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
  */
-export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean) => string | null;
+export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean, base?: string) => string | null;
 /**
  * Splice routes for the pattern redirects (see `vercelPatternRoutes`) into a
  * Build Output `config.json`, in the main phase just ahead of
@@ -117,3 +123,18 @@ export declare const injectNegotiationRoutes: (configText: string, routePaths: r
  * unparsable config, no `routes` array, or no `handle: "filesystem"` marker.
  */
 export declare const injectRedirectRoutes: (configText: string, redirectRoutes: readonly VercelRoute[]) => string | null;
+/**
+ * Move the adapter's routes under `deployment.base`, to match the static files
+ * Blume moves to `static/<base>/`. `@astrojs/vercel` routes a server build as
+ * if it were served from the root: its route patterns (the `_astro/` cache
+ * header, every server route) match base-less paths, its 404 fallback names
+ * `/404.html`, and it joins the base onto each redirect with no slash on the
+ * `from` side and a second time on the `to` side, which Astro hands it
+ * already based (`^/docsold$` → `/docs/docs/new`). Each pattern is
+ * re-anchored under the base and the fallback names the base's `404.html`;
+ * the adapter's redirects make way for `redirectRoutes`, the exact redirects
+ * as the host matches them. Returns the updated JSON text, or `null` when
+ * there is nowhere safe to splice: an unparsable config, no `routes` array,
+ * or no `handle: "filesystem"` marker.
+ */
+export declare const rebaseAdapterRoutes: (configText: string, base: string, redirectRoutes: readonly VercelRoute[]) => string | null;

package/dist/types/openapi/checks.d.ts

@@ -0,0 +1,27 @@
+import type { ApiDocument } from "./model.ts";
+/**
+ * Targeted checks for spec mistakes that would otherwise render silently
+ * wrong. This is not a validator — a linter such as Spectral or oasdiff owns
+ * that — and a spec that fails one of these still renders. Each check names
+ * one mistake whose symptom on the page is quiet: a path placeholder sent
+ * as literal text, a Try it input whose value goes nowhere, an Authorization
+ * section with no scheme to describe. Each reports a warning with its own
+ * code, so a build says what's wrong instead of shipping it.
+ */
+/** One mistake a check found, before the source names the spec it's in. */
+export interface SpecIssue {
+    code: string;
+    message: string;
+    suggestion: string;
+}
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export declare const operationLabel: (name: string, method: string, webhook: boolean) => string;
+/**
+ * Check a parsed document for the mistakes above, and for the OpenAPI 3.2
+ * features Blume doesn't render yet. `$ref` path items are skipped: the
+ * extractor already reports them as missing from the reference.
+ */
+export declare const specIssues: (document: ApiDocument) => SpecIssue[];

package/dist/types/openapi/graphql.d.ts

@@ -37,6 +37,10 @@ export interface GraphqlTypeRef {
     display: string;
     name: string;
 }
+/** A GraphQL input value as JSON carries it in `variables` (enums by name). */
+export type GraphqlJsonValue = string | number | boolean | null | GraphqlJsonValue[] | {
+    [key: string]: GraphqlJsonValue;
+};
 /** An argument or input-object field. */
 export interface GraphqlInputValue {
     name: string;
@@ -44,6 +48,8 @@ export interface GraphqlInputValue {
     type: GraphqlTypeRef;
     /** Default value printed as a GraphQL literal (`10`, `"asc"`, `[1, 2]`). */
     default?: string;
+    /** The same default as JSON, for the example variables. */
+    defaultValue?: GraphqlJsonValue;
     deprecationReason?: string;
 }
 /** An output field of an object or interface type (root fields included). */