blume 2.0.3 → 2.1.1

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;
@@ -20,6 +21,28 @@ export declare const checkVercelFunctionBundles: (outputDir: string, root: strin
  * root it was shown.
  */
 export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Route the pattern redirects (`/beta/:slug*`) in the adapter's Build Output
+ * config: Astro's `redirects` carry only the exact ones, since it can't
+ * 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
@@ -28,6 +51,8 @@ export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLo
  * 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

@@ -2,12 +2,16 @@ import type { RouteSet } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { VercelHeader } from "./headers.ts";
+import type { VercelRoute } from "./vercel-negotiation.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).
+ * manifest for anything else (Apache/nginx rules, an edge worker). A pattern
+ * redirect (`/beta/:slug*`) gets no redirect page, since Astro can't
+ * prerender one for paths it doesn't know; each host file carries it in that
+ * host's syntax (see `core/redirect-patterns.ts`).
  */
 type Redirect = ResolvedConfig["redirects"][number];
 /**
@@ -37,21 +41,40 @@ 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}. 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.
+ * {@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
+ * real served URLs.
  */
 export declare const platformRedirects: (project: {
     config: ResolvedConfig;
     manifest: Pick<BlumeProject["manifest"], "routes">;
 }) => Redirect[];
 /**
- * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
- * `force` appends Netlify's `!` to each status (`301!`), so the rule wins over
- * the redirect page Astro writes at `from`; Cloudflare, which always applies
- * its rules first, rejects a line carrying it.
+ * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line,
+ * a pattern as `:placeholder`s and a `*` splat the destination reads as
+ * `:splat`. `force` appends Netlify's `!` to each status (`301!`), so the rule
+ * wins over the redirect page Astro writes at `from`; Cloudflare, which always
+ * applies its rules first, rejects a line carrying it.
  */
 export declare const buildNetlifyRedirects: (redirects: Redirect[], force?: boolean) => string;
 /**
@@ -60,10 +83,31 @@ export declare const buildNetlifyRedirects: (redirects: Redirect[], force?: bool
  * 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. A `source` is a
- * `path-to-regexp` pattern, so each exact `from` path is escaped: unescaped,
- * `/c++-guide` fails the whole config and `/faq(old)` never matches.
+ * `path-to-regexp` pattern, so each literal run of a `from` path is escaped:
+ * unescaped, `/c++-guide` fails the whole config and `/faq(old)` never
+ * matches. A pattern's captures are `path-to-regexp` params.
  */
 export declare const buildVercelConfig: (redirects: Redirect[], headers?: readonly VercelHeader[]) => string;
-/** Structured manifest for hosts that need manual wiring. */
+/**
+ * The pattern redirects as `_redirects` entries, for the `redirects` of a
+ * Netlify server build's Frameworks API config (see
+ * {@link buildNetlifyRedirects} for the syntax).
+ */
+export declare const netlifyPatternRedirects: (redirects: Redirect[]) => {
+    from: string;
+    status: number;
+    to: string;
+}[];
+/**
+ * The pattern redirects as Build Output API routes, for a Vercel server
+ * build: the adapter routes only the exact redirects Astro's config carries.
+ * Each matches the served path, a trailing slash optional, and fills its
+ * `Location` from numbered captures, as the adapter's own redirect routes do.
+ */
+export declare const vercelPatternRoutes: (redirects: Redirect[]) => VercelRoute[];
+/**
+ * Structured manifest for hosts that need manual wiring. A pattern stays as
+ * configured (`/beta/:slug*`), for the rule it becomes to be written by hand.
+ */
 export declare const buildRedirectManifest: (redirects: Redirect[]) => string;
 export {};

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,9 +106,35 @@ 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
+ * `handle: "filesystem"`: after the exact redirects the adapter puts first,
+ * so an exact path still wins. A second pass replaces its own routes. 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 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/markdown/code-title.d.ts

@@ -7,7 +7,20 @@
  *   language label.
  * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
+ * - the `wrap` keyword becomes `data-wrap`: this block's long lines wrap
+ *   instead of scrolling, as `markdown.code.wrap` does for every block.
+ * - the `expandable` keyword becomes `data-expandable` on a block of
+ *   {@link EXPANDABLE_MIN_LINES} lines or more: the theme shows its first
+ *   {@link EXPANDABLE_VISIBLE_LINES} lines, and the page script adds a toggle
+ *   that shows the rest in full. A shorter block renders as it is.
  */
+/** The lines a collapsed `expandable` block shows. */
+export declare const EXPANDABLE_VISIBLE_LINES = 10;
+/**
+ * The lines a block needs before `expandable` collapses it: a few more than it
+ * shows, so the toggle never hides a line or two behind a click.
+ */
+export declare const EXPANDABLE_MIN_LINES = 16;
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
     options: {
@@ -15,6 +28,8 @@ interface CodeMetaContext {
             __raw?: string;
         };
     };
+    /** The block's code, as highlighted. */
+    source?: string;
 }
 /** The `<pre>` hast node a Shiki `pre` hook receives. */
 interface PreNode {
@@ -27,6 +42,8 @@ export interface CodeTitleTransformer {
 }
 /** The title a fence's meta string promotes to `data-title`, if any. */
 export declare const parseCodeTitle: (raw: string | undefined) => string | undefined;
+/** How many lines a block's code runs to, a trailing newline aside. */
+export declare const lineCount: (source?: string) => number;
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export declare const codeTitleTransformer: () => CodeTitleTransformer;
 export {};

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

@@ -8,8 +8,9 @@ export declare const MARKDOWN_FEATURES: {
 };
 /**
  * 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 `$$…$$`.
+ * math — `singleDollarTextMath: false` keeps a bare `$` (currency, shell,
+ * code) as literal text and only parses `$$…$$`, as a block on its own lines
+ * or inline within a sentence.
  */
 export declare const MDX_FEATURES: {
     directive: true;

package/dist/types/narration/build.d.ts

@@ -0,0 +1,70 @@
+import { HTMLElement } from "node-html-parser";
+import type { Node } from "node-html-parser";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ProjectContext } from "../core/types.ts";
+import type { NarrationProvider } from "./provider.ts";
+import type { NarrationCues, NarrationTree } from "./script.ts";
+/**
+ * Generated narration: after Astro writes the HTML, read every page that
+ * carries the player exactly as the browser will (same walker, same blocks),
+ * split it into sentences, and give each sentence a clip from the configured
+ * speech model. Clips are cached by what decides their sound (text, language,
+ * model, voice, instructions, provider options), so a rebuild only pays for
+ * sentences that changed, and one sentence shared by many pages is generated
+ * once. Each page gets a manifest listing its clips; the player plays them in
+ * order and falls back to browser voices wherever a manifest is missing.
+ */
+/** How the build logs: the integration's Astro logger. */
+export interface NarrationLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+}
+/** Speak `text` in `lang`, returning MP3 bytes. */
+export type Speak = (text: string, lang: string) => Promise<Uint8Array>;
+/** What a narration build did, for the log line and tests. */
+export interface NarrationBuildResult {
+    /** Clips that failed to generate; their pages get no manifest. */
+    failed: number;
+    /** Clips generated by the speech model on this build. */
+    generated: number;
+    /** Pages that got a manifest. */
+    pages: number;
+    /** Clips read back from the cache. */
+    reused: number;
+}
+/**
+ * The clip cache directory: `node_modules/.cache/blume/narration`, next to the
+ * OG card cache and restored by the same host build caches (see `ogCacheDir`).
+ */
+export declare const narrationCacheDir: (context: Pick<ProjectContext, "outDir" | "root">) => string;
+/** The walker's view of a node-html-parser tree. */
+export declare const htmlTree: NarrationTree<Node>;
+/** The player's settings on a built page, and the article it reads. */
+interface PlayerPage {
+    article: HTMLElement;
+    audioBase: string;
+    cues: NarrationCues;
+    lang: string;
+    manifest: string;
+}
+/**
+ * The generated player on a built page, or `null` when the page has none (or
+ * a player without generated audio, which reads with browser voices).
+ */
+export declare const readPlayerPage: (html: string) => PlayerPage | null;
+/**
+ * A clip's cache key: a digest of everything that decides how it sounds. The
+ * Blume version is deliberately left out, unlike the OG card's: an upgrade
+ * shouldn't pay to regenerate audio that would sound the same.
+ */
+export declare const clipKey: (provider: NarrationProvider, lang: string, text: string) => string;
+/** Speak through the Vercel AI Gateway with the provider's model and voice. */
+export declare const gatewaySpeaker: (provider: NarrationProvider) => Speak;
+/**
+ * Generate the narration for a built site in `distDir`: a clip per sentence
+ * and a manifest per page. Does nothing unless `narration.provider` is set,
+ * and warns instead of generating when the provider's key is missing (the
+ * pages then read with browser voices). `speak` replaces the gateway call.
+ */
+export declare const buildNarration: (project: BlumeProject, distDir: string, logger: NarrationLogger, speak?: Speak) => Promise<NarrationBuildResult | null>;
+export {};

package/dist/types/narration/provider.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+/** The speech model narration uses when `gateway()` names none. */
+export declare const DEFAULT_NARRATION_MODEL = "openai/tts-1-hd";
+/** The voice narration uses when `gateway()` names none. */
+export declare const DEFAULT_NARRATION_VOICE = "alloy";
+/**
+ * `narration.provider`: the `gateway()` descriptor from `blume/ai`, read with
+ * speech defaults. `reasoning` is an assistant option and is rejected here;
+ * `voice` and `instructions` are narration options and are rejected by the
+ * assistant.
+ */
+export declare const narrationProviderSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"gateway">;
+    options: z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+        model: z.ZodDefault<z.ZodString>;
+        voice: z.ZodDefault<z.ZodString>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** A validated narration provider, defaults filled in. */
+export type NarrationProvider = z.output<typeof narrationProviderSchema>;

package/dist/types/narration/script.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Narration's reading script: what "Listen to this page" says, in order, and
+ * where each spoken sentence sits in the page's text.
+ *
+ * One walker serves both sides. `blume build` runs it over the built HTML
+ * (parsed with node-html-parser) to generate a clip per sentence, and the
+ * player runs it over the live `<article>` to highlight the sentence being
+ * read. Both see the same markup and apply the same rules, so they agree on
+ * every block's text; the sentence split is only ever computed once per
+ * engine (by the build for generated audio, by the browser for its own
+ * voices), so an ICU difference between Node and the browser can't move a
+ * highlight.
+ *
+ * The rules follow what reads well aloud: the title, description, headings,
+ * and prose are read in order; callouts, steps, tabs, and collapsible
+ * sections are announced with a short spoken cue; code, tables, media,
+ * diagrams, math, API field tables, and anything marked
+ * `data-blume-narration="skip"` are left out.
+ */
+/**
+ * The slice of a DOM-like tree the walker reads. The browser DOM and
+ * node-html-parser both satisfy it through a small adapter, so the walker
+ * never touches either API directly.
+ */
+export interface NarrationTree<N> {
+    /** An element's attribute, or `null` when it is absent. */
+    attr: (node: N, name: string) => string | null;
+    children: (node: N) => readonly N[];
+    /** An element's lowercase tag name; `null` for text and other nodes. */
+    tag: (node: N) => string | null;
+    /** A text node's decoded text; `null` for elements and other nodes. */
+    text: (node: N) => string | null;
+}
+/**
+ * The spoken cues, already localized for the page. `{n}` in `step` is the
+ * step's number and `{title}` in `tab` is the tab's label. An empty string
+ * silences that cue.
+ */
+export interface NarrationCues {
+    danger: string;
+    info: string;
+    note: string;
+    section: string;
+    step: string;
+    success: string;
+    tab: string;
+    tip: string;
+    warning: string;
+}
+/**
+ * A run of text read as one unit: a paragraph, heading, list item, or any
+ * other block. `nodes` are the text nodes it was read from; `nodeOf[i]` and
+ * `offsetOf[i]` locate character `i` of `text` in them, so a sentence's
+ * `[start, end)` maps back to a DOM range for highlighting.
+ */
+export interface NarrationBlock<N> {
+    nodeOf: number[];
+    nodes: N[];
+    offsetOf: number[];
+    text: string;
+}
+/** One step of the reading order: a spoken cue, or a block of page text. */
+export type NarrationItem = {
+    block: number;
+    kind: "block";
+} | {
+    kind: "cue";
+    text: string;
+};
+/** What {@link extractNarration} reads from a page. */
+export interface NarrationExtract<N> {
+    blocks: NarrationBlock<N>[];
+    items: NarrationItem[];
+}
+/**
+ * One spoken unit. A sentence carries its block and its `[start, end)` in
+ * that block's text; a cue carries `block: null`. `text` is what is spoken.
+ */
+export interface NarrationSegment {
+    block: number | null;
+    end: number;
+    start: number;
+    text: string;
+}
+/**
+ * The per-page manifest `blume build` writes for generated narration. The
+ * player aligns `blocks` (the build's block texts) with the live page by
+ * text, then plays one clip per segment. A sentence names its block and range;
+ * a cue carries its spoken `text` instead.
+ */
+export interface NarrationManifest {
+    blocks: string[];
+    segments: NarrationManifestSegment[];
+    version: 1;
+}
+/** One clip of a {@link NarrationManifest}: a sentence or a cue. */
+export type NarrationManifestSegment = {
+    audio: string;
+    block: number;
+    end: number;
+    start: number;
+} | {
+    audio: string;
+    text: string;
+};
+/**
+ * A page needs at least this many spoken characters (title and description
+ * included) to offer narration: roughly 50 English words. Shorter pages, and
+ * pages that are mostly code, tables, or API fields, get no player.
+ */
+export declare const NARRATION_MIN_CHARS = 280;
+/**
+ * Sentences longer than this are split at a clause, then a word boundary.
+ * Browser speech engines drop an utterance that runs past about 15 seconds,
+ * and shorter clips also keep the highlight moving.
+ */
+export declare const NARRATION_MAX_SEGMENT_CHARS = 220;
+/** The attribute that keeps an element (and everything in it) out of narration. */
+export declare const NARRATION_SKIP_ATTRIBUTE = "data-blume-narration";
+/**
+ * Walk `root` and return its reading order: each block of text, with the
+ * cues that introduce callouts, steps, tabs, and collapsible sections.
+ * Whitespace collapses to single spaces, as it renders.
+ */
+export declare const extractNarration: <N>(root: N, tree: NarrationTree<N>, cues: NarrationCues) => NarrationExtract<N>;
+/**
+ * Split an extract into spoken segments: a cue as it is, and each block into
+ * its sentences for `lang` (long ones broken further, see
+ * {@link NARRATION_MAX_SEGMENT_CHARS}).
+ */
+export declare const segmentNarration: <N>(extract: NarrationExtract<N>, lang: string, max?: number) => NarrationSegment[];
+/** How many characters the page's blocks will speak, cues excluded. */
+export declare const narrationLength: <N>(extract: NarrationExtract<N>) => number;
+/** Whether a page has enough prose to offer narration. */
+export declare const isNarratable: <N>(extract: NarrationExtract<N>) => boolean;
+/**
+ * Characters read per second at 1x: about 170 words a minute for
+ * space-separated scripts, and a slower character rate where a character is a
+ * word or more. Estimates only; neither engine reports durations up front.
+ */
+export declare const narrationCharsPerSecond: (lang: string) => number;
+/** The page's estimated listening time at 1x, in whole minutes (at least 1). */
+export declare const narrationMinutes: (chars: number, lang: string) => number;
+/**
+ * Map each manifest block onto the live page's blocks by exact text, in
+ * order, skipping page blocks the build didn't see (a script may have added
+ * some). A manifest block with no match maps to `-1`: its sentences still
+ * play, without a highlight.
+ */
+export declare const alignBlocks: (manifestBlocks: readonly string[], pageBlocks: readonly string[]) => number[];
+/** Whether a value (the player's `data-cues` JSON) is a full set of cues. */
+export declare const isNarrationCues: (value: unknown) => value is NarrationCues;
+/** Whether a fetched manifest has the shape the player plays. */
+export declare const isNarrationManifest: (value: unknown) => value is NarrationManifest;

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[];