blume 1.7.2 → 2.0.0

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

@@ -0,0 +1,53 @@
+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 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];
+/**
+ * Base a redirect for Astro's `redirects` config, where the two sides are not
+ * symmetric:
+ *
+ * - `from` gains only `basePath`. Astro builds the match pattern with
+ *   `deployment.base` already applied (`getPattern(segments, config.base)`), so
+ *   adding it here would serve the redirect at `{base}{base}/from`.
+ * - `to` gains the full `{deployment.base}{basePath}` stack. Astro resolves a
+ *   destination that matches a known route by regenerating it from that route's
+ *   segments, which carry no base — and passes an unmatched destination through
+ *   verbatim. Neither path prepends `base`, so a root-relative `to` escapes the
+ *   base entirely (withastro/astro#7774, still the behavior in Astro 7).
+ *
+ * Both sides are authored as if mounted at root; external `to` URLs pass
+ * through. Idempotent, so a hand-written base isn't doubled.
+ */
+export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath: string, deployBase: string) => Redirect[];
+/**
+ * Base a redirect for the host platform files below. Unlike Astro's config,
+ * these are matched against the real served URL, so both sides carry the full
+ * `{deployment.base}{basePath}` stack.
+ */
+export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string) => Redirect[];
+/**
+ * The configured redirects as the host platform matches them, via
+ * {@link applyBaseToPlatformRedirects}. The one basing every consumer must
+ * share: the emitted redirect files and the Cloudflare worker-first redirect
+ * exemptions both compare these paths against real served URLs.
+ */
+export declare const platformRedirects: (config: ResolvedConfig) => Redirect[];
+/** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
+export declare const buildNetlifyRedirects: (redirects: Redirect[]) => string;
+/**
+ * `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 declare const buildVercelConfig: (redirects: Redirect[], headers?: readonly VercelHeader[]) => string;
+/** Structured manifest for hosts that need manual wiring. */
+export declare const buildRedirectManifest: (redirects: Redirect[]) => string;
+export {};

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

@@ -0,0 +1,8 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+/**
+ * Build a robots.txt that allows all crawlers, declares any configured
+ * `Content-Signal` usage preferences, and points to the sitemap when one is
+ * available (a `site` is set and the sitemap is enabled). Returns null when
+ * robots generation is disabled.
+ */
+export declare const buildRobots: (project: BlumeProject) => string | null;

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

@@ -0,0 +1,31 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+/** A single feed entry derived from a content page. */
+export interface RssItem {
+    title: string;
+    /** Absolute item URL. */
+    link: string;
+    description?: string;
+    /** Publish date, when the page declares one. */
+    date?: Date;
+}
+/** A resolved RSS feed for one content type. */
+export interface RssFeed {
+    /** Content type the feed covers, e.g. `blog`. */
+    type: string;
+    /** Feed URL path, e.g. `/blog/rss.xml`. */
+    path: string;
+    /** Channel title, e.g. `Blume — Blog`. */
+    title: string;
+    /** Absolute site link. */
+    link: string;
+    description?: string;
+    items: RssItem[];
+}
+/**
+ * Build an RSS feed per configured content type that has publishable pages.
+ * Returns an empty list when RSS is disabled or no `deployment.site` is set —
+ * absolute URLs are required for a valid feed, mirroring `buildSitemap`.
+ */
+export declare const buildRssFeeds: (project: BlumeProject) => RssFeed[];
+/** Serialize a resolved feed into an RSS 2.0 XML document. */
+export declare const renderRssFeed: (feed: RssFeed) => string;

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

@@ -0,0 +1,21 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+/** One emitted sitemap artifact: its dist-root filename and XML body. */
+export interface SitemapFile {
+    name: string;
+    xml: string;
+}
+/** The build log line for an emitted sitemap set: one file, or an index. */
+export declare const describeSitemapFiles: (files: readonly SitemapFile[]) => string;
+/**
+ * Build the sitemap files from the route manifest plus the routes the manifest
+ * 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.
+ *
+ * Sites within the per-file URL cap get the single classic `sitemap.xml`;
+ * larger sites get `sitemap.xml` as a sitemap index over numbered
+ * `sitemap-N.xml` chunks, all served from the same directory robots.txt
+ * already points at.
+ */
+export declare const buildSitemapFiles: (project: BlumeProject) => SitemapFile[] | null;

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

@@ -0,0 +1,109 @@
+/**
+ * `Accept: text/markdown` content negotiation for Vercel server builds.
+ *
+ * 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
+ * into it so a content-page request that prefers `text/markdown` is rewritten
+ * (not redirected) to the page's prerendered `.md` mirror — the deployed
+ * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
+ * The same routing config also answers a *missing* page: a request that
+ * prefers Markdown (or asks for a `.md` URL no page backs) gets the
+ * 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.
+ */
+/**
+ * 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*[;,].*)?$";
+/**
+ * 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*[;,].*)?$";
+/**
+ * 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
+ * typed.
+ */
+export interface VercelRoute {
+    continue?: boolean;
+    dest?: string;
+    handle?: string;
+    has?: {
+        key?: string;
+        type: string;
+        value?: string;
+    }[];
+    headers?: Record<string, string>;
+    src?: string;
+    status?: number;
+}
+/** Which prerendered 404 twins the build emitted, so their routes get wired. */
+export interface NotFoundVariants {
+    json?: boolean;
+    markdown?: boolean;
+}
+export interface NegotiationRoutes {
+    /**
+     * `Vary: Accept` for the plain-HTML side of every negotiated URL, so shared
+     * caches keep the two variants apart. Spliced *before* `handle:
+     * "filesystem"` with `continue`: main-phase headers accumulate and ride on
+     * whatever ultimately serves the request. Routes placed after the filesystem
+     * marker are the miss phase — they run only when no static file matches, and
+     * every Blume content page is a prerendered static file, so a header route
+     * there never fires.
+     */
+    headerRoutes: VercelRoute[];
+    /**
+     * The negotiation itself: header-conditional rewrites to the `.md` mirror.
+     * Spliced *before* `handle: "filesystem"` so they run ahead of static-file
+     * matching; the rewritten path then resolves to the prerendered `.md` file.
+     */
+    rewriteRoutes: VercelRoute[];
+}
+/**
+ * Build the routes for the given content-route paths (the routes that have a
+ * raw-Markdown mirror, straight from the manifest). Paths are matched with an
+ * optional trailing slash and rewritten `/{route}` → `/{route}.md`; the home
+ * page's mirror lives at `/index.md`. When `homeTokens` is given, the home
+ * 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.
+ */
+export declare const buildNegotiationRoutes: (routePaths: readonly string[], homeTokens?: number) => NegotiationRoutes;
+/**
+ * Splice the negotiation routes into a Build Output `config.json`, plus — when
+ * given — a homepage `Link` header route for agent discovery (see
+ * `ai/link-headers.ts`), applied the same way the `Vary` routes are: in the
+ * main phase before `handle: "filesystem"` with `continue`, so the header
+ * rides on the prerendered homepage response. `contentTypeOverrides` maps static-dir
+ * relative paths to media types via the Build Output `overrides` field — the
+ * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
+ * signature directory). The trailing-slash redirect that collapses `/docs/`
+ * onto `/docs` is not spliced here: the generated config sets Astro's
+ * `trailingSlash: "never"`, which the adapter turns into the platform's own
+ * 308 route ahead of everything below (so a slashed Markdown request takes
+ * that hop first, then negotiates). For each 404 twin the build emitted (`notFound.markdown` for
+ * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
+ * 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. 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[]) => string | null;

package/dist/types/markdown/code-title.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Code-fence meta. A Shiki transformer reads the tokens after the language and
+ * promotes them to attributes on the rendered `<pre>`:
+ *
+ * - a title — the first bare token (```ts blume.config.ts) or `title="..."` —
+ *   becomes `data-title`; the theme's code header shows it, falling back to the
+ *   language label.
+ * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
+ *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
+ */
+/** The slice of Shiki's transformer `this` context Blume reads. */
+interface CodeMetaContext {
+    options: {
+        meta?: {
+            __raw?: string;
+        };
+    };
+}
+/** The `<pre>` hast node a Shiki `pre` hook receives. */
+interface PreNode {
+    properties: Record<string, boolean | number | string | undefined>;
+}
+/** A Shiki-compatible transformer, typed structurally to avoid a Shiki dep. */
+export interface CodeTitleTransformer {
+    name: string;
+    pre: (this: CodeMetaContext, node: PreNode) => void;
+}
+/** The title a fence's meta string promotes to `data-title`, if any. */
+export declare const parseCodeTitle: (raw: string | undefined) => string | undefined;
+/** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
+export declare const codeTitleTransformer: () => CodeTitleTransformer;
+export {};

package/dist/types/markdown/fence-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The shared fence-meta grammar: how the tokens after a code fence's language
+ * (```ts title="..." {1,3-5} lineNumbers) split, and which of them carry
+ * reserved meaning. Both the Shiki-side meta reader (`code-title.ts`) and the
+ * MDAST plugins that rewrite marked fences (`ts2js.ts`) consume this, so the
+ * two layers can't drift on token boundaries or keyword lists.
+ */
+/**
+ * Any quoted `key="..."` attr (spaces allowed inside the quotes). The body
+ * excludes only the delimiting quote, so `title="foo's file.ts"` (an
+ * apostrophe inside double quotes) still matches. The left boundary stops
+ * `subtitle="..."` (or any `*title=` attr) from reading as a title.
+ */
+export declare const QUOTED_ATTR: RegExp;
+/** Split a raw fence meta string into its tokens. */
+export declare const metaTokens: (meta: string | null | undefined) => string[];
+/**
+ * Bare keywords with reserved meaning after the language; never promoted to
+ * a block title.
+ */
+export declare const RESERVED_META_KEYWORDS: ReadonlySet<string>;
+/** A Shiki `{1,3-5}` line-range token. */
+export declare const isLineRange: (token: string) => boolean;

package/dist/types/markdown/themes.d.ts

@@ -2,14 +2,14 @@
  * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
  * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
  * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
- * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * project's `markdown.code.theme` shifts them all in lockstep. This is the
  * single home for the github fallback used when nothing is configured.
  */
 import type { ThemeRegistrationAny } from "shiki";
 /** A bundled Shiki theme name or an inline custom Shiki theme definition. */
 export type CodeTheme = string | ThemeRegistrationAny;
 /**
- * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * A light/dark Shiki theme pair (`markdown.code.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
  * parameter (`Partial<Record<string, …>>`) expects.
  */
@@ -17,5 +17,5 @@ export type CodeThemes = {
     dark: CodeTheme;
     light: CodeTheme;
 };
-/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+/** The default pair, used when `markdown.code.theme` is unset. */
 export declare const DEFAULT_CODE_THEMES: CodeThemes;

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

@@ -0,0 +1,129 @@
+import type { ApiOperationRef, ApiTagRef } from "./model.ts";
+/**
+ * Blume's own AsyncAPI model — the second front-end of the API reference
+ * pipeline. Specs are normalized to AsyncAPI 3.x at parse time (see
+ * `parseAsyncApiSpec` in `parse.ts`), so this module only handles one shape:
+ * top-level `operations` with `action: send | receive` pointing at `channels`.
+ * Internal `$ref`s are deliberately left in place, mirroring `model.ts` — the
+ * components resolve them lazily, which keeps circular schemas serializable
+ * and lets type labels keep their `#/components/schemas/<name>` names.
+ * Browser-safe: no Node imports (the components import from here).
+ */
+/** The two AsyncAPI 3.x operation actions, from the application's perspective. */
+export declare const ASYNCAPI_ACTIONS: readonly ["send", "receive"];
+export type AsyncApiAction = (typeof ASYNCAPI_ACTIONS)[number];
+/**
+ * A value carried by a parsed spec document: JSON-compatible data whose exact
+ * position in the document is not modeled (extension fields, bindings,
+ * protocol-specific extras). `undefined` covers absent optional members.
+ */
+export type AsyncApiSpecValue = string | number | boolean | null | undefined | AsyncApiSpecValue[] | {
+    [key: string]: AsyncApiSpecValue;
+};
+/** A permissive view of an AsyncAPI reference object. */
+export interface AsyncApiRefLike {
+    $ref?: string;
+    [key: string]: AsyncApiSpecValue;
+}
+/** A permissive view of an AsyncAPI 3.x channel — only the fields we render. */
+export interface AsyncApiChannelObject {
+    address?: string | null;
+    title?: string;
+    summary?: string;
+    description?: string;
+    messages?: Record<string, AsyncApiRefLike>;
+    parameters?: Record<string, AsyncApiRefLike>;
+    servers?: AsyncApiRefLike[];
+    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    [key: string]: AsyncApiSpecValue;
+}
+/** A permissive view of an AsyncAPI 3.x operation — only the fields we render. */
+export interface AsyncApiOperationObject {
+    action?: string;
+    channel?: AsyncApiRefLike;
+    title?: string;
+    summary?: string;
+    description?: string;
+    deprecated?: boolean;
+    tags?: {
+        name?: string;
+        description?: string;
+    }[];
+    security?: AsyncApiRefLike[];
+    messages?: AsyncApiRefLike[];
+    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    [key: string]: AsyncApiSpecValue;
+}
+/** A permissive view of an AsyncAPI 3.x server object. */
+export interface AsyncApiServerObject {
+    host?: string;
+    protocol?: string;
+    pathname?: string;
+    description?: string;
+    security?: AsyncApiRefLike[];
+    [key: string]: AsyncApiSpecValue;
+}
+/** A normalized AsyncAPI 3.x document, internal `$ref`s intact. */
+export interface AsyncApiDocument {
+    asyncapi?: string;
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+        tags?: {
+            name?: string;
+            description?: string;
+        }[];
+        [key: string]: AsyncApiSpecValue;
+    };
+    defaultContentType?: string;
+    servers?: Record<string, AsyncApiServerObject>;
+    channels?: Record<string, AsyncApiChannelObject>;
+    operations?: Record<string, AsyncApiOperationObject>;
+    components?: Record<string, Record<string, AsyncApiSpecValue>>;
+    [key: string]: AsyncApiSpecValue;
+}
+/** The channel id an operation's `channel.$ref` points at, if resolvable. */
+export declare const channelIdOf: (channel?: AsyncApiRefLike) => string | undefined;
+/**
+ * A channel's display address. AsyncAPI 3.x allows `address: null` (unknown at
+ * design time) — fall back to the channel id so the operation still shows
+ * where it lives.
+ */
+export declare const channelAddress: (channelId: string, channel?: AsyncApiChannelObject) => string;
+/**
+ * Merge `traits` into their operation/message objects, in declaration order,
+ * with the object's own properties taking precedence (the spec's merge rule;
+ * applied shallowly, which covers the fields traits carry in practice —
+ * bindings, security, tags, headers). Runs once at parse time so the
+ * serialized document and every downstream consumer are trait-free; the
+ * `traits` key itself is dropped. Unresolvable trait `$ref`s are skipped.
+ */
+export declare const applyAsyncApiTraits: (document: AsyncApiDocument) => AsyncApiDocument;
+/**
+ * The parse-time normalization pass: component channel/operation refs inlined,
+ * then traits merged. The serialized document and every downstream consumer
+ * see plain channel/operation objects, trait-free.
+ */
+export declare const normalizeAsyncApiDocument: (document: AsyncApiDocument) => AsyncApiDocument;
+/** The route-mapped operations, ordered tags, and skip warnings of one document. */
+export interface AsyncApiOperationCatalog {
+    operations: ApiOperationRef[];
+    tags: ApiTagRef[];
+    warnings: string[];
+}
+/**
+ * Flatten a normalized AsyncAPI 3.x document into a route-mapped operation
+ * list and its ordered tags — the AsyncAPI counterpart of `extractOperations`
+ * in `model.ts`, built on the same `operationCollector`. Operations group by
+ * their first tag; untagged operations fall back to their channel address, so
+ * a spec with no tags still gets one sidebar group per channel. Keys come from
+ * the operation id (the `operations` map key), which the official 2.x
+ * converter synthesizes deterministically (`<channel>.publish` /
+ * `<channel>.subscribe`) — so a 2.x spec and its converter-upgraded 3.x form
+ * yield identical URLs. An id that slugifies to nothing falls back to
+ * action + address, the same scheme `operationKey` uses for method + path.
+ */
+export declare const extractAsyncApiOperations: (document: AsyncApiDocument, baseRoute: string) => AsyncApiOperationCatalog;
+/** Resolve the operation object for a ref out of its (AsyncAPI) document. */
+export declare const asyncApiOperationObject: (document: AsyncApiDocument, ref: ApiOperationRef) => AsyncApiOperationObject | undefined;

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

@@ -0,0 +1,8 @@
+import type { GraphqlDocument } from "./graphql.ts";
+/**
+ * Build the document from schema text: an introspection JSON result (the raw
+ * `{ __schema }` shape or a `{ data: { __schema } }` response envelope) or
+ * SDL. Anything else throws — JSON that isn't an introspection result names
+ * that problem directly instead of earning SDL syntax errors for a `{`.
+ */
+export declare const buildGraphqlDocument: (text: string) => GraphqlDocument;

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

@@ -0,0 +1,122 @@
+import type { ApiOperationRef, ExtractedOperations } from "./model.ts";
+/**
+ * Blume's own GraphQL model — the third front-end of the API reference
+ * pipeline. Schemas are lowered to this JSON-serializable document at parse
+ * time (see `buildGraphqlDocument` in `graphql-build.ts`, kept separate so
+ * `graphql`-js stays out of this module's import graph), so the components
+ * render entirely from plain data, mirroring how `model.ts` keeps OpenAPI
+ * documents serializable. Browser-safe: no Node imports (the components
+ * import from here).
+ */
+/** The three GraphQL operation kinds, each a sidebar group of root fields. */
+export declare const GRAPHQL_OPERATION_KINDS: readonly ["query", "mutation", "subscription"];
+export type GraphqlOperationKind = (typeof GRAPHQL_OPERATION_KINDS)[number];
+/** The named-type kinds that get reference pages, in sidebar-group order. */
+export declare const GRAPHQL_TYPE_KINDS: readonly ["object", "input", "enum", "interface", "union", "scalar"];
+export type GraphqlTypeKind = (typeof GRAPHQL_TYPE_KINDS)[number];
+/** Everything a GraphQL operation ref's `method` can carry. */
+export type GraphqlMember = GraphqlOperationKind | GraphqlTypeKind;
+/** Sidebar/overview group label for each member kind. */
+export declare const GRAPHQL_GROUP_LABELS: {
+    enum: string;
+    input: string;
+    interface: string;
+    mutation: string;
+    object: string;
+    query: string;
+    scalar: string;
+    subscription: string;
+    union: string;
+};
+/**
+ * A type expression as it appears in the schema: the rendered display form
+ * (`[String!]!`) plus the named type at its core (`String`), so components can
+ * print the exact wrapper shape and still link to the named type's page.
+ */
+export interface GraphqlTypeRef {
+    display: string;
+    name: string;
+}
+/** An argument or input-object field. */
+export interface GraphqlInputValue {
+    name: string;
+    description: string;
+    type: GraphqlTypeRef;
+    /** Default value printed as a GraphQL literal (`10`, `"asc"`, `[1, 2]`). */
+    default?: string;
+    deprecationReason?: string;
+}
+/** An output field of an object or interface type (root fields included). */
+export interface GraphqlField {
+    name: string;
+    description: string;
+    type: GraphqlTypeRef;
+    args: GraphqlInputValue[];
+    deprecationReason?: string;
+}
+/** One member of an enum type. */
+export interface GraphqlEnumValue {
+    name: string;
+    description: string;
+    deprecationReason?: string;
+}
+/** One named type of the schema, flattened to the fields the reference renders. */
+export interface GraphqlTypeDef {
+    name: string;
+    kind: GraphqlTypeKind;
+    description: string;
+    /** Output fields (object and interface types). */
+    fields?: GraphqlField[];
+    /** Input fields (input object types). */
+    inputFields?: GraphqlInputValue[];
+    /** Members (enum types). */
+    enumValues?: GraphqlEnumValue[];
+    /** Member type names (unions) or implementing object types (interfaces). */
+    possibleTypes?: string[];
+    /** Interfaces this object/interface type implements. */
+    interfaces?: string[];
+    /** `specifiedBy` URL (custom scalars). */
+    specifiedByUrl?: string;
+    /**
+     * A spec-defined scalar (`String`, `Int`, …): kept for type refs to resolve
+     * against, but never given a reference page of its own.
+     */
+    builtIn?: boolean;
+}
+/** A normalized GraphQL schema, lowered to serializable data at parse time. */
+export interface GraphqlDocument {
+    /** Mirrors the OpenAPI `info` block so `source.ts` reads one shape. */
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+    /** Root operation type names (`Query`, `Mutation`, `Subscription`). */
+    roots: Partial<Record<GraphqlOperationKind, string>>;
+    /** Named types by name, spec-defined scalars included, introspection types excluded. */
+    types: Record<string, GraphqlTypeDef>;
+}
+/** Whether an operation ref's method is a root-field kind (vs a type page). */
+export declare const isGraphqlOperationKind: (method: string) => method is GraphqlOperationKind;
+/**
+ * A GraphQL member in the schema's own notation — `query pets` for a root
+ * field, `type Pet` / `input PetInput` / `enum Status` for a named type. The
+ * rendered page shows the same pair as a kind badge beside the name; the
+ * text form spells the kind the way SDL does, so a reader who knows GraphQL
+ * and not Blume's badges reads it right.
+ */
+export declare const graphqlSignature: (operation: Pick<ApiOperationRef, "method" | "path">) => string;
+/**
+ * Flatten a GraphQL document into a route-mapped page list and its ordered
+ * groups — the GraphQL counterpart of `extractOperations` in `model.ts`, built
+ * on the same `operationCollector`. Root fields become operation pages grouped
+ * as Queries/Mutations/Subscriptions; every other named type becomes a type
+ * page grouped by kind (Objects, Input Objects, …). Spec-defined scalars and
+ * the root types themselves get no page — the roots' fields ARE the operation
+ * pages, and `String`/`Int`/… document nothing.
+ */
+export declare const extractGraphqlOperations: (document: GraphqlDocument, baseRoute: string) => ExtractedOperations;
+/** Resolve the root field behind an operation-kind ref, if it still exists. */
+export declare const graphqlRootField: (document: GraphqlDocument, ref: ApiOperationRef) => GraphqlField | undefined;
+/** Resolve the named type behind a type-page ref, if it still exists. */
+export declare const graphqlTypeDef: (document: GraphqlDocument, ref: ApiOperationRef) => GraphqlTypeDef | undefined;