blume 2.1.0 → 2.1.1

package/src/components/openapi/helpers.ts

@@ -135,7 +135,23 @@ export const mergeParameters = (
 export const refName = (ref: string): string =>
   REF_PATTERN.exec(ref)?.groups?.name ?? ref.split("/").at(-1) ?? ref;
 
-/** Resolve one level of `$ref` against the document's component schemas. */
+/**
+ * The one member of an `allOf` that only wraps it: `allOf: [{ $ref }]` beside
+ * a `description`, `readOnly`, or `default`, which is how drf-spectacular and
+ * other generators attach keywords a 3.0 `$ref` can't carry. `undefined` for
+ * a real composition: several members, or properties or branches of its own.
+ */
+export const soleAllOfMember = (schema: SchemaLike): SchemaLike | undefined =>
+  schema.allOf?.length === 1 &&
+  !(schema.properties || schema.oneOf || schema.anyOf)
+    ? schema.allOf[0]
+    : undefined;
+
+/**
+ * Resolve one level of `$ref` against the document's component schemas. A
+ * single-member `allOf` wrapper resolves like its member, with the wrapper's
+ * own keywords on top: its `description` is about this field.
+ */
 export const resolveSchema = (
   schemas: Record<string, SchemaLike>,
   schema?: SchemaLike
@@ -143,6 +159,11 @@ export const resolveSchema = (
   if (!schema) {
     return {};
   }
+  const member = soleAllOfMember(schema);
+  if (member) {
+    const { allOf: _wrapped, ...own } = schema;
+    return { ...resolveSchema(schemas, member), ...own };
+  }
   if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
     if (name && schemas[name]) {
@@ -152,6 +173,16 @@ export const resolveSchema = (
   return schema;
 };
 
+/**
+ * A parameter's description: its own, else its schema's (resolved one `$ref`
+ * level), which is where generators like Elysia and oRPC write it.
+ */
+export const parameterDescription = (
+  param: { description?: string; schema?: SchemaLike },
+  schemas: Record<string, SchemaLike>
+): string | undefined =>
+  param.description ?? resolveSchema(schemas, param.schema).description;
+
 const declaredTypeList = (type: string | string[] | undefined): string[] => {
   if (!type) {
     return [];
@@ -177,6 +208,8 @@ const isNullType = (schema: SchemaLike): boolean => {
  * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
  * array items can't recurse forever. A `null` member stays out of a union's
  * label: rows mark it with {@link isNullable}, as they do `type: [T, "null"]`.
+ * A single-member `allOf` wrapper labels as its member; a real composition is
+ * an `object`.
  */
 export const typeLabel = (schema: SchemaLike): string => {
   if (isString(schema.$ref)) {
@@ -192,7 +225,8 @@ export const typeLabel = (schema: SchemaLike): string => {
     return [...new Set(labels)].join(" | ") || "any";
   }
   if (schema.allOf) {
-    return "object";
+    const member = soleAllOfMember(schema);
+    return member ? typeLabel(member) : "object";
   }
   const types = nonNullTypes(schema.type);
   const arrayLabel = (): string => `${typeLabel(schema.items ?? {})}[]`;

package/src/components/openapi/message-model.ts

@@ -1,10 +1,15 @@
 import type {
   AsyncApiAction,
+  AsyncApiDocument,
   AsyncApiServerObject,
 } from "../../openapi/asyncapi.ts";
 import { withServerDefaults } from "../../openapi/model.ts";
 import type { AsyncApiMessageLike, NamedMessage } from "./async.ts";
-import { payloadSchema } from "./async.ts";
+import {
+  kafkaKeySchema,
+  payloadSchema,
+  resolvedServerSecurity,
+} from "./async.ts";
 import { exampleValue, toJson } from "./helpers.ts";
 import type { ParameterLike, SchemaLike } from "./helpers.ts";
 import type {
@@ -76,14 +81,34 @@ const messagePayload = (
   };
 };
 
+/**
+ * The first message's Kafka key as the kcat sample writes it: sampled from
+ * its binding's `key` schema the way a payload is (a declared example wins),
+ * a non-string value as JSON. None when the message declares no key.
+ */
+const messageKey = (
+  message: AsyncApiMessageLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  components: AsyncApiDocument["components"]
+): string | undefined => {
+  const schema = kafkaKeySchema(message, components);
+  const key = inputValue(schema ? exampleValue(schema, schemas) : null);
+  return key === "" ? undefined : key;
+};
+
 /**
  * A server's base URL for the picker. Falls back to the bare host when the
  * spec omits `protocol` — a label is a label, and the snippet builders read
  * the server object itself rather than this string. Server variables in the
  * host and pathname (`{env}.events.example.com`) resolve to their declared
  * defaults, in the label and in the object the samples and connect URL read.
+ * Security refs resolve here too, so the kcat sample can name the server's
+ * SASL mechanism.
  */
-const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
+const serverOption = (
+  spec: AsyncApiServerObject,
+  components: AsyncApiDocument["components"]
+): MessageServerOption => {
   const server = { ...spec };
   if (spec.host !== undefined) {
     server.host = withServerDefaults(spec.host, spec.variables);
@@ -91,6 +116,9 @@ const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
   if (spec.pathname !== undefined) {
     server.pathname = withServerDefaults(spec.pathname, spec.variables);
   }
+  if (spec.security !== undefined) {
+    server.security = resolvedServerSecurity(spec, components);
+  }
   const host = `${server.host ?? ""}${server.pathname ?? ""}`;
   return {
     label: server.protocol ? `${server.protocol}://${host}` : host,
@@ -102,17 +130,32 @@ const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
 export const messageModel = (args: {
   action: AsyncApiAction;
   address: string;
+  /** The document's `components`, which bindings and security refs resolve against. */
+  components?: AsyncApiDocument["components"];
   messages: NamedMessage[];
   parameters: ParameterLike[];
   protocol?: string;
   schemas: Record<string, SchemaLike>;
   servers: AsyncApiServerObject[];
-}): MessageModel => ({
-  action: args.action,
-  address: args.address,
-  connectable: Object.hasOwn(LIVE_PROTOCOLS, args.protocol ?? ""),
-  params: messageParams(args.parameters),
-  payload: messagePayload(args.messages[0]?.message, args.schemas),
-  protocol: args.protocol,
-  servers: args.servers.map(serverOption),
-});
+}): MessageModel => {
+  const model: MessageModel = {
+    action: args.action,
+    address: args.address,
+    connectable: Object.hasOwn(LIVE_PROTOCOLS, args.protocol ?? ""),
+    params: messageParams(args.parameters),
+    payload: messagePayload(args.messages[0]?.message, args.schemas),
+    protocol: args.protocol,
+    servers: args.servers.map((server) =>
+      serverOption(server, args.components)
+    ),
+  };
+  const key = messageKey(
+    args.messages[0]?.message,
+    args.schemas,
+    args.components
+  );
+  if (key !== undefined) {
+    model.key = key;
+  }
+  return model;
+};

package/src/components/openapi/message.ts

@@ -41,15 +41,19 @@ export interface MessageServerOption {
   /** `protocol://host+pathname` — what the reader picks between. */
   label: string;
   /**
-   * The spec server with its host/pathname variables at their defaults; the
-   * snippet builders read host/pathname/protocol.
+   * The spec server with its host/pathname variables at their defaults and
+   * its `security` refs resolved; the snippet builders read
+   * host/pathname/protocol/security.
    */
   server: AsyncApiServerObject;
 }
 
 export interface MessageModel {
   action: AsyncApiAction;
-  /** Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`. */
+  /**
+   * Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`
+   * — or the Kafka binding's `topic` when the channel names one.
+   */
   address: string;
   /**
    * Whether the panel offers a live connection. Only WebSocket bindings can be
@@ -57,6 +61,8 @@ export interface MessageModel {
    * CLI samples rather than faked connectivity.
    */
   connectable: boolean;
+  /** Example Kafka message key, sampled from the first message's binding. */
+  key?: string;
   params: MessageParam[];
   payload: MessagePayload;
   /** Normalized binding key (`ws`, `kafka`, `mqtt`, …) when the spec implies one. */
@@ -149,7 +155,7 @@ export const buildMessage = (
   } catch {
     payload = undefined;
   }
-  return {
+  const sample: MessageSample = {
     action: model.action,
     address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
       const value = values.params[String(name)] ?? "";
@@ -158,6 +164,10 @@ export const buildMessage = (
     payload,
     server: custom === "" ? picked?.server : customServer(custom),
   };
+  if (model.key !== undefined) {
+    sample.key = model.key;
+  }
+  return sample;
 };
 
 /**

package/src/components/openapi/operation-model.ts

@@ -3,6 +3,7 @@ import {
   declaredExample,
   exampleValue,
   objectProperties,
+  parameterDescription,
   resolveSchema,
   toJson,
 } from "./helpers.ts";
@@ -142,7 +143,7 @@ const modelParams = (
     const required = where === "path" ? true : param.required === true;
     const schema = resolveSchema(schemas, param.schema);
     params.push({
-      description: param.description,
+      description: parameterDescription(param, schemas),
       enum: schema.enum?.map(String),
       in: where,
       name: param.name,
@@ -330,6 +331,19 @@ const authInput = (
   }
 };
 
+/**
+ * The playground's credential inputs for an operation's security: the first
+ * alternative only — the spec's preferred way to authorize, matching what the
+ * static samples always showed.
+ */
+export const playgroundAuth = (
+  security: OperationSecurity
+): PlaygroundAuthInput[] =>
+  (security.alternatives[0] ?? []).flatMap((resolved) => {
+    const input = authInput(resolved);
+    return input ? [input] : [];
+  });
+
 /** Derive the playground request model for one operation, at build time. */
 export const operationModel = (args: {
   method: string;
@@ -344,12 +358,7 @@ export const operationModel = (args: {
   components?: ComponentsLike;
   security: OperationSecurity;
 }): PlaygroundModel => ({
-  // First alternative only — the spec's preferred way to authorize, matching
-  // what the static samples always showed.
-  auth: (args.security.alternatives[0] ?? []).flatMap((resolved) => {
-    const input = authInput(resolved);
-    return input ? [input] : [];
-  }),
+  auth: playgroundAuth(args.security),
   authOptional: args.security.optional,
   body: modelBody(args.requestBody, args.schemas, args.components),
   method: args.method.toUpperCase(),

package/src/components/openapi/playground-client.ts

@@ -26,16 +26,34 @@ import { fetchRefusesMethod, sampleLanguages } from "./snippets.ts";
 import type { RequestSample } from "./snippets.ts";
 import { validateJson } from "./validate-json.ts";
 
+const OPENAPI_PROXY_SETTING =
+  "`playground: { proxy: true }` on the `openapi()` reference";
+
+/**
+ * The Blume config setting that turns on the proxy for a panel, keyed by the
+ * `data-proxy-config` the rendering surface stamps on it: an `openapi()` or
+ * `graphql()` reference's `playground` option, or `api.playground` for
+ * hand-written API pages.
+ */
+const PROXY_SETTINGS = new Map([
+  ["api", "`api: { playground: { proxy: true } }`"],
+  ["graphql", "`playground: { proxy: true }` on the `graphql()` reference"],
+  ["openapi", OPENAPI_PROXY_SETTING],
+]);
+
 /**
  * A failed fetch surfaces as a TypeError with no status — almost always the
  * browser's CORS wall, not the API being down — so the message explains the
- * one fix docs authors control instead of parroting "failed to fetch".
+ * one fix docs authors control instead of parroting "failed to fetch", naming
+ * the setting for the surface this panel is on and the server output the
+ * built-in proxy needs.
  */
-const CORS_MESSAGE =
+const corsMessage = (config: string): string =>
   "The browser blocked this request before it reached the API — the API " +
   "likely does not allow cross-origin requests from this docs site. Set " +
-  "`playground: { proxy: true }` on the `openapi()` reference in the Blume " +
-  "config to route playground requests through the docs server instead.";
+  `${PROXY_SETTINGS.get(config) ?? OPENAPI_PROXY_SETTING} in the Blume ` +
+  "config to route playground requests through the docs server instead. " +
+  "The proxy needs server output: a host adapter in `deployment`.";
 
 /**
  * `Cookie` is a forbidden header name: a page cannot set it, so a credential
@@ -294,6 +312,7 @@ export const initPlayground = (root: HTMLElement): void => {
   const response = root.querySelector<HTMLElement>("[data-response]");
   const storageKey = root.dataset.storageKey ?? "";
   const proxy = root.dataset.proxy ?? "";
+  const proxyConfig = root.dataset.proxyConfig ?? "";
 
   /** True while a send is outstanding, so a second click can't race it. */
   let sending = false;
@@ -607,7 +626,7 @@ export const initPlayground = (root: HTMLElement): void => {
         const crossOrigin = !proxy && !sample.url.startsWith("/");
         message =
           crossOrigin && (await reachable(sample.url))
-            ? CORS_MESSAGE
+            ? corsMessage(proxyConfig)
             : UNREACHABLE_MESSAGE;
       }
       response.textContent = "";

package/src/components/openapi/playground-schema.ts

@@ -62,7 +62,7 @@ const isReadOnly = (
  * Prune a spec schema into the tiny subset `validate-json.ts` understands:
  * `$ref`s resolved inline, cycles cut (the visited set is copied per branch so
  * a ref reused by siblings still prunes fully), depth capped. Structure beyond
- * the cut simply goes unvalidated — advisory checks, not a gate.
+ * the cut simply goes unvalidated, so it can never block a send.
  */
 const pruneSchema = (
   schema: SchemaLike | undefined,

package/src/components/openapi/schema-tree.ts

@@ -2,6 +2,7 @@ import {
   objectProperties,
   refName,
   resolveSchema,
+  soleAllOfMember,
   typeLabel,
 } from "./helpers.ts";
 import type { SchemaLike, SpecValue } from "./helpers.ts";
@@ -67,6 +68,15 @@ export type SchemaNode =
 const isString = (value: SpecValue): value is string =>
   typeof value === "string";
 
+/**
+ * The `$ref` a schema stands for: its own, or its member's when it is a
+ * single-member `allOf` wrapper, which plans (and stops at a circle) the same.
+ */
+const refOf = (schema: SchemaLike): string | undefined => {
+  const ref = schema.$ref ?? soleAllOfMember(schema)?.$ref;
+  return isString(ref) ? ref : undefined;
+};
+
 const typesOf = (schema: SchemaLike): (string | undefined)[] =>
   Array.isArray(schema.type) ? schema.type : [schema.type];
 
@@ -88,13 +98,32 @@ interface PendingRef {
   slot: SchemaSlot;
 }
 
-/** Plan the table tree for one schema (a request body, a response, a payload). */
+/**
+ * Which way a schema's data travels, when its table has one: a request body
+ * leaves out the `readOnly` fields the server generates, and a response the
+ * `writeOnly` ones it never returns, as the examples beside them do.
+ */
+export type SchemaDirection = "request" | "response";
+
+/**
+ * Plan the table tree for one schema (a request body, a response, a payload).
+ * With a `direction`, every table in the tree leaves out the fields that
+ * don't travel that way.
+ */
 export const schemaTree = (
   root: SchemaLike,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  direction?: SchemaDirection
 ): SchemaNode => {
   const queue: PendingRef[] = [];
   const expanded = new Set<string>();
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+
+  /** Whether a property stays out of this tree's tables. */
+  const hidden = (property: SchemaLike): boolean =>
+    direction !== undefined &&
+    (property[omitted] === true ||
+      resolveSchema(schemas, property)[omitted] === true);
 
   /**
    * A table for `schema`, where `ancestors` are the named schemas already
@@ -107,8 +136,9 @@ export const schemaTree = (
     ancestors: string[],
     resolved = false
   ): SchemaSlot => {
-    if (!resolved && isString(schema.$ref)) {
-      const name = refName(schema.$ref);
+    const ref = resolved ? undefined : refOf(schema);
+    if (ref) {
+      const name = refName(ref);
       if (ancestors.includes(name)) {
         return { node: { kind: "circular", name } };
       }
@@ -132,10 +162,8 @@ export const schemaTree = (
     }
     // A row discloses nested structure — never a model inside itself.
     const rowChildren = (property: SchemaLike): SchemaSlot | undefined => {
-      if (
-        isString(property.$ref) &&
-        ancestors.includes(refName(property.$ref))
-      ) {
+      const propertyRef = refOf(property);
+      if (propertyRef && ancestors.includes(refName(propertyRef))) {
         return undefined;
       }
       const target = resolveSchema(schemas, property);
@@ -147,12 +175,14 @@ export const schemaTree = (
         : undefined;
     };
     const { properties, required } = objectProperties(schema, schemas);
-    const rows: SchemaRow[] = properties.map(([name, property]) => ({
-      children: rowChildren(property),
-      name,
-      required: required.has(name),
-      schema: property,
-    }));
+    const rows: SchemaRow[] = properties
+      .filter(([, property]) => !hidden(property))
+      .map(([name, property]) => ({
+        children: rowChildren(property),
+        name,
+        required: required.has(name),
+        schema: property,
+      }));
     // Shared properties beside a `oneOf`/`anyOf` (`amount` and `currency`
     // next to `Card | BankAccount`) render above the variants, planned first
     // as they read first.

package/src/components/openapi/security.ts

@@ -32,6 +32,11 @@ export interface ResolvedScheme {
   /** The scheme object; undefined when the requirement names an unknown one. */
   scheme?: SecuritySchemeLike;
   scopes: string[];
+  /**
+   * AsyncAPI: the servers that declare this scheme, set only when the
+   * channel's servers don't all declare the same ones.
+   */
+  servers?: string[];
 }
 
 /** The security state one operation renders. */
@@ -40,6 +45,11 @@ export interface OperationSecurity {
   alternatives: ResolvedScheme[][];
   /** True when an empty requirement also allows unauthenticated calls. */
   optional: boolean;
+  /**
+   * AsyncAPI: the servers that declare no security while others do, so the
+   * schemes apply on the other servers only.
+   */
+  unauthenticatedServers?: string[];
 }
 
 /**

package/src/components/openapi/snippets.ts

@@ -1053,19 +1053,21 @@ export const sampleLanguageInfo = (raw: string): SampleLanguageInfo | null => {
   return language ? { label: language.label, lang: language.lang } : null;
 };
 
+/** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
+export const DEFAULT_SAMPLE_LANGUAGES = ["curl", "js", "python"];
+
 /**
  * The sample languages to render, resolved from config ids (unknown ids
- * dropped). `false` renders none; an empty list, the defaults.
+ * dropped), in order. `false` and an empty list both render none.
  */
 export const sampleLanguages = (ids: string[] | false): SampleLanguage[] => {
   if (ids === false) {
     return [];
   }
-  const wanted = ids.length > 0 ? ids : ["curl", "js", "python"];
   const byId = new Map(LANGUAGES.map((entry) => [entry.id, entry]));
   const out: SampleLanguage[] = [];
   const seen = new Set<string>();
-  for (const raw of wanted) {
+  for (const raw of ids) {
     const id = sampleLanguageId(raw);
     const language = byId.get(id);
     if (language && !seen.has(id)) {

package/src/components/openapi/validate-json.ts

@@ -4,9 +4,10 @@ import type { ValidationSchema } from "./request.ts";
  * Minimal JSON-schema validation for the playground body editor. Client-safe
  * and dependency-free by design: the server prunes the operation's schema into
  * the tiny `ValidationSchema` subset (`operation-model.ts`), so a full
- * draft-2020 validator would be dead weight in the browser bundle. Checks are
- * advisory — they catch the common "typo'd a required field" mistakes, they do
- * not gate the Send button.
+ * draft-2020 validator would be dead weight in the browser bundle. The checks
+ * catch the common "typo'd a required field" mistakes, and any error they
+ * report blocks the Try it send (`playground-client.ts`) and the event
+ * composer's connect and send (`message-composer.ts`).
  */
 
 /** An already-parsed JSON object — string keys, parsed-JSON values. */

package/src/core/changelog-index.ts

@@ -1,4 +1,6 @@
-import type { ResolvedConfig } from "./schema.ts";
+import type { UIStrings } from "./i18n-ui.ts";
+import { resolveLocalizable } from "./localizable.ts";
+import type { LocalizableLabel, ResolvedConfig } from "./schema.ts";
 import { sourcesOfKind } from "./sources/collection.ts";
 import type { PageRecord } from "./types.ts";
 
@@ -22,3 +24,31 @@ export const hasChangelogIndex = (
       page.contentType === "changelog" &&
       !(page.meta.draft || page.meta.sidebar.hidden)
   ) || sourcesOfKind(config, "github-releases").length > 0;
+
+/**
+ * A locale's UI strings with the index's title and description taken from
+ * the `changelog` config where it sets them (a string, or a per-locale map
+ * resolved like a header label), so every surface that reads the
+ * `changelog` strings (the page, its OG card, its Markdown mirror) agrees.
+ */
+export const withChangelogIndexText = (
+  config: ResolvedConfig,
+  ui: UIStrings,
+  locale?: string
+): UIStrings => {
+  const text = (label: LocalizableLabel | undefined, fallback: string) =>
+    label === undefined
+      ? fallback
+      : resolveLocalizable(label, locale, config.i18n?.defaultLocale);
+  return {
+    ...ui,
+    changelog: {
+      ...ui.changelog,
+      description: text(
+        config.changelog?.description,
+        ui.changelog.description
+      ),
+      title: text(config.changelog?.title, ui.changelog.title),
+    },
+  };
+};

package/src/core/component-diagnostics.ts

@@ -1,3 +1,5 @@
+import { relative } from "pathe";
+
 import { BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
 import type { Diagnostic, PageRecord } from "./types.ts";
 
@@ -42,3 +44,54 @@ export const validateUsedComponents = (
   }
   return diagnostics;
 };
+
+/** What example discovery found: where it looked, and each example's key. */
+export interface ExampleKeys {
+  /** Absolute directory the examples were discovered under. */
+  dir: string;
+  examples: readonly { path: string }[];
+}
+
+/**
+ * Warn about each `<Component path>` in an `.mdx` page that names no
+ * discovered example. The page still renders, with a "No example found" box
+ * where the preview should be, so without this a typo or a moved example
+ * ships silently. Reported at the `path` value, in the partial that holds it
+ * when an `<include>` brought it in; a file shared by several locales is
+ * reported once. `extraTags` are the project's own components (islands +
+ * overrides), as for {@link validateUsedComponents}: one named `Component`
+ * replaces the built-in and resolves `path` its own way, so none is checked.
+ */
+export const missingExampleDiagnostics = (
+  pages: readonly PageRecord[],
+  discovery: ExampleKeys,
+  root: string,
+  extraTags: ReadonlySet<string>
+): Diagnostic[] => {
+  if (extraTags.has("Component")) {
+    return [];
+  }
+  const known = new Set(discovery.examples.map((example) => example.path));
+  const dir = relative(root, discovery.dir) || ".";
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    for (const use of page.examplesUsed ?? []) {
+      const file = use.file ?? page.sourcePath ?? page.id;
+      const key = `${file}:${use.line}:${use.column}`;
+      if (!(known.has(use.path) || seen.has(key))) {
+        seen.add(key);
+        diagnostics.push({
+          code: "BLUME_EXAMPLE_NOT_FOUND",
+          column: use.column,
+          file,
+          line: use.line,
+          message: `<Component path="${use.path}"> in ${page.route} names no example, so the page shows "No example found" in its place.`,
+          severity: "warning",
+          suggestion: `Fix the path, or add the example under ${dir}/: \`path\` is its location there, without the extension.`,
+        });
+      }
+    }
+  }
+  return diagnostics;
+};

package/src/core/component-overrides.ts

@@ -69,6 +69,29 @@ type Group = (typeof GROUPS)[number];
 
 const isGroup = (name: string): name is Group => GROUP_SET.has(name);
 
+/**
+ * The `layout` keys the built-in chrome reads (`RootLayout.astro` and
+ * `Header.astro`). Any other key is never rendered, so it's warned about
+ * rather than silently dropped; a typo or wrong case would otherwise leave
+ * the built-in in place with no sign why.
+ */
+const LAYOUT_SLOTS = [
+  "Layout",
+  "Header",
+  "Logo",
+  "Search",
+  "Sidebar",
+  "MobileNav",
+  "Breadcrumbs",
+  "TableOfContents",
+  "Pagination",
+  "Feedback",
+  "PageHeader",
+  "PageFooter",
+  "Footer",
+];
+const LAYOUT_SLOT_SET: ReadonlySet<string> = new Set(LAYOUT_SLOTS);
+
 /** The authoring forms an override accepts; the fix every rejection points at. */
 export const ACCEPTED_OVERRIDE_FORMS =
   "Each override must be an imported identifier, a path string, or a `{ component, client, media }` object literal whose `component` is an imported identifier or a path string.";
@@ -628,6 +651,15 @@ const collectGroupOverrides = (
     if (normalized) {
       result[name].push(normalized);
     }
+    if (
+      name === "layout" &&
+      normalized &&
+      !LAYOUT_SLOT_SET.has(normalized.key)
+    ) {
+      context.warnings.push(
+        `Layout override "${normalized.key}" isn't a layout slot, so nothing renders it. Use one of: ${LAYOUT_SLOTS.join(", ")}.`
+      );
+    }
   }
 };