blume 2.1.1 → 2.1.3

package/src/narration/build.ts

@@ -10,15 +10,24 @@ import {
   writeFile,
 } from "node:fs/promises";
 
+import type * as OpenAISdk from "@ai-sdk/openai";
+import type { OpenAIProvider } from "@ai-sdk/openai";
 import { createGateway, generateSpeech } from "ai";
+import type { SpeechModel } from "ai";
 import { HTMLElement, parse, TextNode } from "node-html-parser";
 import type { Node } from "node-html-parser";
 import { dirname, join } from "pathe";
 
 import { normalizeBasePath } from "../core/base-path.ts";
+import { nodeRequire } from "../core/node-require.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
-import type { NarrationProvider } from "./provider.ts";
+import { hasCredentials, OPENAI_SPEECH_DEP } from "./provider.ts";
+import type {
+  GatewayNarrationProvider,
+  NarrationProvider,
+  OpenAINarrationProvider,
+} from "./provider.ts";
 import {
   extractNarration,
   isNarratable,
@@ -37,10 +46,11 @@ import type {
  * 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.
+ * model, voice, instructions, provider options, endpoint), 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. */
@@ -54,7 +64,10 @@ 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. */
+  /**
+   * Clips that failed to generate, or that a missing key left ungenerated;
+   * their pages get no manifest.
+   */
   failed: number;
   /** Clips generated by the speech model on this build. */
   generated: number;
@@ -67,6 +80,13 @@ export interface NarrationBuildResult {
 // Bump to regenerate every clip: part of every cache key.
 const CLIP_FORMAT = 1;
 
+// Where `openai()` speaks with neither a `baseUrl` nor `OPENAI_BASE_URL`.
+const OPENAI_API_URL = "https://api.openai.com/v1";
+
+// What `generateSpeech` reports for bytes it recognized as MP3. Bytes it can't
+// place at all (a web page, raw PCM) default to `audio/mp3` instead.
+const MP3_MEDIA_TYPE = "audio/mpeg";
+
 // Parallel speech requests. Low enough to stay inside provider rate limits on
 // a first build of a large site, where every sentence is new.
 const CONCURRENCY = 4;
@@ -144,23 +164,52 @@ export const readPlayerPage = (html: string): PlayerPage | null => {
 const speechLanguage = (lang: string): string =>
   lang.toLowerCase().replaceAll("_", "-").split("-")[0] ?? lang;
 
+/**
+ * The server `openai()` speaks to: its `baseUrl`, else `OPENAI_BASE_URL` as
+ * OpenAI's SDKs read it, else OpenAI, without a trailing slash, which the SDK
+ * drops too. Resolved here rather than left to the SDK, so the clip key names
+ * the server the clips come from.
+ */
+const openaiEndpoint = (provider: OpenAINarrationProvider): string =>
+  (
+    provider.options.baseUrl ||
+    process.env.OPENAI_BASE_URL ||
+    OPENAI_API_URL
+  ).replace(/\/+$/u, "");
+
+/** The server a provider's clips come from: none named for `gateway()`. */
+const speakerEndpoint = (provider: NarrationProvider): string | undefined =>
+  provider.kind === "openai" ? openaiEndpoint(provider) : undefined;
+
 /**
  * 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.
+ * shouldn't pay to regenerate audio that would sound the same. A build
+ * resolves `endpoint` once and passes it in, rather than reading the
+ * environment for every sentence.
  */
 export const clipKey = (
   provider: NarrationProvider,
   lang: string,
-  text: string
+  text: string,
+  endpoint = speakerEndpoint(provider)
 ): string => {
   const { instructions, model, providerOptions, voice } = provider.options;
+  const gateway = provider.kind === "gateway";
   return createHash("sha256")
     .update(
       JSON.stringify({
+        // Which server speaks: none for `gateway()`, which JSON drops, so its
+        // clips keep the keys they had before narration took other providers.
+        endpoint: gateway
+          ? undefined
+          : { baseUrl: endpoint, kind: provider.kind },
         format: CLIP_FORMAT,
         instructions,
-        lang: speechLanguage(lang),
+        // Only the gateway is sent a language (`openaiSpeaker` sends none), so
+        // an `openai()` sentence sounds the same in every locale and is
+        // generated once.
+        lang: gateway ? speechLanguage(lang) : undefined,
         model,
         providerOptions,
         text,
@@ -172,7 +221,7 @@ export const clipKey = (
 };
 
 /** Speak through the Vercel AI Gateway with the provider's model and voice. */
-export const gatewaySpeaker = (provider: NarrationProvider): Speak => {
+export const gatewaySpeaker = (provider: GatewayNarrationProvider): Speak => {
   const { apiKeyEnv, headers, instructions, model, providerOptions, voice } =
     provider.options;
   const gateway = createGateway({ apiKey: process.env[apiKeyEnv], headers });
@@ -190,6 +239,104 @@ export const gatewaySpeaker = (provider: NarrationProvider): Speak => {
   };
 };
 
+/**
+ * `fetch` for a keyless request: `createOpenAI` always sends the key as a
+ * bearer token, so an empty one would arrive as a bare `Bearer` that servers
+ * and proxies checking auth can reject. An `Authorization` from `headers`
+ * stays.
+ */
+const withoutEmptyBearer = async (
+  input: Parameters<typeof fetch>[0],
+  init?: RequestInit
+): Promise<Response> => {
+  const headers = new Headers(init?.headers);
+  if (headers.get("authorization") === "Bearer") {
+    headers.delete("authorization");
+  }
+  return await fetch(input, { ...init, headers });
+};
+
+/**
+ * Speak through OpenAI's speech API, or with `baseUrl` through any server
+ * that serves it (`POST /audio/speech`): Kokoro-FastAPI, Speaches, LiteLLM.
+ * That API takes no language, so none is sent and the model or voice
+ * decides it. Without a key, no bearer token is sent (an `Authorization` in
+ * `headers` still is). A build resolves `baseURL` once and passes it in.
+ */
+export const openaiSpeaker = (
+  provider: OpenAINarrationProvider,
+  baseURL = openaiEndpoint(provider)
+): Speak => {
+  const { apiKeyEnv, headers, instructions, model, providerOptions, voice } =
+    provider.options;
+  // Made on the first clip rather than up front, so what can go wrong here
+  // fails that clip and the build carries on with browser voices: an ejected
+  // app's `astro build` runs no dependency preflight, and `OPENAI_BASE_URL`
+  // isn't validated the way `baseUrl` is.
+  const connect = (): OpenAIProvider => {
+    if (hasCredentials(baseURL)) {
+      throw new Error(
+        "OPENAI_BASE_URL has credentials in it, which fetch won't send: name the env var holding the key in apiKeyEnv instead"
+      );
+    }
+    // `require`, not `import()`: this runs in `astro:build:done` (see
+    // `core/node-require.ts`).
+    const { createOpenAI }: typeof OpenAISdk = nodeRequire(OPENAI_SPEECH_DEP);
+    const apiKey = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+    return createOpenAI({
+      // Never undefined: the SDK would fall back to OPENAI_API_KEY and send
+      // that to a custom endpoint that names no key.
+      apiKey: apiKey ?? "",
+      baseURL,
+      // SAFETY: the SDK only calls it, so Bun's `fetch.preconnect` (which its
+      // `typeof fetch` adds) is never read.
+      fetch: apiKey ? undefined : (withoutEmptyBearer as typeof fetch),
+      headers,
+    });
+  };
+  let openai: OpenAIProvider | undefined;
+  return async (text) => {
+    openai ??= connect();
+    const { audio, responses } = await generateSpeech({
+      instructions,
+      // SAFETY: both sides are the same `SpeechModelV4` spec. `ai` and
+      // `@ai-sdk/openai` each pin their own `@ai-sdk/provider`, and the type
+      // only differs between those copies, not in what `generateSpeech` calls.
+      model: openai.speech(model) as SpeechModel,
+      outputFormat: "mp3",
+      providerOptions,
+      text,
+      voice,
+    });
+    // The SDK takes any 2xx body as audio, and the clip is cached and served
+    // as an MP3 whatever it holds, so a page a redirect led to (an SSO
+    // proxy's sign-in, say) or WAV from a server that ignores
+    // `response_format` would be reused on every build after: fail the clip
+    // unless its bytes are MP3.
+    if (audio.mediaType !== MP3_MEDIA_TYPE) {
+      const type = responses[0]?.headers?.["content-type"] ?? "no content type";
+      throw new Error(`The speech server answered with ${type}, not MP3 audio`);
+    }
+    return audio.uint8Array;
+  };
+};
+
+/**
+ * The env var a build needs to generate with `provider` and doesn't have, or
+ * `null` when it can go ahead: the key is set, Vercel's OIDC token stands in
+ * for the gateway's, or the provider names no key (`openai()` with a
+ * `baseUrl` and no `apiKeyEnv`).
+ */
+export const missingKey = (provider: NarrationProvider): string | null => {
+  const env = provider.options.apiKeyEnv;
+  if (env === undefined || process.env[env]) {
+    return null;
+  }
+  return provider.kind === "gateway" && process.env.VERCEL_OIDC_TOKEN
+    ? null
+    : env;
+};
+
 /** Every `.html` file under `dir`. */
 const listHtml = async (dir: string): Promise<string[]> => {
   const entries = await readdir(dir, { recursive: true, withFileTypes: true });
@@ -274,35 +421,23 @@ const manifestFor = (plan: PagePlan): NarrationManifest => ({
   version: 1,
 });
 
+/** What a build narrates: each page's plan, and every clip by its key. */
+interface SitePlan {
+  /** Where the clips are published, or `null` with no narratable page. */
+  audioDir: string | null;
+  plans: PagePlan[];
+  texts: Map<string, { lang: string; text: string }>;
+}
+
 /**
- * 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.
+ * Read every built page that carries the player and plan its narration,
+ * keying each sentence's clip with `keyFor`.
  */
-export const buildNarration = async (
-  project: BlumeProject,
+const planSite = async (
   distDir: string,
-  logger: NarrationLogger,
-  speak?: Speak
-): Promise<NarrationBuildResult | null> => {
-  const { narration } = project.config;
-  const { provider } = narration;
-  if (!(narration.enabled && provider)) {
-    return null;
-  }
-  const env = provider.options.apiKeyEnv;
-  if (!(speak || process.env[env] || process.env.VERCEL_OIDC_TOKEN)) {
-    logger.warn(
-      `Narration audio was not generated: ${env} is not set, so pages will be read with browser voices.`
-    );
-    return null;
-  }
-  const say = speak ?? gatewaySpeaker(provider);
-  const base = normalizeBasePath(project.config.deployment.options.base);
-
-  // Read every page first, so the log can say what generation will cost
-  // before any of it is spent.
+  base: string,
+  keyFor: (lang: string, text: string) => string
+): Promise<SitePlan> => {
   const plans: PagePlan[] = [];
   const texts = new Map<string, { lang: string; text: string }>();
   let audioDir: string | null = null;
@@ -322,7 +457,7 @@ export const buildNarration = async (
     audioDir ??= distPath(distDir, base, page.audioBase);
     const segments = segmentNarration(extract, page.lang);
     const keys = segments.map((segment) => {
-      const key = clipKey(provider, page.lang, segment.text);
+      const key = keyFor(page.lang, segment.text);
       texts.set(key, { lang: page.lang, text: segment.text });
       return key;
     });
@@ -333,6 +468,37 @@ export const buildNarration = async (
       segments,
     });
   }
+  return { audioDir, plans, texts };
+};
+
+/**
+ * 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.
+ * When new clips are needed and the provider's key is missing, it warns and
+ * generates nothing, so only pages whose clips are all cached get audio (the
+ * rest read with browser voices). `speak` replaces the provider call.
+ */
+export const buildNarration = async (
+  project: BlumeProject,
+  distDir: string,
+  logger: NarrationLogger,
+  speak?: Speak
+): Promise<NarrationBuildResult | null> => {
+  const { narration } = project.config;
+  const { provider } = narration;
+  if (!(narration.enabled && provider)) {
+    return null;
+  }
+  const endpoint = speakerEndpoint(provider);
+  const base = normalizeBasePath(project.config.deployment.options.base);
+
+  // Read every page first, so the log can say what generation will cost
+  // before any of it is spent.
+  const { audioDir, plans, texts } = await planSite(
+    distDir,
+    base,
+    (lang, text) => clipKey(provider, lang, text, endpoint)
+  );
   if (!audioDir || plans.length === 0) {
     return { failed: 0, generated: 0, pages: 0, reused: 0 };
   }
@@ -341,7 +507,14 @@ export const buildNarration = async (
   const cached = (key: string) => join(cacheDir, `${key}.mp3`);
   const missing = [...texts.keys()].filter((key) => !existsSync(cached(key)));
   const reused = texts.size - missing.length;
-  if (missing.length > 0) {
+  // Checked only once something needs generating, so a build without the key
+  // (a fork's pull request, say) still ships every clip the cache restored.
+  const env = speak || missing.length === 0 ? null : missingKey(provider);
+  if (env) {
+    logger.warn(
+      `Narration audio was not generated: ${env} is not set, so pages missing clips will be read with browser voices.`
+    );
+  } else if (missing.length > 0) {
     const chars = missing.reduce(
       (total, key) => total + (texts.get(key)?.text.length ?? 0),
       0
@@ -350,13 +523,18 @@ export const buildNarration = async (
       `Generating narration: ${missing.length} new clip(s), ${chars.toLocaleString("en-US")} characters, with ${provider.options.model}`
     );
   }
+  const say =
+    speak ??
+    (provider.kind === "gateway"
+      ? gatewaySpeaker(provider)
+      : openaiSpeaker(provider, endpoint));
 
   // The AI SDK already retries a transient failure, so one that gets through
   // (a bad key, an unknown model, a spent quota) would fail every clip after
   // it too: stop generating at the first, and keep what's already cached.
-  const failures = new Set<string>();
+  const failures = new Set(env ? missing : []);
   let firstError: string | null = null;
-  await eachLimited(missing, CONCURRENCY, async (key) => {
+  await eachLimited(env ? [] : missing, CONCURRENCY, async (key) => {
     const entry = texts.get(key);
     if (!entry || firstError !== null) {
       failures.add(key);

package/src/narration/provider.ts

@@ -1,29 +1,109 @@
 import { z } from "zod";
 
-import { GATEWAY_API_KEY_ENV, sharedOptions } from "../ai/ask.ts";
+import {
+  GATEWAY_API_KEY_ENV,
+  OPENAI_API_KEY_ENV,
+  sharedOptions,
+} from "../ai/ask.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 
 /** The speech model narration uses when `gateway()` names none. */
 export const DEFAULT_NARRATION_MODEL = "openai/tts-1-hd";
 
-/** The voice narration uses when `gateway()` names none. */
+/** The voice narration uses when the provider names none. */
 export 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.
+ * The AI SDK provider `openai()` narration speaks through, with or without a
+ * `baseUrl`: `@ai-sdk/openai-compatible` has no speech models.
  */
-export const narrationProviderSchema = adapterDescriptorSchema(
+export const OPENAI_SPEECH_DEP = "@ai-sdk/openai";
+
+/**
+ * Whether `url` carries a username or password, which `fetch` refuses to
+ * send and whose error message would print them. A URL that doesn't parse
+ * has none.
+ */
+export const hasCredentials = (url: string): boolean => {
+  const parsed = URL.parse(url);
+  return Boolean(parsed?.username || parsed?.password);
+};
+
+/** The narration options both providers take on top of the shared ones. */
+const speechOptions = {
+  instructions: z.string().min(1).optional(),
+  voice: z.string().min(1).default(DEFAULT_NARRATION_VOICE),
+};
+
+const gatewayNarrationSchema = adapterDescriptorSchema(
   "gateway",
   z.strictObject({
     ...sharedOptions(GATEWAY_API_KEY_ENV),
-    instructions: z.string().min(1).optional(),
+    ...speechOptions,
     model: z.string().min(1).default(DEFAULT_NARRATION_MODEL),
-    voice: z.string().min(1).default(DEFAULT_NARRATION_VOICE),
   })
 );
 
+const openaiNarrationSchema = adapterDescriptorSchema(
+  "openai",
+  z.strictObject({
+    ...sharedOptions(OPENAI_API_KEY_ENV),
+    ...speechOptions,
+    // Replaces the shared default: whether it's OPENAI_API_KEY depends on
+    // the `baseUrl` (see below).
+    apiKeyEnv: z.string().min(1).optional(),
+    // An unparsable URL is left to `z.url()`.
+    baseUrl: z
+      .url()
+      .refine((url) => !hasCredentials(url), {
+        message:
+          "Credentials don't go in the baseUrl: name the env var holding the key in apiKeyEnv.",
+      })
+      .optional(),
+    model: z.string().min(1),
+  })
+);
+
+/**
+ * `narration.provider`: the `gateway()` or `openai()` descriptor from
+ * `blume/ai`, read with speech defaults. `reasoning` (and `openai()`'s
+ * `name`, which speech models don't read) are assistant options and are
+ * rejected here; `voice` and `instructions` are narration options and are
+ * rejected by the assistant.
+ *
+ * `openai()` is read for what narration needs, not what the assistant does:
+ * it speaks through `@ai-sdk/openai` whatever the `baseUrl`, and a custom
+ * endpoint gets only the key `apiKeyEnv` names, never `OPENAI_API_KEY` by
+ * default, so it may take none at all. A key that is named is required.
+ */
+export const narrationProviderSchema = z
+  .discriminatedUnion("kind", [gatewayNarrationSchema, openaiNarrationSchema])
+  .transform((provider) => {
+    if (provider.kind !== "openai") {
+      return provider;
+    }
+    const { options } = provider;
+    const apiKeyEnv =
+      options.apiKeyEnv ?? (options.baseUrl ? undefined : OPENAI_API_KEY_ENV);
+    return {
+      ...provider,
+      options: apiKeyEnv ? { ...options, apiKeyEnv } : options,
+      requiredSecrets: apiKeyEnv ? [apiKeyEnv] : [],
+      runtimeDeps: [OPENAI_SPEECH_DEP],
+    };
+  });
+
 /** A validated narration provider, defaults filled in. */
 export type NarrationProvider = z.output<typeof narrationProviderSchema>;
+
+/** A validated `gateway()` narration provider. */
+export type GatewayNarrationProvider = Extract<
+  NarrationProvider,
+  { kind: "gateway" }
+>;
+
+/** A validated `openai()` narration provider. */
+export type OpenAINarrationProvider = Extract<
+  NarrationProvider,
+  { kind: "openai" }
+>;

package/src/openapi/render-mdx.ts

@@ -1,4 +1,4 @@
-import type { Nodes, Root } from "mdast";
+import type { List, Nodes, Paragraph, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
@@ -10,7 +10,7 @@ import type { GraphqlMember } from "./graphql.ts";
 import { isGraphqlOperationKind } from "./graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
-import { asSentence } from "./sentence.ts";
+import { asSentence, closeSentence, endsInLeadIn } from "./sentence.ts";
 import { operationSignature } from "./signature.ts";
 
 /**
@@ -193,6 +193,51 @@ export interface RenderedPage {
 const META_DESCRIPTION_MAX = 160;
 const WHITESPACE = /\s+/gu;
 const TRAILING_WORD = /\s+\S*$/u;
+// A list item's own closing mark, dropped where the items join into one line.
+const ITEM_END = /[.;。；]$/u;
+
+/** Markdown as single-line plain text. */
+const flatten = (node: Nodes): string =>
+  mdastToString(node).replace(WHITESPACE, " ").trim();
+
+/** The innermost last node of `node`: the one its text ends in. */
+const lastLeaf = (node: Nodes): Nodes => {
+  const last = "children" in node ? node.children.at(-1) : undefined;
+  return last ? lastLeaf(last) : node;
+};
+
+/**
+ * Whether a paragraph ends in a lead-in colon. Only a colon in the prose
+ * counts: one closing inline code (`tenant:`) is part of the literal.
+ */
+const leadsIn = (paragraph: Paragraph): boolean => {
+  const leaf = lastLeaf(paragraph);
+  return leaf.type === "text" && endsInLeadIn(leaf.value);
+};
+
+/** A list as one line: each item's first paragraph, joined by semicolons. */
+const listProse = (list: List): string =>
+  list.children
+    .map((item) => {
+      const paragraph = item.children.find(
+        (child) => child.type === "paragraph"
+      );
+      if (!paragraph) {
+        return "";
+      }
+      const text = flatten(paragraph);
+      // A closing mark in inline code (`SELECT 1;`) is part of the literal.
+      if (lastLeaf(paragraph).type !== "text") {
+        return text;
+      }
+      // A nested list's lead-in ("Modes:") closes like any other.
+      return (leadsIn(paragraph) ? asSentence(text) : text).replace(
+        ITEM_END,
+        ""
+      );
+    })
+    .filter(Boolean)
+    .join("; ");
 
 /**
  * Flatten markdown prose to its first paragraph as single-line plain text,
@@ -200,12 +245,25 @@ const TRAILING_WORD = /\s+\S*$/u;
  * was lossy on literal prose — `snake_case` → `snakecase`, `C#` → `C` — and
  * these strings ship as `seo.description` meta tags. A description with no
  * paragraph (say, only a heading or list) falls back to its first block.
+ *
+ * A first paragraph that leads in to a list ("Supports two modes:") is cut
+ * from what it introduces, so the list's items follow it on the same line. A
+ * lead-in to anything else, such as a code block, is closed as a sentence.
  */
 const plainProse = (markdown: string): string => {
-  const tree = fromMarkdown(markdown);
-  const first =
-    tree.children.find((node) => node.type === "paragraph") ?? tree.children[0];
-  return first ? mdastToString(first).replace(WHITESPACE, " ").trim() : "";
+  const { children } = fromMarkdown(markdown);
+  const index = children.findIndex((node) => node.type === "paragraph");
+  const paragraph = children[index];
+  if (paragraph?.type !== "paragraph") {
+    return children[0] ? flatten(children[0]) : "";
+  }
+  const text = flatten(paragraph);
+  if (!leadsIn(paragraph)) {
+    return text;
+  }
+  const next = children[index + 1];
+  const items = next?.type === "list" ? listProse(next) : "";
+  return items ? `${text} ${items}` : asSentence(text);
 };
 
 /** Cap `text` at `max` display columns, cutting on a word boundary. */
@@ -274,14 +332,16 @@ const operationDescription = (
     subject = `${operation.method.toUpperCase()} ${operation.path} ${operation.webhook ? "webhook" : "endpoint"}`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
-  // Room for the joining space and the period `asSentence` may add, so a
+  // Room for the joining space and the period `closeSentence` may add, so a
   // title-like summary ("Get a flag") ends before the suffix begins.
   const prose = clip(
     plainProse(operation.description || operation.summary),
     META_DESCRIPTION_MAX - stringWidth(suffix) - 2
   );
+  // `plainProse` has already closed a lead-in colon, so one still at the end
+  // is a literal (`tenant:`) and keeps its period after it.
   return clip(
-    [asSentence(prose), suffix].filter(Boolean).join(" "),
+    [closeSentence(prose), suffix].filter(Boolean).join(" "),
     META_DESCRIPTION_MAX
   );
 };

package/src/openapi/sentence.ts

@@ -4,11 +4,38 @@
  */
 const TERMINAL_PUNCTUATION = /[.!?…。！？]["'”’)\]]*$/u;
 
+/**
+ * A colon closing the fragment introduces a list or block it was cut from
+ * ("Supports two modes:" before its bullets). The ASCII or full-width colon,
+ * with the space French typesetting puts before it ("Deux modes :").
+ */
+const LEAD_IN_COLON = /\s*[:：]\s*$/u;
+
+/**
+ * A trailing colon that belongs to a literal rather than the prose: an emoji
+ * shortcode (`:rocket:`) or a `Foo::` scope.
+ */
+const LITERAL_COLON = /(?:[:：]{2}|:[\w+-]+:)\s*$/u;
+
+/** Whether `text` ends in a colon that leads in to what follows it. */
+export const endsInLeadIn = (text: string): boolean =>
+  LEAD_IN_COLON.test(text) && !LITERAL_COLON.test(text);
+
+/**
+ * Close prose with a period unless it already ends a sentence. A colon at the
+ * end is kept and gains the period: use this when the caller has already told
+ * a lead-in apart from a literal (`tenant:` in inline code). Empty text stays
+ * empty.
+ */
+export const closeSentence = (text: string): string =>
+  text === "" || TERMINAL_PUNCTUATION.test(text) ? text : `${text}.`;
+
 /**
  * Close a fragment of spec prose as a sentence. OpenAPI `summary` values are
  * usually title-like ("Get a flag", no period), so prose that runs straight
  * into the next generated sentence ("Get a flag Reference for …") needs one.
- * Empty text stays empty.
+ * A lead-in colon becomes the period rather than gaining one after it, and
+ * prose that already ended before it ("e.g.:") keeps its own mark.
  */
 export const asSentence = (text: string): string =>
-  text === "" || TERMINAL_PUNCTUATION.test(text) ? text : `${text}.`;
+  closeSentence(endsInLeadIn(text) ? text.replace(LEAD_IN_COLON, "") : text);

package/src/registry/eject.ts

@@ -529,12 +529,15 @@ const examplesPreviewFiles = (
  * eject declares the ones its generated files import directly: the AI SDK the
  * assistant route streams through (unless `ai.assistant.endpoint` points
  * elsewhere, when no route is written) and the EPUB generator's browser bundle
- * `features.ts` loads (only named there when `export.epub` is on).
+ * `features.ts` loads (only named there when `export.epub` is on). The
+ * narration provider's SDK (`openai()`'s `@ai-sdk/openai`) is no runtime
+ * import, but the ejected app's `astro build` loads it to generate the clips.
  */
 const ejectDependencies = (
   options: Parameters<typeof runtimeDependencies>[0]
 ): string[] => {
   const { assistant } = options.config.ai;
+  const { narration } = options.config;
   return [
     ...new Set([
       "astro",
@@ -545,6 +548,7 @@ const ejectDependencies = (
       ...runtimeDependencies(options),
       ...(options.needsReact ? ["react", "react-dom"] : []),
       ...(assistant?.enabled && !assistant.endpoint ? ["ai"] : []),
+      ...(narration.enabled ? (narration.provider?.runtimeDeps ?? []) : []),
       ...(options.config.export.epub ? ["epub-gen-memory"] : []),
     ]),
   ];