blume 2.0.3 → 2.1.0

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

@@ -1,7 +1,12 @@
 import type { PageRecord } from "../types.ts";
+import type { ContentVariables } from "../variables.ts";
 import type { ContentSource } from "./types.ts";
 /** The subset of a scanned project the entry reader needs. */
 export interface EntryReadContext {
+    /** The site's content variables, substituted into what's read. */
+    config?: {
+        variables?: ContentVariables;
+    };
     /** The instantiated sources, keyed for `read()` lookups. */
     sources?: ContentSource[];
 }

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

@@ -297,7 +297,7 @@ export interface Navigation {
     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`). */
+    /** Repo URL for the footer's GitHub link, or null when hidden (`navigation.repo`). */
     repoUrl?: string | null;
     /**
      * Where the header's brand link points in this locale: `logo.href` moved

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

@@ -0,0 +1,42 @@
+/**
+ * Content variables: `variables: { version: "2.1.0" }` in `blume.config.ts`
+ * makes `{{version}}` in a page read `2.1.0` wherever it appears in the body,
+ * code and links included. The syntax is Mintlify's, so migrated pages keep
+ * working.
+ *
+ * Substitution is textual, before any parsing, so a page's HTML, its search
+ * entry, its `.md` mirror, and `llms-full.txt` all agree: the MDX pipeline
+ * substitutes in a Vite transform ahead of the compiler (an MDX parser would
+ * read `{{version}}` as a JavaScript expression), the Markdown pipeline in a
+ * plugin over the parsed text, includes as their files are read, and the raw
+ * readers through {@link substituteVariables}. Only defined names are
+ * replaced; an undefined one in prose is a build error
+ * (`BLUME_UNDEFINED_VARIABLE`), and inside code it is left alone, since
+ * templating examples (`{{name}}` in a Handlebars snippet) are common there.
+ */
+/** The variables a site defines, name to value. */
+export type ContentVariables = Readonly<Record<string, string>>;
+/** A variable name: letters, digits, `_`, and `-` (Mintlify's `api-url`). */
+export declare const VARIABLE_NAME: RegExp;
+/** Whether a site defines any variables, so the rest can be skipped. */
+export declare const hasVariables: (variables?: ContentVariables) => variables is ContentVariables;
+/** `text` with every reference to a defined variable replaced by its value. */
+export declare const substituteVariables: (text: string, variables?: ContentVariables) => string;
+/**
+ * {@link substituteVariables} over a page's raw source, leaving its front
+ * matter as written: the rendered page reads its title and description from
+ * the unsubstituted front matter, so the other surfaces must too.
+ */
+export declare const substituteVariablesInBody: (source: string, variables?: ContentVariables) => string;
+/** An undefined variable referenced in prose, with its 1-based line. */
+export interface UndefinedVariable {
+    line: number;
+    name: string;
+}
+/**
+ * The undefined variables `text` references outside code: fenced blocks and
+ * inline code spans are skipped, so a templating example never fails a
+ * build. Empty when the site defines no variables at all, so a page that
+ * shows `{{…}}` literally keeps working until the site opts in.
+ */
+export declare const undefinedVariables: (text: string, variables?: ContentVariables) => UndefinedVariable[];

package/dist/types/deploy/node-headers.d.ts

@@ -1,4 +1,5 @@
 import type { BlumeProject } from "../core/project-graph.ts";
+import type { CompiledRedirect } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { BuildLog } from "./platforms/types.ts";
 /**
@@ -34,19 +35,29 @@ export declare const nodeHeaderRules: (config: ResolvedConfig) => NodeHeaderRule
  */
 export type NodeRedirects = Record<string, [string, number]>;
 /**
- * The configured redirects, based the way the host matches them (see
+ * The configured exact redirects, based the way the host matches them (see
  * `platformRedirects`) and keyed for the wrapper's lookup, the `Location`
  * percent-encoded as Astro sends it. A redirect at a content route's own path
  * is left out: the prerendered page owns that URL, and the static handler
- * serves it before Astro's redirect ever could.
+ * serves it before Astro's redirect ever could. Patterns are compiled apart
+ * ({@link nodePatternRedirects}).
  */
 export declare const nodeRedirects: (project: BlumeProject) => NodeRedirects;
+/**
+ * The configured pattern redirects (`/beta/:slug*`), based the way the host
+ * matches them and compiled for the wrapper, which tries them in order after
+ * the exact ones. None can match a page: the scan rejects a pattern that
+ * does (`BLUME_REDIRECT_MATCHES_PAGE`).
+ */
+export declare const nodePatternRedirects: (project: BlumeProject) => CompiledRedirect[];
 /** What the wrapper needs beyond the header rules. */
 export interface NodeEntryOptions {
     /** `deployment.base`, normalized (`""` at the root). */
     base?: string;
     /** The configured redirects, from {@link nodeRedirects}. */
     redirects?: NodeRedirects;
+    /** The configured pattern redirects, from {@link nodePatternRedirects}. */
+    patternRedirects?: CompiledRedirect[];
 }
 /**
  * The entry that replaces Astro's: it answers a configured redirect with its

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

@@ -28,6 +28,11 @@ export declare const emitCloudflareDeployConfig: (context: ProjectContext) => Pr
  * built config instead, and is left alone.
  */
 export declare const nameCloudflareWorker: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Declare the Workers rate limiting binding `rateLimit: cloudflare()` counts
+ * with in the built Worker's config, which `wrangler deploy` reads.
+ */
+export declare const bindCloudflareRateLimit: (project: BlumeProject, log: BuildLog) => Promise<void>;
 /**
  * Cloudflare Workers and Pages. A server build emits the Worker into
  * `dist/server` and serves `dist/client` through the ASSETS binding, which

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

@@ -26,6 +26,13 @@ export declare const NETLIFY_CONFIG_FILE: string;
  * as static files, so the prerendered endpoint's own headers never ship.
  */
 export declare const emitNetlifyHeaders: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Carry the pattern redirects (`/beta/:slug*`) into a server build, as
+ * `redirects` in the Frameworks API config: Astro's `redirects` carry only
+ * the exact ones, since it can't prerender a pattern's pages, so the adapter
+ * never writes these. Netlify appends them after any rules of the user's own.
+ */
+export declare const emitNetlifyPatternRedirects: (project: BlumeProject) => Promise<void>;
 /**
  * Netlify. A server build runs on Netlify Functions from the Frameworks API
  * tree the adapter writes to `.netlify/v1`, relative to the Astro root —

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

@@ -20,6 +20,12 @@ 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>;
 /**
  * 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

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];
 /**
@@ -39,19 +43,22 @@ export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath
 export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => 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}, 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 +67,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/vercel-negotiation.d.ts

@@ -108,3 +108,12 @@ export declare const buildNegotiationRoutes: (routePaths: readonly string[], hom
  * `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;
+/**
+ * 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;

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/model.d.ts

@@ -45,6 +45,12 @@ export interface ApiOperationRef {
     deprecated: boolean;
     /** The channel the operation acts on (AsyncAPI only). */
     channelId?: string;
+    /**
+     * An OpenAPI 3.1 webhook: a request the API sends to the reader's endpoint
+     * rather than one it serves. `path` then holds the webhook's name, the key
+     * it has under the document's `webhooks`.
+     */
+    webhook?: true;
 }
 /**
  * A tag/section: the spec's declared tags in their declared order, then any
@@ -76,8 +82,8 @@ export interface ApiSpecData {
     /** Operations keyed by {@link ApiOperationRef.key}. */
     operations: Record<string, ApiOperationRef>;
     tags: ApiTagRef[];
-    /** Code-sample languages to render per operation. */
-    codeSamples: string[];
+    /** Code-sample languages to render per operation; `false` for none. */
+    codeSamples: string[] | false;
     /** Whether nested schema rows start expanded. */
     expandSchemas: boolean;
     /**
@@ -162,10 +168,10 @@ export interface ExtractedOperations extends CollectedOperations {
 export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
- * tags. Operations inherit the first tag they declare; keys are de-duplicated so
- * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item, webhooks), so missing operations
- * aren't silent.
+ * tags, webhooks included. Operations inherit the first tag they declare; keys
+ * are de-duplicated so a repeated `operationId` still yields distinct routes.
+ * `warnings` reports anything skipped (a `$ref` path item), so missing
+ * operations aren't silent.
  */
 export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */

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

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { JsonValue } from "../core/adapter.ts";
+/**
+ * OpenAPI Overlays: the OpenAPI Initiative's format for changing an API
+ * description without editing it — an ordered list of actions, each an RFC
+ * 9535 JSONPath `target` with an `update` to merge in, a `copy` of another
+ * node to merge in, or `remove`. A spec generated by another tool or owned by
+ * another team can then carry docs-only changes (better descriptions, hidden
+ * internal operations, a public server URL) in a file of its own.
+ *
+ * Implements Overlay Specification 1.0 and 1.1 over `jsonpath-rfc9535`, which
+ * passes the JSONPath compliance suite in full, as the spec requires. The
+ * documents here are already parsed; `parse.ts` reads the files.
+ */
+/** An overlay document or action that doesn't follow the spec. */
+export declare class OverlayError extends Error {
+    constructor(message: string);
+}
+/** An object node, the only kind that holds named properties. */
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * A parsed YAML or JSON mapping, as the document an overlay acts on: the
+ * parser's own types say nothing of JSON, but what it parses is JSON.
+ */
+export declare const isJsonObject: <Value>(value: Value) => value is Value & JsonObject;
+declare const overlaySchema: z.ZodObject<{
+    actions: z.ZodArray<z.ZodObject<{
+        copy: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        remove: z.ZodDefault<z.ZodBoolean>;
+        target: z.ZodString;
+        update: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$loose>>;
+    extends: z.ZodOptional<z.ZodString>;
+    info: z.ZodObject<{
+        title: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>;
+    overlay: z.ZodString;
+}, z.core.$loose>;
+/** A validated overlay document. */
+export type OverlayDocument = z.output<typeof overlaySchema>;
+/** Validate a parsed overlay document, naming the file in any error. */
+export declare const overlayDocument: <Value>(value: Value, name: string) => OverlayDocument;
+/**
+ * Apply an overlay to a parsed document, in place and in action order: each
+ * action sees the result of the one before. A target that matches nothing
+ * changes nothing. Throws an {@link OverlayError} naming the overlay file and
+ * the action that failed.
+ */
+export declare const applyOverlay: (document: JsonValue, overlay: OverlayDocument, name: string) => void;
+export {};