blume 1.5.2 → 1.6.0

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

@@ -0,0 +1,69 @@
+import type { FolderMeta, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
+import type { Diagnostic, FeaturedLink, HeaderAction, Navigation, NavSelector, NavTab, PageRecord } from "./types.ts";
+/**
+ * Whether `route` is the section root `base` or nested beneath it. Requires a
+ * path boundary, so `/api-reference` is not under `/api`. The root `/` spans
+ * every route.
+ */
+export declare const isUnderPath: (route: string, base: string) => boolean;
+/**
+ * Whether `tab` is the root tab of the tree rooted at `root` — the tab that
+ * spans the whole sidebar rather than one section. Tab paths and the root
+ * normally share one path space, so the root tab sits at `root` exactly (`/`,
+ * `/en`, `/docs`); in an archived version tree the root is versionized
+ * (`/v1.0`, `/docs/v1.0`) while tab paths stay in current-docs space, so the
+ * root tab is any tab the whole root sits under. The one definition shared by
+ * sidebar scoping, tab-section hoisting, and the header's current-tab state —
+ * consumers that disagree on which tab is the root tab prune an archived
+ * sidebar or highlight the wrong tab over it.
+ */
+export declare const isRootTab: (tab: NavTab, root: string) => boolean;
+/** Build the complete navigation model from pages, meta, and config. */
+export declare const buildNavigation: (pages: PageRecord[], options: {
+    /** Plain links in the header, left of the icon buttons. */
+    actions?: HeaderAction[];
+    /** Site-wide route mount point (`""` or `/seg`); applied to config paths. */
+    basePath?: string;
+    /** The single primary call to action in the header. */
+    cta?: HeaderAction | null;
+    folderMeta: Map<string, FolderMeta>;
+    /** Global display mode for every sidebar group (default `flat`). */
+    display?: SidebarDisplay;
+    featured?: FeaturedLink[];
+    selectors?: NavSelector[];
+    tabs?: NavTab[];
+    sidebar?: SidebarItemConfig[];
+    /**
+     * Folder-meta lookup prefix (`""` for the default locale of the current
+     * version): the version dir and/or locale dir hoisted in front of the
+     * group path, e.g. `fr`, `v1.0`, or `v1.0/fr`.
+     */
+    metaPrefix?: string;
+    /**
+     * Prefix for shared `meta.$.*` lookups — the version dir inside a
+     * snapshot (`v1.0`), since shared meta is locale-agnostic but still
+     * version-specific. `""` for the current version.
+     */
+    sharedMetaPrefix?: string;
+    /**
+     * Resolve explicit-sidebar references against each page's locale-agnostic
+     * `translationKey` instead of its localized `route`. Used under i18n so a
+     * single authored sidebar maps onto every locale's pages.
+     */
+    refByLogical?: boolean;
+    /** Shared `meta.$.*` meta, keyed by locale-stripped dir path. */
+    sharedFolderMeta?: Map<string, FolderMeta>;
+    /**
+     * The tree's root route before `basePath` (`"/"`, or the locale prefix
+     * under i18n, e.g. `/fr` — tab paths arrive already localized). The tab
+     * pointing here spans the whole tree, so it is excluded from tab-section
+     * scoping.
+     */
+    localizedRoot?: string;
+    /**
+     * Sink for diagnostics produced while building the tree (duplicate sidebar
+     * `order` values, index-page title/folder-meta-title mismatches). Pushed
+     * into in place; omit to discard.
+     */
+    diagnostics?: Diagnostic[];
+}) => Navigation;

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

@@ -218,6 +218,11 @@ declare const contentSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     publishedValue: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"notion">;
 }, z.core.$strip>, z.ZodObject<{
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prefix: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"obsidian">;
+    vault: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
     source: z.ZodCustom<ContentSource, ContentSource>;
     type: z.ZodLiteral<"custom">;
 }, z.core.$strip>], "type">;
@@ -280,14 +285,17 @@ declare const aiConfigSchema: z.ZodObject<{
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        details: z.ZodOptional<z.ZodString>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         openapi: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>]>>, z.ZodTransform<{
         enabled: boolean;
         openapi: boolean;
+        details?: string | undefined;
     }, boolean | {
         enabled: boolean;
         openapi: boolean;
+        details?: string | undefined;
     }>>;
     markdownComponents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCustom<ComponentMarkdown, ComponentMarkdown>>>;
     mcp: z.ZodPrefault<z.ZodObject<{
@@ -472,6 +480,22 @@ declare const openapiSourceSchema: z.ZodObject<{
     spec: z.ZodString;
 }, z.core.$strict>;
 export type OpenApiSource = z.input<typeof openapiSourceSchema>;
+/**
+ * A single GraphQL schema rendered by the reference. `spec` is a local path or
+ * an `http(s)` URL to SDL text or an introspection JSON result; `endpoint` is
+ * the live GraphQL API URL the playground and code samples target (a schema,
+ * unlike an OpenAPI document, names no server).
+ */
+declare const graphqlSourceSchema: z.ZodObject<{
+    includeInLlms: z.ZodDefault<z.ZodBoolean>;
+    includeInSearch: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    route: z.ZodOptional<z.ZodString>;
+    spec: z.ZodString;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type GraphqlSource = z.input<typeof graphqlSourceSchema>;
 export declare const blumeConfigSchema: z.ZodObject<{
     ai: z.ZodPrefault<z.ZodObject<{
         ask: z.ZodOptional<z.ZodObject<{
@@ -499,14 +523,17 @@ export declare const blumeConfigSchema: z.ZodObject<{
             }, z.core.$strict>>>;
         }, z.core.$strict>>;
         llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            details: z.ZodOptional<z.ZodString>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             openapi: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>]>>, z.ZodTransform<{
             enabled: boolean;
             openapi: boolean;
+            details?: string | undefined;
         }, boolean | {
             enabled: boolean;
             openapi: boolean;
+            details?: string | undefined;
         }>>;
         markdownComponents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCustom<ComponentMarkdown, ComponentMarkdown>>>;
         mcp: z.ZodPrefault<z.ZodObject<{
@@ -650,6 +677,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             publishedValue: z.ZodOptional<z.ZodString>;
             type: z.ZodLiteral<"notion">;
         }, z.core.$strip>, z.ZodObject<{
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            prefix: z.ZodOptional<z.ZodString>;
+            type: z.ZodLiteral<"obsidian">;
+            vault: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
             source: z.ZodCustom<ContentSource, ContentSource>;
             type: z.ZodLiteral<"custom">;
         }, z.core.$strip>], "type">>>;
@@ -734,11 +766,39 @@ export declare const blumeConfigSchema: z.ZodObject<{
         extend: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCustom<StandardSchema<unknown, unknown>, StandardSchema<unknown, unknown>>>>;
     }, z.core.$strict>>;
     github: z.ZodOptional<z.ZodObject<{
+        api: z.ZodOptional<z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>>;
         branch: z.ZodDefault<z.ZodString>;
         dir: z.ZodOptional<z.ZodString>;
+        host: z.ZodDefault<z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>>;
         owner: z.ZodString;
         repo: z.ZodString;
     }, z.core.$strict>>;
+    graphql: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        route: z.ZodDefault<z.ZodString>;
+        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            proxy: string | boolean;
+        }, boolean | {
+            enabled: boolean;
+            proxy: string | boolean;
+        }>>;
+        spec: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            includeInLlms: z.ZodDefault<z.ZodBoolean>;
+            includeInSearch: z.ZodDefault<z.ZodBoolean>;
+            label: z.ZodOptional<z.ZodString>;
+            noindex: z.ZodDefault<z.ZodBoolean>;
+            route: z.ZodOptional<z.ZodString>;
+            spec: z.ZodString;
+            endpoint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     i18n: z.ZodOptional<z.ZodObject<{
         defaultLocale: z.ZodDefault<z.ZodString>;
         fallbackLocale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -798,12 +858,20 @@ export declare const blumeConfigSchema: z.ZodObject<{
         imageZoom: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     navigation: z.ZodPrefault<z.ZodObject<{
+        actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            href: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>>;
+        cta: z.ZodOptional<z.ZodObject<{
+            href: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
         featured: z.ZodDefault<z.ZodArray<z.ZodObject<{
             href: z.ZodString;
             icon: z.ZodOptional<z.ZodString>;
             label: z.ZodString;
         }, z.core.$strict>>>;
-        repo: z.ZodDefault<z.ZodBoolean>;
+        repo: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodURL]>>;
         selectors: z.ZodDefault<z.ZodArray<z.ZodObject<{
             items: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
@@ -894,6 +962,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             searchApiKey: z.ZodString;
         }, z.core.$strict>>;
         indexing: z.ZodPrefault<z.ZodObject<{
+            includeCodeBlocks: z.ZodDefault<z.ZodBoolean>;
             includeHiddenPages: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
         mixedbread: z.ZodOptional<z.ZodObject<{
@@ -978,6 +1047,22 @@ export declare const blumeConfigSchema: z.ZodObject<{
             site: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
             titles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$strict>>;
+        organization: z.ZodOptional<z.ZodObject<{
+            address: z.ZodOptional<z.ZodObject<{
+                addressCountry: z.ZodOptional<z.ZodString>;
+                addressLocality: z.ZodOptional<z.ZodString>;
+                addressRegion: z.ZodOptional<z.ZodString>;
+                postalCode: z.ZodOptional<z.ZodString>;
+                streetAddress: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            contactType: z.ZodDefault<z.ZodString>;
+            email: z.ZodOptional<z.ZodEmail>;
+            logo: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            sameAs: z.ZodDefault<z.ZodArray<z.ZodURL>>;
+            telephone: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strict>>;
         robots: z.ZodDefault<z.ZodBoolean>;
         rss: z.ZodPrefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -985,6 +1070,34 @@ export declare const blumeConfigSchema: z.ZodObject<{
             types: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         sitemap: z.ZodDefault<z.ZodBoolean>;
+        software: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            applicationCategory: z.ZodDefault<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            license: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            operatingSystem: z.ZodOptional<z.ZodString>;
+            price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            priceCurrency: z.ZodDefault<z.ZodString>;
+            sameAs: z.ZodDefault<z.ZodArray<z.ZodURL>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            applicationCategory: string;
+            priceCurrency: string;
+            sameAs: string[];
+            description?: string | undefined;
+            license?: string | undefined;
+            name?: string | undefined;
+            operatingSystem?: string | undefined;
+            price?: string | number | undefined;
+        } | undefined, boolean | {
+            applicationCategory: string;
+            priceCurrency: string;
+            sameAs: string[];
+            description?: string | undefined;
+            license?: string | undefined;
+            name?: string | undefined;
+            operatingSystem?: string | undefined;
+            price?: string | number | undefined;
+        } | undefined>>;
         structuredData: z.ZodDefault<z.ZodBoolean>;
         x: z.ZodDefault<z.ZodObject<{
             creator: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
@@ -1037,6 +1150,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                     bunny: "bunny";
                     fontshare: "fontshare";
                 }>>;
+                subsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 weights: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
             }, z.core.$strict>, z.ZodObject<{
                 fallback: z.ZodOptional<z.ZodEnum<{
@@ -1068,6 +1182,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                     bunny: "bunny";
                     fontshare: "fontshare";
                 }>>;
+                subsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 weights: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
             }, z.core.$strict>, z.ZodObject<{
                 fallback: z.ZodOptional<z.ZodEnum<{
@@ -1099,6 +1214,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                     bunny: "bunny";
                     fontshare: "fontshare";
                 }>>;
+                subsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 weights: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
             }, z.core.$strict>, z.ZodObject<{
                 fallback: z.ZodOptional<z.ZodEnum<{

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

@@ -24,9 +24,15 @@ export interface SourceEntry {
      */
     raw?: string;
     /**
-     * Absolute filesystem path when the entry originates from disk. Populated by
-     * the filesystem adapter only; powers git last-modified and edit URLs and the
-     * `sourcePath` back-compat window. Omitted by remote/CMS adapters.
+     * Absolute filesystem path when the entry originates from disk. Set by any
+     * local-file adapter — the filesystem source, and staged local sources such
+     * as Obsidian, whose bodies are rewritten but whose notes are still real
+     * files. It gives diagnostics a path the author recognizes and lets relative
+     * image checks resolve next to the file. Omitted by remote/CMS adapters.
+     *
+     * It does *not* imply the entry renders through the docs glob collection —
+     * read `source.staged` for that — and git last-modified additionally needs
+     * the owning source to expose a `contentRoot` to bound the log's pathspec.
      */
     sourcePath?: string;
     /** Optional provenance for "edit this page". */
@@ -35,6 +41,22 @@ export interface SourceEntry {
     lastModified?: string;
     /** Content hash for cache invalidation / HMR; adapter-computed when cheap. */
     hash?: string;
+    /**
+     * The body with `<include>` statements expanded, set by the scan's expansion
+     * pass (filesystem entries whose body contains a statement). `normalizeEntry`
+     * extracts headings/links/components from this text so a partial's content
+     * counts toward the including page, with `origins` mapping each expanded
+     * line back to the file and raw line it came from for diagnostics.
+     */
+    expanded?: {
+        text: string;
+        origins: {
+            file: string;
+            line: number;
+        }[];
+        /** Absolute paths of every file included, transitively. */
+        includes: string[];
+    };
 }
 /** The result of a single `ContentSource.load()` call. */
 export interface SourceLoadResult {
@@ -92,9 +114,12 @@ export interface ContentSource {
     /** Optional route prefix; the source's routes namespace under `/<prefix>/`. */
     readonly prefix?: string;
     /**
-     * Resolved on-disk root, set by filesystem-backed sources only. Drives
-     * folder-meta discovery (scan under this root) and the docs-collection base;
-     * omitted by remote/CMS/staged sources that have no local tree.
+     * Resolved on-disk root, set by sources whose entries live on disk. For
+     * filesystem sources it drives folder-meta discovery (scan under this root)
+     * and the docs-collection base; for staged local sources (an Obsidian
+     * vault) it only bounds the git last-modified pathspec — folder-meta
+     * discovery is guarded on `staged`. Omitted by remote/CMS sources that have
+     * no local tree.
      */
     readonly contentRoot?: string;
     /** Pull every entry. Called once per scan. */

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

@@ -55,6 +55,10 @@ export interface PageLink {
     line: number;
     /** 1-based column of the target within the line. */
     column: number;
+    /** Absolute path of the file the link was written in, when that isn't the
+     * page's own source — a link inside an included partial. Diagnostics point
+     * here so authors fix the partial, not the page that spliced it. */
+    file?: string;
 }
 /**
  * Resolved project paths. Computed once per CLI invocation and threaded
@@ -95,7 +99,7 @@ export interface PageRecord {
         name: string;
         ref: string;
     };
-    /** Absolute source path. Populated by the filesystem adapter only (back-compat). */
+    /** Absolute source path. Populated by any local-file adapter (back-compat). */
     sourcePath?: string;
     /**
      * Renderable body captured at scan time. Set for staged (non-filesystem)
@@ -165,6 +169,11 @@ export interface PageRecord {
      */
     custom?: Record<string, unknown>;
     headings: Heading[];
+    /**
+     * Raw HTML element ids (`<a id="…">`) outside headings, deduplicated —
+     * fragment-link targets `blume validate` accepts alongside heading slugs.
+     */
+    anchors: string[];
     /** Whether the file is `.md`/`.mdx`. */
     format: "md" | "mdx";
     /** Internal/asset links discovered in the page (for validation). */
@@ -173,6 +182,9 @@ export interface PageRecord {
     componentsUsed?: string[];
     /** Resolved "last updated" ISO date, when the feature is enabled. */
     lastModified?: string;
+    /** Absolute paths of files this page `<include>`s, transitively. Drives the
+     * dev-server invalidation edge from a partial to the pages that splice it. */
+    includes?: string[];
 }
 /** A node in the generated navigation tree. */
 export type NavNode = {
@@ -249,6 +261,11 @@ export interface FeaturedLink {
     href: string;
     icon?: string;
 }
+/** A plain header link, or the header's single call to action. */
+export interface HeaderAction {
+    href: string;
+    label: string;
+}
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
     tabs: NavTab[];
@@ -264,6 +281,10 @@ export interface Navigation {
      * graphs; treat as `/`.
      */
     root?: string;
+    /** Plain links in the header, left of the icon buttons. */
+    actions?: HeaderAction[];
+    /** The single primary call to action in the header. */
+    cta?: HeaderAction | null;
     /** Pinned links shown above the sidebar sections, unscoped by tab. */
     featured: FeaturedLink[];
     /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
@@ -321,7 +342,7 @@ export interface RouteManifestEntry {
     /** Astro collection-relative entry id, passed to `getEntry`. */
     entryId: string;
     path: string;
-    /** Absolute source path; populated for filesystem entries only (back-compat). */
+    /** Absolute source path; populated for local-file entries only (back-compat). */
     sourcePath?: string;
     /** Adapter-supplied "edit this page" URL (non-filesystem sources). */
     editUrl?: string;

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

@@ -0,0 +1,21 @@
+/**
+ * Sätteri's feature set for plain `.md` pages. Shared by the renderer and the
+ * search extractor so the index reads the same grammar the page renders.
+ */
+export declare const MARKDOWN_FEATURES: {
+    subscript: true;
+    superscript: true;
+};
+/**
+ * The `.mdx` feature set: Markdown's plus `:::` directives (→ `<Callout>`) and
+ * block-only math — `singleDollarTextMath: false` keeps a bare `$` (currency,
+ * shell, code) as literal text and only parses `$$…$$`.
+ */
+export declare const MDX_FEATURES: {
+    directive: true;
+    math: {
+        singleDollarTextMath: false;
+    };
+    subscript: true;
+    superscript: true;
+};

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

@@ -7,7 +7,7 @@ export { normalizeRoute } from "../core/base-path.ts";
  * data module all share one source of truth. Kept free of any Astro/template
  * imports so `core` can depend on it without a cycle.
  */
-export type ReferenceKind = "openapi" | "asyncapi";
+export type ReferenceKind = "openapi" | "asyncapi" | "graphql";
 /** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
 export type ReferenceRenderer = "blume" | "scalar";
 /** Per-block display options for the Blume renderer. */
@@ -49,6 +49,11 @@ export interface ReferenceSource {
     noindex: boolean;
     /** Local path or `http(s)` URL, verbatim from config. */
     spec: string;
+    /**
+     * URL of the live GraphQL endpoint the playground and code samples target
+     * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
+     */
+    endpoint?: string;
     /** Per-block Scalar theme name override, if any (Scalar renderer only). */
     theme?: string;
     /**
@@ -90,3 +95,18 @@ export declare const referenceRoutes: (config: ResolvedConfig) => string[];
 export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
 /** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
 export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;
+/**
+ * The reference kinds whose enabled, Blume-rendered playground opted into the
+ * built-in CORS proxy with `proxy: true`. A proxy URL string points at an
+ * external service, and `false` sends requests directly — neither routes
+ * through the endpoint. The generator's per-spec allowlist diagnostics key on
+ * this, so it shares one definition with {@link needsPlaygroundProxy}.
+ */
+export declare const builtinProxyKinds: (config: ResolvedConfig) => ReferenceKind[];
+/**
+ * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
+ * generated: some enabled Blume-rendered block's playground opted into it with
+ * `proxy: true`. Shared by the server feature gate and the generator so the
+ * two can never disagree.
+ */
+export declare const needsPlaygroundProxy: (config: ResolvedConfig) => boolean;

package/dist/types/seo/jsonld.d.ts

@@ -0,0 +1,105 @@
+import type { Crumb } from "../components/layout/nav-utils.ts";
+/** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
+type DateInput = string | Date | null;
+/** A schema.org `PostalAddress`; every part optional. */
+export interface PostalAddressIdentity {
+    addressCountry?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+    streetAddress?: string;
+}
+/**
+ * `seo.organization`: the organization behind the site, emitted on every page
+ * as an `Organization` node the WebSite and article nodes cite as publisher.
+ */
+export interface OrganizationIdentity {
+    address?: PostalAddressIdentity;
+    /** `ContactPoint.contactType`; only emitted with an email or telephone. */
+    contactType: string;
+    email?: string;
+    /** Absolute URL or root-relative path (absolutized like page URLs). */
+    logo?: string;
+    /** Defaults to the site title. */
+    name?: string;
+    /** Profile URLs (GitHub, X, LinkedIn, …) that identify the organization. */
+    sameAs: string[];
+    telephone?: string;
+    /** Defaults to the site origin. */
+    url?: string;
+}
+/**
+ * `seo.software`: the product the site documents, emitted on the homepage as
+ * a `SoftwareApplication` node — the identity type agents use to tell what a
+ * docs site is about.
+ */
+export interface SoftwareIdentity {
+    applicationCategory: string;
+    /** Defaults to the site description. */
+    description?: string;
+    /** License URL or SPDX identifier. */
+    license?: string;
+    /** Defaults to the site title. */
+    name?: string;
+    operatingSystem?: string;
+    /** Emitted as an `Offer` when set; `0` marks the software free. */
+    price?: number | string;
+    priceCurrency: string;
+    /** Package registry, repository, and profile URLs for the product. */
+    sameAs: string[];
+}
+/** The site-level identity nodes, from `seo.organization`/`seo.software`. */
+export interface StructuredDataIdentity {
+    organization?: OrganizationIdentity;
+    software?: SoftwareIdentity;
+}
+/** Inputs for a page's JSON-LD, all known at render time in RootLayout. */
+export interface StructuredDataInput {
+    siteName: string;
+    /** Absolute site origin, or null when `deployment.site` is unset. */
+    siteUrl: string | null;
+    title: string;
+    description?: string;
+    /** Page route, e.g. `/blog/post`. */
+    route: string;
+    /** Deployment base (`import.meta.env.BASE_URL`); prefixed onto absolute URLs. */
+    base?: string;
+    /** Content type — `blog` and `changelog` map to richer article types. */
+    pageType?: string;
+    /** Publish date (string or YAML Date); emitted as ISO `datePublished`. */
+    published?: DateInput;
+    /** Last-modified date; emitted as ISO `dateModified`. */
+    modified?: DateInput;
+    /** BCP-47 language tag for `inLanguage`; defaults to `en`. */
+    locale?: string;
+    breadcrumbs: Crumb[];
+    /**
+     * Site identity (`seo.organization`, `seo.software`). Both nodes need an
+     * absolute `@id`, so they are emitted only when `siteUrl` is set — like the
+     * WebSite node.
+     */
+    identity?: StructuredDataIdentity | null;
+}
+/** A value a schema.org node property can hold. */
+type JsonLdValue = string | number | JsonLdValue[] | JsonLdNode;
+/** A schema.org node: JSON-LD keys to concrete JSON values. */
+export interface JsonLdNode {
+    [key: string]: JsonLdValue;
+}
+/**
+ * Frontmatter date → ISO 8601, or undefined when absent/unparseable. Shared with
+ * the layout's `article:published_time`/`article:modified_time` so both date
+ * surfaces treat a malformed date the same way: omit it rather than emit
+ * "Invalid Date".
+ */
+export declare const toIso: (value: DateInput | undefined) => string | undefined;
+/**
+ * Build a schema.org JSON-LD `@graph` for a page: site identity (the WebSite,
+ * plus the configured Organization everywhere and the SoftwareApplication on
+ * the homepage), the page as an article, and its breadcrumb trail. Returns
+ * null when there is nothing useful to emit (e.g. the homepage without a
+ * configured site). URLs are absolute when `siteUrl` is set, otherwise
+ * route-relative.
+ */
+export declare const buildStructuredData: (input: StructuredDataInput) => JsonLdNode | null;
+export {};

package/dist/types/theme/fonts.d.ts

@@ -20,6 +20,11 @@ export interface RemoteFontConfig {
     provider?: RemoteFontProvider;
     /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
     weights?: (number | string)[];
+    /**
+     * Character subsets to load (`"latin"`, `"vietnamese"`, `"cyrillic"`, …).
+     * Defaults to `latin` plus whatever the site's configured locales need.
+     */
+    subsets?: string[];
     /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
     fallback?: FontCategory;
 }
@@ -52,6 +57,7 @@ export type FontEntry = {
     cssVariable: string;
     fallbacks: string[];
     name: string;
+    subsets: string[];
     weights: (number | string)[];
 } | {
     kind: "local";
@@ -193,19 +199,43 @@ export type FontSlug = keyof typeof GOOGLE_FONTS;
 export declare const FONT_SLUGS: string[];
 /** Type guard: is `value` a supported font slug? */
 export declare const isFontSlug: (value: string) => value is FontSlug;
+/** The shape of a config's `i18n` block the font builders read. */
+export interface FontLocaleSource {
+    locales: {
+        code: string;
+    }[];
+}
+/** The locale codes an optional `i18n` block declares (none when absent). */
+export declare const fontLocaleCodes: (i18n: FontLocaleSource | undefined) => string[];
+/**
+ * The subsets the site's locales need: `latin` always, plus each locale's
+ * script. A site with no `i18n` block (or only Latin-1 languages) gets just
+ * `latin` — Astro's own default — so its CSS and preloads don't change.
+ */
+export declare const localeFontSubsets: (locales: string[]) => string[];
 /** Kebab-case a family name into a slug (`"Noto Sans JP"` -> `"noto-sans-jp"`). */
 export declare const slugifyFontName: (name: string) => string;
-/** The unique Astro `fonts:` entries for the configured roles (deduped). */
-export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
+/**
+ * The unique Astro `fonts:` entries for the configured roles (deduped).
+ * `locales` are the site's configured locale codes; they pick the subsets a
+ * remote family loads unless its config pins `subsets` itself.
+ */
+export declare const buildFontEntries: (fonts: FontsConfig, locales?: string[]) => FontEntry[];
 /**
  * The config-token CSS that points each role's `--blume-font-<role>-src` at the
  * Astro-populated family variable. Concatenated into the generated entry's
  * config tokens; empty when no fonts are set so defaults stay the system stacks.
  */
 export declare const buildFontsCss: (fonts: FontsConfig) => string;
-/** One `<Font>` render in the head: its CSS variable + weights to preload. */
+/**
+ * One `<Font>` render in the head: its CSS variable + the weights (and, for
+ * providers that split faces by subset, the subsets) to preload. Local and
+ * Fontshare faces carry no subset, so those entries leave `preloadSubsets`
+ * unset and preload by weight alone.
+ */
 export interface FontHead {
     cssVariable: string;
+    preloadSubsets?: string[];
     preloadWeights: number[];
 }
 /**
@@ -213,4 +243,4 @@ export interface FontHead {
  * by CSS variable with preload weights unioned across the roles that share a
  * family (so `display` and `body` both set to Inter preload 400/500/600 once).
  */
-export declare const configuredFonts: (fonts: FontsConfig) => FontHead[];
+export declare const configuredFonts: (fonts: FontsConfig, locales?: string[]) => FontHead[];