blume 1.5.3 → 1.6.1

package/src/openapi/references.ts

@@ -14,7 +14,7 @@ export { normalizeRoute } from "../core/base-path.ts";
  * imports so `core` can depend on it without a cycle.
  */
 
-export type ReferenceKind = "openapi" | "asyncapi";
+export type ReferenceKind = "openapi" | "asyncapi" | "graphql";
 
 /** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
 export type ReferenceRenderer = "blume" | "scalar";
@@ -54,8 +54,18 @@ export interface ReferenceSource {
   includeInSearch: boolean;
   /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
   noindex: boolean;
+  /**
+   * Whether operation meta descriptions end with the generated English
+   * "Reference for …" sentence, or carry the spec's own prose alone.
+   */
+  seoDescriptionSuffix: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
+  /**
+   * URL of the live GraphQL endpoint the playground and code samples target
+   * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
+   */
+  endpoint?: string;
   /** Per-block Scalar theme name override, if any (Scalar renderer only). */
   theme?: string;
   /**
@@ -109,25 +119,40 @@ export const slugify = (text: string): string =>
 const routeSlug = (route: string): string =>
   slugify(trimChar(route, "/")) || "reference";
 
-type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
+/**
+ * The structural shape all three reference blocks (`openapi`, `asyncapi`,
+ * `graphql`) share. `endpoint` exists only on the GraphQL block and its
+ * sources; `scalar`/`theme` only on the Scalar-capable kinds — optional here
+ * so one resolver serves every block.
+ */
+interface Block {
+  enabled: boolean;
+  endpoint?: string;
+  route: string;
+  scalar?: ResolvedConfig["openapi"]["scalar"];
+  sources: {
+    endpoint?: string;
+    includeInLlms: boolean;
+    includeInSearch: boolean;
+    label?: string;
+    noindex: boolean;
+    route?: string;
+    seoDescriptionSuffix: boolean;
+    spec: string;
+  }[];
+  spec?: string;
+  theme?: string;
+}
 
 /** A spec is a single source (`spec` shorthand prepended to any `sources`). */
-const sourcesOf = (
-  block: Block
-): {
-  includeInLlms: boolean;
-  includeInSearch: boolean;
-  label?: string;
-  noindex: boolean;
-  route?: string;
-  spec: string;
-}[] => {
+const sourcesOf = (block: Block): Block["sources"] => {
   const sources = [...block.sources];
   if (block.spec) {
     sources.unshift({
       includeInLlms: true,
       includeInSearch: true,
       noindex: false,
+      seoDescriptionSuffix: true,
       spec: block.spec,
     });
   }
@@ -163,7 +188,7 @@ const referencesFor = (
       route = normalizeRoute(`${base}/${suffix || index + 1}`);
     }
 
-    return {
+    const reference: ReferenceSource = {
       basePath,
       display,
       includeInLlms: source.includeInLlms,
@@ -174,10 +199,18 @@ const referencesFor = (
       renderer,
       route,
       scalar: block.scalar,
+      seoDescriptionSuffix: source.seoDescriptionSuffix,
       slug: routeSlug(route),
       spec: source.spec,
       theme: block.theme,
     };
+    // Per-source endpoint wins; the block-level one is the shared default
+    // (the common single-schema case pairs it with the `spec` shorthand).
+    const endpoint = source.endpoint ?? block.endpoint;
+    if (endpoint !== undefined) {
+      reference.endpoint = endpoint;
+    }
+    return reference;
   });
 };
 
@@ -212,6 +245,21 @@ export const resolveReferences = (
     },
     config.basePath
   ),
+  // GraphQL is always Blume-rendered — Scalar's embedded SPA reads OpenAPI
+  // documents only, so the block declares no `renderer` opt-out (nor the
+  // schema-row `expandSchemas` toggle; GraphQL field tables have no nesting).
+  ...referencesFor(
+    "graphql",
+    config.graphql,
+    "GraphQL",
+    "blume",
+    {
+      codeSamples: config.graphql.codeSamples,
+      expandSchemas: false,
+      playground: config.graphql.playground,
+    },
+    config.basePath
+  ),
 ];
 
 /**
@@ -287,3 +335,39 @@ export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
 /** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
 export const hasScalarReferences = (config: ResolvedConfig): boolean =>
   resolveReferences(config).some((ref) => ref.renderer === "scalar");
+
+/**
+ * The reference kinds whose enabled, Blume-rendered playground opted into the
+ * built-in CORS proxy with `proxy: true`. A proxy URL string points at an
+ * external service, and `false` sends requests directly — neither routes
+ * through the endpoint. The generator's per-spec allowlist diagnostics key on
+ * this, so it shares one definition with {@link needsPlaygroundProxy}.
+ */
+export const builtinProxyKinds = (config: ResolvedConfig): ReferenceKind[] => {
+  const kinds: ReferenceKind[] = [];
+  if (
+    config.openapi.enabled &&
+    config.openapi.renderer === "blume" &&
+    config.openapi.playground.enabled &&
+    config.openapi.playground.proxy === true
+  ) {
+    kinds.push("openapi");
+  }
+  if (
+    config.graphql.enabled &&
+    config.graphql.playground.enabled &&
+    config.graphql.playground.proxy === true
+  ) {
+    kinds.push("graphql");
+  }
+  return kinds;
+};
+
+/**
+ * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
+ * generated: some enabled Blume-rendered block's playground opted into it with
+ * `proxy: true`. Shared by the server feature gate and the generator so the
+ * two can never disagree.
+ */
+export const needsPlaygroundProxy = (config: ResolvedConfig): boolean =>
+  builtinProxyKinds(config).length > 0;

package/src/openapi/render-mdx.ts

@@ -4,6 +4,8 @@ import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
 
 import { columnsPrefix } from "../core/text-width.ts";
+import type { GraphqlMember } from "./graphql.ts";
+import { isGraphqlOperationKind } from "./graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -156,20 +158,51 @@ const clip = (text: string, max: number): string => {
 
 const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
 
+/** Human phrase for each GraphQL page kind, for meta descriptions. */
+const GRAPHQL_MEMBER_PHRASES = {
+  enum: "enum type",
+  input: "input object type",
+  interface: "interface type",
+  mutation: "mutation",
+  object: "object type",
+  query: "query",
+  scalar: "scalar type",
+  subscription: "subscription",
+  union: "union type",
+} satisfies Record<GraphqlMember, string>;
+
 /**
  * The spec's own prose for the operation, followed by the endpoint it documents
  * — so every operation page carries a distinct, self-describing meta
- * description even when the spec's summaries are terse.
+ * description even when the spec's summaries are terse. With the suffix
+ * switched off (`seoDescriptionSuffix: false`, for sites whose prose isn't
+ * English) the description is the prose alone, or the page `title` — a
+ * language-neutral `GET /pets`, channel, or field name — when the operation
+ * has no prose at all, so no page ships an empty description.
  */
 const operationDescription = (
   spec: ApiSpecData,
-  operation: ApiOperationRef
+  operation: ApiOperationRef,
+  options: { suffix: boolean; title: string }
 ): string => {
-  // AsyncAPI operations act on a channel, not an HTTP endpoint.
-  const suffix =
-    spec.kind === "asyncapi"
-      ? `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`
-      : `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+  if (!options.suffix) {
+    return clip(
+      plainProse(operation.description || operation.summary) || options.title,
+      META_DESCRIPTION_MAX
+    );
+  }
+  // AsyncAPI operations act on a channel, not an HTTP endpoint; GraphQL pages
+  // document a root field or a named type.
+  let suffix: string;
+  if (spec.kind === "asyncapi") {
+    suffix = `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`;
+  } else if (spec.kind === "graphql") {
+    // SAFETY: the GraphQL extractor only ever assigns member kinds as the
+    // method (see `extractGraphqlOperations`).
+    suffix = `Reference for the ${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]} in the ${apiName(spec)} API.`;
+  } else {
+    suffix = `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+  }
   const prose = clip(
     plainProse(operation.description || operation.summary),
     META_DESCRIPTION_MAX - stringWidth(suffix) - 1
@@ -188,11 +221,17 @@ export const operationMdx = (
   operation: ApiOperationRef,
   reference?: Pick<
     ReferenceSource,
-    "includeInLlms" | "includeInSearch" | "noindex"
+    "includeInLlms" | "includeInSearch" | "noindex" | "seoDescriptionSuffix"
   >
 ): RenderedPage => {
   const method = operation.method.toUpperCase();
-  const title = operation.summary || `${method} ${operation.path}`;
+  const graphql = spec.kind === "graphql";
+  // A GraphQL page IS its field/type — `QUERY pets` would double the badge the
+  // page already renders; the other kinds title an endpoint or channel action.
+  const fallbackTitle = graphql
+    ? operation.path
+    : `${method} ${operation.path}`;
+  const title = operation.summary || fallbackTitle;
   // Skip the body description when it only repeats the summary (the `<h1>`) —
   // common in specs that set summary and description to the same string.
   const description =
@@ -214,11 +253,26 @@ export const operationMdx = (
     searchFlags.exclude = true;
   }
   const seo: RenderedPageData["seo"] = {
-    description: operationDescription(spec, operation),
+    description: operationDescription(spec, operation, {
+      suffix: reference?.seoDescriptionSuffix !== false,
+      title,
+    }),
   };
   if (reference?.noindex) {
     seo.noindex = true;
   }
+  const sidebar: RenderedPageData["sidebar"] = {
+    label: operation.summary || operation.path,
+  };
+  // GraphQL operation kinds badge like HTTP methods, but a type page's kind
+  // already heads its sidebar group ("Objects", "Enums", …) — an `OBJECT`
+  // badge on every row would only repeat it, so type pages get none. The
+  // uppercased method is likewise an internal token on GraphQL pages, so
+  // their search tags carry only the group name.
+  if (!graphql || isGraphqlOperationKind(operation.method)) {
+    sidebar.badge = method;
+  }
+  const tags = graphql ? [operation.tag] : [operation.tag, method];
   return {
     body: withDescription(
       description,
@@ -226,9 +280,9 @@ export const operationMdx = (
     ),
     data: {
       ...flags,
-      search: { ...searchFlags, tags: [operation.tag, method] },
+      search: { ...searchFlags, tags },
       seo,
-      sidebar: { badge: method, label: operation.summary || operation.path },
+      sidebar,
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
       type: "openapi-operation",

package/src/openapi/scalar.ts

@@ -32,22 +32,16 @@ const referencePagePath = (route: string): string => {
   return `${segments === "" ? "index" : segments}.astro`;
 };
 
-const darkModeConfig = (mode: ResolvedConfig["theme"]["mode"]) => {
-  if (mode === "dark") {
-    return { darkMode: true };
-  }
-  if (mode === "light") {
-    return { darkMode: false };
-  }
-  // "system": leave Scalar to follow the OS preference.
-  return {};
-};
-
 /**
  * Map Blume's theme onto Scalar's. An explicit `theme` name wins; otherwise we
  * keep Scalar's default theme and layer Blume's accent/radius on top via
  * `customCss`. Scalar re-injects `customCss` after its bundled theme, so these
  * variables reliably override the defaults. Best-effort, not pixel-exact.
+ *
+ * Light/dark is not decided here: the page's `data-theme` (stored preference,
+ * else the configured mode, else the OS) is only known in the browser, so
+ * `ReferenceLayout` pins Scalar's color mode to it at mount and keeps the two
+ * in step afterwards (`SCALAR_THEME_INIT_SCRIPT`).
  */
 const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   if (override) {
@@ -57,7 +51,6 @@ const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   const radius = resolveRadius(config.theme);
   return {
     customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent.light};--scalar-radius:${radius};}.dark-mode{--scalar-color-accent:${accent.dark};}`,
-    ...darkModeConfig(config.theme.mode),
   };
 };
 
@@ -151,9 +144,6 @@ export const buildReferenceFiles = async (options: {
       warnings.push(spec.warning);
     }
     const pagePath = referencePagePath(ref.route);
-    // Relative path from the page back to src/generated/data.json: a page one
-    // directory deep (api/events.astro) needs an extra "../".
-    const depth = pagePath.split("/").length - 1;
     files.push({
       content: scalarReferenceTemplate({
         configuration: {
@@ -164,7 +154,6 @@ export const buildReferenceFiles = async (options: {
           // hideTestRequestButton, orderSchemaPropertiesBy, and the rest).
           ...ref.scalar,
         },
-        dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
         noindex: ref.noindex,
         route: ref.route,
         title: ref.label,

package/src/openapi/source.ts

@@ -11,6 +11,8 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractAsyncApiOperations } from "./asyncapi.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
+import { extractGraphqlOperations } from "./graphql.ts";
+import type { GraphqlDocument } from "./graphql.ts";
 import { extractOperations } from "./model.ts";
 import type {
   ApiDocument,
@@ -19,7 +21,12 @@ import type {
   ApiTagRef,
   OpenApiData,
 } from "./model.ts";
-import { InvalidSpecError, parseAsyncApiSpec, parseSpec } from "./parse.ts";
+import {
+  InvalidSpecError,
+  parseAsyncApiSpec,
+  parseGraphqlSpec,
+  parseSpec,
+} from "./parse.ts";
 import type { ReferenceSource } from "./references.ts";
 import { operationMdx, overviewMdx } from "./render-mdx.ts";
 import type { RenderedPage } from "./render-mdx.ts";
@@ -51,6 +58,62 @@ export const isOpenApiSource = (
 /** Route (`/reference/pet/add-pet`) to a staged content ref, without extension. */
 const routeToRef = (route: string): string => route.replace(/^\/+/u, "");
 
+/** Human label per spec kind, so one kind's failure never reads as another's. */
+const KIND_LABELS = {
+  asyncapi: "AsyncAPI",
+  graphql: "GraphQL",
+  openapi: "OpenAPI",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** Diagnostic-code prefix per spec kind. */
+const CODE_PREFIXES = {
+  asyncapi: "BLUME_ASYNCAPI",
+  graphql: "BLUME_GRAPHQL",
+  openapi: "BLUME_OPENAPI",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/**
+ * Parse-level warning code per kind: an offline cache fallback for any kind,
+ * plus lossy 2.x→3.0 conversion notes for AsyncAPI — hence the broader codes
+ * there and for GraphQL (OpenAPI keeps its historical one).
+ */
+const SPEC_WARNING_CODES = {
+  asyncapi: "BLUME_ASYNCAPI_SPEC_WARNING",
+  graphql: "BLUME_GRAPHQL_SPEC_WARNING",
+  openapi: "BLUME_OPENAPI_STALE",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/**
+ * Extract-level skip code per kind. OpenAPI keeps its historical code (the
+ * only extract warning it emits is the unresolved $ref path item); the
+ * GraphQL extractor currently skips nothing, so its code is reserved.
+ */
+const SKIPPED_CODES = {
+  asyncapi: "BLUME_ASYNCAPI_SKIPPED_OPERATION",
+  graphql: "BLUME_GRAPHQL_SKIPPED",
+  openapi: "BLUME_OPENAPI_REF_PATH_ITEM",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** `_EMPTY` diagnostic suggestion per kind. */
+const EMPTY_SUGGESTIONS = {
+  asyncapi:
+    "Check the spec points at an AsyncAPI document with `channels` and `operations`.",
+  graphql:
+    "Check the spec points at a GraphQL schema (SDL or introspection JSON) whose root types declare fields.",
+  openapi:
+    "Check the spec points at an OpenAPI document with operations under `paths`.",
+} satisfies Record<ReferenceSource["kind"], string>;
+
+/** `_UNAVAILABLE` suggestion for a readable-but-invalid spec, per kind. */
+const INVALID_SUGGESTIONS = {
+  asyncapi:
+    "Point the spec at an AsyncAPI document (a YAML or JSON file with an object at the top level).",
+  graphql:
+    "Point the spec at a GraphQL schema — SDL text or an introspection JSON result.",
+  openapi:
+    "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level).",
+} satisfies Record<ReferenceSource["kind"], string>;
+
 const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
   const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
   return {
@@ -122,7 +185,7 @@ interface LoadedSpec {
 
 /** One parsed spec, whichever front-end read it — the kind dispatch seam. */
 interface ParsedReference {
-  document: ApiDocument | AsyncApiDocument;
+  document: ApiDocument | AsyncApiDocument | GraphqlDocument;
   warnings: string[];
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
@@ -149,6 +212,21 @@ const parseReference = async (
       warnings,
     };
   }
+  if (reference.kind === "graphql") {
+    const { document, warnings } = await parseGraphqlSpec(
+      reference.spec,
+      ctx.projectRoot,
+      options
+    );
+    const extracted = extractGraphqlOperations(document, reference.route);
+    return {
+      document,
+      extractWarnings: extracted.warnings,
+      operations: extracted.operations,
+      tags: extracted.tags,
+      warnings,
+    };
+  }
   const { document, warnings } = await parseSpec(
     reference.spec,
     ctx.projectRoot,
@@ -175,9 +253,8 @@ export const openApiSource = (
   ): Promise<LoadedSpec | Diagnostic> => {
     // Human label and diagnostic-code prefix for the spec's kind, so an
     // AsyncAPI failure never reads as an OpenAPI one.
-    const kindLabel = reference.kind === "asyncapi" ? "AsyncAPI" : "OpenAPI";
-    const codePrefix =
-      reference.kind === "asyncapi" ? "BLUME_ASYNCAPI" : "BLUME_OPENAPI";
+    const kindLabel = KIND_LABELS[reference.kind];
+    const codePrefix = CODE_PREFIXES[reference.kind];
     try {
       const { document, warnings, operations, tags, extractWarnings } =
         await parseReference(reference, ctx);
@@ -221,26 +298,20 @@ export const openApiSource = (
         title: info.title ?? reference.label,
         version: info.version ?? "",
       };
+      // Only GraphQL references carry a live endpoint (a schema names no
+      // server); assigned separately so the key stays absent otherwise.
+      if (reference.endpoint !== undefined) {
+        spec.endpoint = reference.endpoint;
+      }
       return {
         diagnostics: [
           ...warnings.map((message) => ({
-            // Parse-level notes: an offline cache fallback for either kind,
-            // plus lossy 2.x→3.0 conversion notes for AsyncAPI — hence the
-            // broader code on that side (OpenAPI keeps its historical one).
-            code:
-              reference.kind === "asyncapi"
-                ? "BLUME_ASYNCAPI_SPEC_WARNING"
-                : "BLUME_OPENAPI_STALE",
+            code: SPEC_WARNING_CODES[reference.kind],
             message,
             severity: "warning" as const,
           })),
           ...extractWarnings.map((message) => ({
-            // OpenAPI keeps its historical code (the only extract warning it
-            // emits is the unresolved $ref path item).
-            code:
-              reference.kind === "asyncapi"
-                ? "BLUME_ASYNCAPI_SKIPPED_OPERATION"
-                : "BLUME_OPENAPI_REF_PATH_ITEM",
+            code: SKIPPED_CODES[reference.kind],
             message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning" as const,
           })),
@@ -253,10 +324,7 @@ export const openApiSource = (
                   code: `${codePrefix}_EMPTY`,
                   message: `${kindLabel} spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
                   severity: "warning" as const,
-                  suggestion:
-                    reference.kind === "asyncapi"
-                      ? "Check the spec points at an AsyncAPI document with `channels` and `operations`."
-                      : "Check the spec points at an OpenAPI document with operations under `paths`.",
+                  suggestion: EMPTY_SUGGESTIONS[reference.kind],
                 },
               ]
             : []),
@@ -280,7 +348,7 @@ export const openApiSource = (
         // only point at reachability for actual fetch/read failures.
         suggestion:
           error instanceof InvalidSpecError
-            ? `Point the spec at ${reference.kind === "asyncapi" ? "an AsyncAPI" : "an OpenAPI"} document (a YAML or JSON file with an object at the top level).`
+            ? INVALID_SUGGESTIONS[reference.kind]
             : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
       };
     }

package/src/registry/eject.ts

@@ -9,7 +9,12 @@ import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
-import { discoverExamples, exampleMarkdownLookup } from "../astro/examples.ts";
+import {
+  EXAMPLE_SCAN_GLOB,
+  discoverExamples,
+  exampleMarkdownLookup,
+  exampleScanRoots,
+} from "../astro/examples.ts";
 import {
   buildRuntimeData,
   collectStaged,
@@ -44,6 +49,7 @@ import {
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { buildIncludeGraph } from "../core/includes.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -60,6 +66,7 @@ import {
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
 import { buildThemeCss } from "../theme/palette.ts";
+import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 
 const toPosix = (path: string): string => path.split("\\").join("/");
@@ -202,7 +209,7 @@ const mcpFiles = async (
       path: join(genDir, "mcp-data.json"),
     },
     {
-      content: mcpEndpointTemplate(route),
+      content: mcpEndpointTemplate(),
       path: join(srcDir, "pages", mcpPageFile(route)),
     },
     {
@@ -250,13 +257,21 @@ const changelogFiles = (
 };
 
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
-const readExamplesCss = (
-  root: string,
-  css: string | undefined
-): Promise<string> =>
-  css && existsSync(join(root, css))
-    ? readFile(join(root, css), "utf-8")
-    : Promise.resolve("");
+/**
+ * Read a user stylesheet that eject inlines into a generated entry under
+ * `genDir`, re-rooting its relative `@source` paths from the user's file.
+ * Resolves to an empty string when the file is unset or absent.
+ */
+const readUserCss = async (
+  file: string | null,
+  genDir: string
+): Promise<string> => {
+  if (!(file && existsSync(file))) {
+    return "";
+  }
+  const css = await readFile(file, "utf-8");
+  return rebaseSourceDirectives(css, { from: file, to: genDir });
+};
 
 /**
  * The per-example preview route `<Component />` iframes embed, nested under
@@ -330,10 +345,11 @@ export const eject = async (
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
     detectUsesMath(root),
-    context.themeFile
-      ? readFile(context.themeFile, "utf-8")
-      : Promise.resolve(""),
-    readExamplesCss(root, config.examples.css),
+    readUserCss(context.themeFile, genDir),
+    readUserCss(
+      config.examples.css ? join(root, config.examples.css) : null,
+      genDir
+    ),
     buildRawMarkdown(project),
     discoverIslands(root),
   ]);
@@ -383,11 +399,14 @@ export const eject = async (
       content: astroConfigTemplate({
         askPath: "./src/generated/Ask.astro",
         config,
+        contentRoot: relContext.contentRoot,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
-        dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        // No CLI publishes the runtime data modules in memory after eject, so
+        // the config aliases each to the JSON snapshot written below.
+        generatedModulesDir: "./src/generated",
         integrationBridge: ejectIntegrationBridge(
           config,
           root,
@@ -396,7 +415,6 @@ export const eject = async (
         needsReact,
         needsSvelte,
         needsVue,
-        openapiPath: "./src/generated/openapi.json",
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css",
@@ -450,7 +468,9 @@ export const eject = async (
       // Relative sources keep the ejected app portable.
       content: examplesEntryTemplate({
         configTokens: buildThemeCss(config.theme),
-        sources: ["../../**/*.{astro,jsx,svelte,ts,tsx,vue}"],
+        sources: exampleScanRoots(root, examples.dir).map(
+          (dir) => `${relative(genDir, dir)}/${EXAMPLE_SCAN_GLOB}`
+        ),
         userCss: userExamplesCss,
       }),
       path: join(genDir, "examples.css"),
@@ -485,6 +505,15 @@ export const eject = async (
       content: `${JSON.stringify(rawMarkdown)}\n`,
       path: join(genDir, "raw-markdown.json"),
     },
+    {
+      // The partial → including-pages map behind `includeHmrPlugin`, which the
+      // ejected astro.config wires at this exact path — without the file every
+      // hot update's read would silently no-op and partial edits would serve
+      // stale pages. A snapshot like the rest of `src/generated`: the ejected
+      // app owns (and may regenerate or prune) it.
+      content: `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`,
+      path: join(genDir, "includes.json"),
+    },
     {
       content: rawMarkdownEndpointTemplate("md"),
       path: join(srcDir, "pages", "[...slug].md.ts"),
@@ -502,7 +531,8 @@ export const eject = async (
   if (config.seo.og.enabled) {
     files.push({
       content: ogEndpointTemplate(
-        customOgRoutes(pages, config.title, config.seo.og.titles)
+        customOgRoutes(pages, config.title, config.seo.og.titles),
+        { pageDescriptions: config.seo.og.description !== false }
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });