blume 2.0.3 → 2.1.1

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/components/props.ts

@@ -44,9 +44,15 @@ export type FrameProps = ComponentProps<
 export type PanelProps = ComponentProps<
   typeof import("./content/Panel.astro").default
 >;
+export type ParamFieldProps = ComponentProps<
+  typeof import("./content/ParamField.astro").default
+>;
 export type PromptProps = ComponentProps<
   typeof import("./content/Prompt.astro").default
 >;
+export type ResponseFieldProps = ComponentProps<
+  typeof import("./content/ResponseField.astro").default
+>;
 export type StepProps = ComponentProps<
   typeof import("./content/Step.astro").default
 >;

package/src/consent/client.ts

@@ -0,0 +1,95 @@
+/**
+ * The browser half of the consent layer (`consent` in `blume.config.ts`),
+ * bundled into every layout by `ConsentHead.astro` and started once per real
+ * page load. It answers `window.blumeConsent` (see `init.ts`):
+ *
+ * - Analytics scripts wait in the page as `<script type="text/plain"
+ *   data-blume-consent="analytics">` (see `Analytics.astro`). Once the reader
+ *   allows analytics, each one runs, once per page load: the client router
+ *   brings the held tags back on every navigation, and running them again
+ *   would count every visit twice.
+ * - A reader who takes consent back after the scripts ran gets a reload, the
+ *   one way to stop scripts that already started.
+ * - Any element with `data-blume-consent-open` (the footer's Cookie settings
+ *   link) reopens the adapter's preferences.
+ * - An adapter with a browser module (`native()`'s banner, say) is started
+ *   from here once the runtime is listening; see `consent/clients.ts`.
+ */
+import type { BlumeConsent } from "../components/layout/consent/types.ts";
+
+/** The window, with the state the init script puts on it. */
+type ConsentWindow = Window & { blumeConsent?: BlumeConsent };
+
+/** Analytics tags held until the reader allows analytics. */
+export const HELD_SCRIPTS =
+  'script[type="text/plain"][data-blume-consent="analytics"]';
+
+const OPEN = "[data-blume-consent-open]";
+
+/**
+ * Run each held tag the page hasn't run yet, as a new `<script>` beside it
+ * with the same attributes and body. `ran` is keyed by the tag's markup,
+ * which is the same on every page, so a tag the router brings back is
+ * skipped.
+ */
+export const runHeldScripts = (ran: Set<string>): void => {
+  for (const held of document.querySelectorAll(HELD_SCRIPTS)) {
+    const key = held.outerHTML;
+    if (ran.has(key)) {
+      continue;
+    }
+    ran.add(key);
+    const script = document.createElement("script");
+    for (const { name, value } of held.attributes) {
+      if (name !== "type" && name !== "data-blume-consent") {
+        script.setAttribute(name, value);
+      }
+    }
+    // A created script is async unless told otherwise; keep the tags in
+    // document order, as the parser would have, unless one asked for async.
+    if (!held.hasAttribute("async")) {
+      script.async = false;
+    }
+    script.text = held.textContent ?? "";
+    held.after(script);
+  }
+};
+
+/**
+ * Start the consent runtime on this page load, then the configured adapter's
+ * browser module (`startClient`, from the generated `blume:consent-client`;
+ * none for a hosted manager, whose `<head>` tags report its answers).
+ */
+export const startConsent = (
+  startClient: (consent: BlumeConsent) => void = () => {
+    // No browser module: a hosted manager's <head> tags report its answers.
+  }
+): void => {
+  // SAFETY: ConsentWindow only adds the optional state the init script
+  // creates; it's checked before use.
+  const consent = (window as ConsentWindow).blumeConsent;
+  if (!consent) {
+    return;
+  }
+  const ran = new Set<string>();
+  const run = () => {
+    if (consent.analytics === true) {
+      runHeldScripts(ran);
+    }
+  };
+  window.addEventListener("blume:consent", () => {
+    if (consent.analytics === true) {
+      runHeldScripts(ran);
+    } else if (ran.size > 0) {
+      location.reload();
+    }
+  });
+  document.addEventListener("click", (event) => {
+    if (event.target instanceof Element && event.target.closest(OPEN)) {
+      consent.open?.();
+    }
+  });
+  startClient(consent);
+  run();
+  document.addEventListener("astro:after-swap", run);
+};

package/src/consent/clients.ts

@@ -0,0 +1,19 @@
+/**
+ * The browser module each consent adapter brings, by `kind`. The generated
+ * `blume:consent-client` (see `consentClientTemplate`) imports the configured
+ * adapter's, so a site bundles only its own adapter's browser code, the way
+ * `blume:search-client` does for search.
+ *
+ * Hosted managers (`osano()`, `ethyca()`) have none: their `<head>` tags load
+ * them and report their answers (see `head.ts`). A manager that ships as an
+ * npm package adds its module under `components/layout/consent/` instead: a
+ * `start` (`ConsentClientStart` in its `types.ts`) that reports the reader's answer with
+ * `consent.set({ analytics })` and sets `consent.open`, with the packages it
+ * imports listed in its factory's `runtimeDeps`, so only the sites that pick
+ * it install them.
+ */
+
+/** Each adapter's browser module, as the generated project imports it. */
+export const CONSENT_CLIENT_MODULES = new Map([
+  ["native", "blume/components/layout/consent/native.ts"],
+]);

package/src/consent/ethyca.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+import type { HeadScript } from "../analytics/head.ts";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link ethyca}. */
+export interface EthycaOptions {
+  /**
+   * The key of the privacy notice that covers analytics, as you named it in
+   * Fides. Defaults to `analytics`.
+   */
+  notice?: string;
+  /** Your Fides privacy center's origin, which serves `fides.js`. */
+  privacyCenter: string;
+  /** The Fides property to load, when you have more than one. */
+  propertyId?: string;
+}
+
+export const ethycaOptionsSchema = z.strictObject({
+  notice: z.string().min(1).optional(),
+  privacyCenter: z.url({ protocol: /^https?$/u }),
+  propertyId: z.string().min(1).optional(),
+});
+
+export type EthycaAdapter = AdapterDescriptor<"ethyca", EthycaOptions>;
+
+export const ethycaAdapterSchema = adapterDescriptorSchema(
+  "ethyca",
+  ethycaOptionsSchema
+);
+
+/**
+ * Ethyca's Fides consent manager, loaded from your privacy center. Fides
+ * shows its own banner and modal, set up in Fides, and Blume runs the
+ * analytics once the reader's analytics notice is on. Nothing here is
+ * secret.
+ */
+export const ethyca = (options: EthycaOptions): EthycaAdapter => ({
+  kind: "ethyca",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * Reports the analytics notice to `window.blumeConsent` when Fides is ready
+ * and whenever the reader saves a change, and reopens Fides' modal from the
+ * Cookie settings link. The notice key rides in as `data-notice`. It counts
+ * as allowed when on (`true`), opted in, or a notice that only asks for
+ * acknowledgment.
+ */
+export const ETHYCA_BRIDGE = `(()=>{const c=window.blumeConsent;if(!c){return;}const k=document.currentScript?.dataset.notice??"analytics";const sync=(e)=>{const v=(e?.detail?.consent??window.Fides?.consent??{})[k];c.set({analytics:v===true||v==="opt_in"||v==="acknowledge"});};c.open=()=>window.Fides?.showModal();addEventListener("FidesReady",sync);addEventListener("FidesUpdated",sync);if(window.Fides?.initialized){sync();}})();`;
+
+/** Fides' script from the privacy center, then the bridge. */
+export const ethycaHead = (options: EthycaOptions): HeadScript[] => {
+  const src = new URL(
+    "fides.js",
+    `${options.privacyCenter.replace(/\/+$/u, "")}/`
+  );
+  if (options.propertyId) {
+    src.searchParams.set("property_id", options.propertyId);
+  }
+  return [
+    { attributes: { src: src.href }, content: null },
+    {
+      attributes: { "data-notice": options.notice ?? "analytics" },
+      content: ETHYCA_BRIDGE,
+    },
+  ];
+};

package/src/consent/head.ts

@@ -0,0 +1,24 @@
+import type { HeadScript } from "../analytics/head.ts";
+import { ethycaHead } from "./ethyca.ts";
+import { osanoHead } from "./osano.ts";
+import type { ConsentAdapter } from "./schema.ts";
+
+/**
+ * The tags one consent adapter emits into `<head>`, after the init script and
+ * ahead of the held analytics: a hosted manager's loader and the bridge that
+ * reports its answers to `window.blumeConsent`. `native()` has none; its
+ * banner is markup (`ConsentBanner.astro`) and its logic is the runtime's.
+ */
+export const consentHead = (adapter: ConsentAdapter): HeadScript[] => {
+  switch (adapter.kind) {
+    case "ethyca": {
+      return ethycaHead(adapter.options);
+    }
+    case "osano": {
+      return osanoHead(adapter.options);
+    }
+    default: {
+      return [];
+    }
+  }
+};

package/src/consent/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Consent adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { googleAnalytics } from "blume/analytics";
+ * import { native } from "blume/consent";
+ *
+ * export default defineConfig({
+ *   analytics: [googleAnalytics({ id: "G-XXXXXXXXXX" })],
+ *   consent: native({ policy: "/privacy" }),
+ * });
+ * ```
+ *
+ * With `consent` set, analytics waits for the reader: every adapter's tags are
+ * held until the consent adapter reports that analytics is allowed. Each
+ * factory returns a plain descriptor (see `core/adapter.ts`).
+ *
+ * Adding a consent manager: a factory and option schema in its own module,
+ * and a member of `consentAdapterSchema` (`schema.ts`). Then connect it to
+ * `window.blumeConsent` (see `init.ts` for the contract): report the reader's
+ * choice with `set({ analytics })` on load and on every change, and set
+ * `open` to reopen the manager's preferences. A hosted manager does that
+ * with tags in `consentHead` (`head.ts`): its loader, then a constant bridge
+ * script (`osano.ts` is an example). A manager that ships as an npm package
+ * does it in a browser module instead, registered in `clients.ts`, with its
+ * packages in the factory's `runtimeDeps` (`native()`'s banner is the
+ * example).
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { ethyca } from "./ethyca.ts";
+export type { EthycaAdapter, EthycaOptions } from "./ethyca.ts";
+export { native } from "./native.ts";
+export type { NativeAdapter, NativeOptions } from "./native.ts";
+export { osano } from "./osano.ts";
+export type { OsanoAdapter, OsanoOptions } from "./osano.ts";
+export type { ConsentAdapter } from "./schema.ts";

package/src/consent/init.ts

@@ -0,0 +1,29 @@
+/**
+ * The consent layer's first script, inlined at the top of `<head>` on every
+ * page when `consent` is configured, ahead of any adapter's script and the
+ * held analytics. It creates `window.blumeConsent`, the one contract every
+ * consent adapter talks to:
+ *
+ * - `analytics`: `null` until an adapter reports, then the reader's choice.
+ * - `set({ analytics })`: what an adapter calls with the reader's choice, on
+ *   load for a returning reader and again whenever it changes. A change fires
+ *   a `blume:consent` event on `window` (`detail: { analytics }`), which the
+ *   runtime (`client.ts`) answers by running the held analytics, and which a
+ *   site can listen to for its own scripts.
+ * - `open()`: set by an adapter to reopen its preferences; the footer's
+ *   Cookie settings link calls it.
+ * - `kind`: the configured adapter (`native`, `osano`, …), from the tag's
+ *   `data-kind`.
+ *
+ * It also sets `window.webAnalyticsBeforeSend`, which Vercel Web Analytics
+ * reads when it starts, so `vercel()` sends nothing until analytics is
+ * allowed; its script is a component rather than a tag, so it can't be held
+ * like the others.
+ *
+ * A constant, like the layouts' other inline scripts (see
+ * `components/layout/head-scripts.ts`): the kind rides in as an attribute,
+ * never as interpolated source. It runs once per real page load; the client
+ * router never runs an inline script twice, and the state it creates lives
+ * on across navigations.
+ */
+export const CONSENT_INIT_SCRIPT = `(()=>{if(window.blumeConsent){return;}const c={analytics:null,kind:document.currentScript?.dataset.kind??"",set(s){const a=s?.analytics===true;if(c.analytics===a){return;}c.analytics=a;dispatchEvent(new CustomEvent("blume:consent",{detail:{analytics:a}}));}};window.blumeConsent=c;window.webAnalyticsBeforeSend=(e)=>c.analytics===true?e:null;})();`;

package/src/consent/native.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link native}. */
+export interface NativeOptions {
+  /** Where the banner's privacy policy link goes: a page route or a URL. */
+  policy?: string;
+}
+
+export const nativeOptionsSchema = z.strictObject({
+  policy: z.string().min(1).optional(),
+});
+
+export type NativeAdapter = AdapterDescriptor<"native", NativeOptions>;
+
+export const nativeAdapterSchema = adapterDescriptorSchema(
+  "native",
+  nativeOptionsSchema
+);
+
+/**
+ * Blume's own consent banner: a card at the foot of the page asking to use
+ * analytics cookies, with Accept and Decline side by side and an optional
+ * link to your privacy policy. The answer stays in the reader's browser, and
+ * the footer's Cookie settings link brings the banner back to change it. Its
+ * text comes from the `consent` UI strings, translated in every built-in
+ * language.
+ */
+export const native = (options: NativeOptions = {}): NativeAdapter => ({
+  kind: "native",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/consent/osano.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+import type { HeadScript } from "../analytics/head.ts";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link osano}. */
+export interface OsanoOptions {
+  /** The configuration ID from the script tag Osano gives you. */
+  configId: string;
+  /** The customer ID from the script tag Osano gives you. */
+  customerId: string;
+}
+
+export const osanoOptionsSchema = z.strictObject({
+  configId: z.string().min(1),
+  customerId: z.string().min(1),
+});
+
+export type OsanoAdapter = AdapterDescriptor<"osano", OsanoOptions>;
+
+export const osanoAdapterSchema = adapterDescriptorSchema(
+  "osano",
+  osanoOptionsSchema
+);
+
+/**
+ * Osano Cookie Consent. Osano shows its own banner and drawer, set up in the
+ * Osano dashboard, and Blume runs the analytics once Osano reports the
+ * reader's `ANALYTICS` consent. Both IDs come from the script tag Osano
+ * gives you, and neither is secret.
+ */
+export const osano = (options: OsanoOptions): OsanoAdapter => ({
+  kind: "osano",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * Reports Osano's analytics consent to `window.blumeConsent` now (`Osano.cm`
+ * is ready as soon as its script ran) and on every Osano consent event, and
+ * reopens Osano's drawer from the Cookie settings link.
+ */
+export const OSANO_BRIDGE = `(()=>{const o=window.Osano?.cm;const c=window.blumeConsent;if(!o||!c){return;}const sync=()=>c.set({analytics:o.analytics===true});c.open=()=>o.showDrawer();for(const e of ["osano-cm-initialized","osano-cm-consent-saved","osano-cm-consent-changed"]){o.addEventListener(e,sync);}sync();})();`;
+
+/**
+ * Osano's loader, synchronous as its install guide requires, then the
+ * bridge. The IDs are path segments, so each is encoded.
+ */
+export const osanoHead = (options: OsanoOptions): HeadScript[] => [
+  {
+    attributes: {
+      src: `https://cmp.osano.com/${encodeURIComponent(options.customerId)}/${encodeURIComponent(options.configId)}/osano.js`,
+    },
+    content: null,
+  },
+  { attributes: {}, content: OSANO_BRIDGE },
+];

package/src/consent/schema.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+import { ethycaAdapterSchema } from "./ethyca.ts";
+import { nativeAdapterSchema } from "./native.ts";
+import { osanoAdapterSchema } from "./osano.ts";
+
+const ADAPTER_HINT =
+  'consent takes one adapter — e.g. `consent: native()` or `consent: osano({ customerId, configId })`, imported from "blume/consent".';
+
+/**
+ * The configured consent adapter, as its factory returned it. Anything that
+ * isn't one (`true`, a list, an unknown `kind`) fails with the adapter hint;
+ * an adapter's own option errors keep their messages.
+ */
+export const consentAdapterSchema = z.discriminatedUnion(
+  "kind",
+  [ethycaAdapterSchema, nativeAdapterSchema, osanoAdapterSchema],
+  { error: ADAPTER_HINT }
+);
+
+export type ConsentAdapter = z.output<typeof consentAdapterSchema>;
+
+/**
+ * `blume.config.consent`: the adapter that asks readers before analytics
+ * runs. Unset (`null` once resolved) means no consent layer, and analytics
+ * runs as it loads.
+ */
+export const consentConfigSchema = consentAdapterSchema
+  .optional()
+  .transform((adapter) => adapter ?? null);

package/src/core/builtin-tags.ts

@@ -31,7 +31,11 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Math",
   "Operation",
   "Panel",
+  "ParamField",
   "Prompt",
+  "RequestExample",
+  "ResponseExample",
+  "ResponseField",
   "Step",
   "Steps",
   "Tab",
@@ -40,6 +44,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Tooltip",
   "Tree",
   "TypeTable",
+  "View",
   "Visibility",
   "YouTube",
 ]);

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/client-address.ts

@@ -0,0 +1,19 @@
+/** The slice of Astro's `APIContext` a server route reads the reader from. */
+export interface ClientContext {
+  /** The reader's address; Astro's getter throws where the host can't tell. */
+  readonly clientAddress?: string;
+  readonly request: Request;
+}
+
+/**
+ * The reader's IP address as the host reports it (Astro resolves the
+ * platform's trusted header, or the socket on a Node server), or `undefined`
+ * where the host can't tell.
+ */
+export const clientAddressOf = (context: ClientContext): string | undefined => {
+  try {
+    return context.clientAddress || undefined;
+  } catch {
+    return undefined;
+  }
+};

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(", ")}.`
+      );
+    }
   }
 };