@decocms/blocks 7.28.0-beta.5 → 7.28.1

package/src/cms/resolve.ts

@@ -1,3 +1,10 @@
+import {
+  type ActionConfig,
+  inferLoaderTags,
+  type LoaderConfig,
+  registerActionSchemas,
+  registerLoaderSchemas,
+} from "./schema";
 import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
 import { getMeter, MetricNames, withTracing } from "../middleware/observability";
 import { djb2Hex } from "../sdk/djb2";
@@ -6,13 +13,6 @@ import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
-import {
-  type ActionConfig,
-  inferLoaderTags,
-  type LoaderConfig,
-  registerActionSchemas,
-  registerLoaderSchemas,
-} from "./schema";
 import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
@@ -127,17 +127,25 @@ export interface AsyncRenderingConfig {
   /** Section component keys that must always be rendered eagerly. */
   alwaysEager: Set<string>;
   /**
-   * Bot-aware page SEO. When true, the page-level `seo` block's
-   * commerce-loader-backed props (e.g. `jsonLD: { __resolveType: "PLP Loader" }`)
-   * are SKIPPED for human (non-bot) requests — so SSR doesn't run the heavy
-   * upstream fetch and the product payload never reaches the human HTML. Bots
-   * still get the full SEO (JSON-LD) for indexing.
+   * Site-wide bot-aware page SEO shortcut. When true, the page-level `seo`
+   * block's commerce-loader-backed props (e.g. `jsonLD: { __resolveType: "PLP
+   * Loader" }`) are SKIPPED for human (non-bot) requests — so SSR doesn't run
+   * the heavy upstream fetch and the product payload never reaches the human
+   * HTML. Bots still get the full SEO (JSON-LD) for indexing.
+   *
+   * This is a blanket, developer-set shortcut. The PRIMARY, client-facing lever
+   * is the per-section `ignoreStructuredData` toggle in the admin (on the PLP/PDP
+   * SEO section): it drives the exact same fetch-skip + bot-aware JSON-LD, but
+   * per section and without a code change. This flag simply turns the behavior
+   * on for every commerce-backed SEO block at once.
    *
    * OFF by default: the optimization removes the commerce data a human `<title>`
-   * may derive from, so it is only safe once the site provides a lightweight
-   * title fallback (e.g. a cheap category-metadata loader). Sites that just bump
-   * the framework keep the previous behavior (full SEO for everyone) and are not
-   * regressed. Opt in with `setAsyncRenderingConfig({ botAwareSeo: true })`.
+   * may derive from, so a blanket opt-in is only safe once the site provides a
+   * lightweight title fallback (e.g. a cheap category-metadata loader). Sites
+   * that just bump the framework keep the previous behavior (full SEO for
+   * everyone) and are not regressed. Opt in with
+   * `setAsyncRenderingConfig({ botAwareSeo: true })`, or leave it off and let
+   * editors flip `ignoreStructuredData` per section.
    * @default false
    */
   botAwareSeo: boolean;
@@ -227,7 +235,7 @@ function isEagerSection(key: string): boolean {
  * during hydration (search filters, configurators, etc.).
  */
 export function registerNeverDeferSections(keys: string[]): void {
-  const set: Set<string> = (G.__deco.neverDeferSectionKeys ??= new Set());
+  const set: Set<string> = G.__deco.neverDeferSectionKeys ??= new Set();
   for (const k of keys) set.add(k);
 }
 
@@ -342,7 +350,8 @@ function hasForceEagerParam(ctx?: MatcherContext): boolean {
  */
 function isProgrammaticFetch(ctx?: MatcherContext): boolean {
   if (ctx?.isClientNavigation) return false;
-  const dest = ctx?.request?.headers.get("sec-fetch-dest") ?? ctx?.headers?.["sec-fetch-dest"];
+  const dest = ctx?.request?.headers.get("sec-fetch-dest") ??
+    ctx?.headers?.["sec-fetch-dest"];
   return dest === "empty";
 }
 
@@ -353,7 +362,8 @@ function isProgrammaticFetch(ctx?: MatcherContext): boolean {
  * to gate both section deferral and page-SEO commerce resolution.
  */
 export function isEagerRequest(ctx?: MatcherContext): boolean {
-  return isBot(ctx?.userAgent) || hasForceEagerParam(ctx) || isProgrammaticFetch(ctx);
+  return isBot(ctx?.userAgent) || hasForceEagerParam(ctx) ||
+    isProgrammaticFetch(ctx);
 }
 
 /**
@@ -733,9 +743,7 @@ function evaluateVariantRule(
   const already = ctx.flags?.find((f) => f.name === meta.name && f.pct === meta.pct);
   if (already) return already.value;
 
-  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find(
-    (f) => f.name === meta.name,
-  );
+  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find((f) => f.name === meta.name);
   // pct === -1 marks a classic-deco segment without a fingerprint — honor it
   // (stay sticky) instead of re-rolling. A stale fingerprint re-rolls.
   const useStored = stored && (stored.pct === -1 || stored.pct === meta.pct);
@@ -1124,18 +1132,21 @@ export async function resolvePageSeoBlock(
 ): Promise<ResolvedSection | null> {
   if (!seoBlock || typeof seoBlock !== "object") return null;
 
-  // Bot-aware SEO is OPT-IN (`setAsyncRenderingConfig({ botAwareSeo: true })`).
-  // When disabled (default), resolve the SEO block fully for EVERYONE — the
-  // previous behavior — so sites that bump the framework without a lightweight
-  // title fallback are not regressed to a generic `<title>`.
-  //
-  // When enabled: crawlers get the SEO block fully resolved (e.g. a
+  // Bot-aware SEO: crawlers get the SEO block fully resolved (e.g. a
   // ProductListingPage for JSON-LD ItemList) — that content exists for indexing;
-  // humans get only the lightweight metadata — SEO props backed by a commerce
-  // loader are skipped (see `stripCommerceLoaderProps`) so SSR doesn't block on
-  // the heavy upstream call and the bulky payload never reaches the human HTML.
-  const botAwareSeo = getAsyncConfig()?.botAwareSeo ?? false;
-  const seoForBot = !botAwareSeo || isEagerRequest(rctx.matcherCtx);
+  // humans get only the lightweight metadata, with SEO props backed by a commerce
+  // loader skipped (see `stripCommerceLoaderProps`) so SSR doesn't block on the
+  // heavy upstream call and the bulky payload never reaches the human HTML.
+  //
+  // The skip is driven per-section by the editor's `ignoreStructuredData` toggle
+  // (the primary, client-facing lever — see `sectionIgnoresStructuredData`), OR
+  // site-wide by the legacy `setAsyncRenderingConfig({ botAwareSeo: true })`
+  // shortcut. When neither is set, resolve fully for EVERYONE (the previous
+  // default) so sites without a lightweight title fallback are not regressed to
+  // a generic `<title>`. The final decision is made at the terminal section
+  // below, where the section's raw props are known.
+  const isEagerReq = isEagerRequest(rctx.matcherCtx);
+  const globalBotAware = getAsyncConfig()?.botAwareSeo ?? false;
 
   const blocks = loadBlocks();
   let current = seoBlock;
@@ -1195,7 +1206,11 @@ export async function resolvePageSeoBlock(
     // (e.g. `jsonLD: { __resolveType: "PLP Loader" }`). This avoids the heavy
     // SSR fetch and keeps the product payload out of the human HTML. Bots keep
     // the full props so JSON-LD/rich metadata is still emitted for indexing.
-    const propsToResolve = seoForBot ? rawProps : stripCommerceLoaderProps(rawProps);
+    // Skip only when the editor turned on `ignoreStructuredData` for this
+    // section, or the site-wide `botAwareSeo` shortcut is enabled.
+    const skipCommerceForHuman =
+      !isEagerReq && (globalBotAware || sectionIgnoresStructuredData(rawProps));
+    const propsToResolve = skipCommerceForHuman ? stripCommerceLoaderProps(rawProps) : rawProps;
     try {
       const resolvedProps = await resolveProps(propsToResolve, rctx);
       return {
@@ -1257,6 +1272,24 @@ function resolvesToCommerceLoader(value: unknown, depth = 0): boolean {
   return false;
 }
 
+/**
+ * True when a commerce SEO section's props carry the editor's "Ignore Structured
+ * Data" toggle. This is the primary, client-facing lever for bot-aware SEO: with
+ * it on, humans receive no JSON-LD (and, on the page's SEO block, skip the heavy
+ * commerce fetch) while crawlers still get the full structured data.
+ *
+ * Two shapes, mirroring the Studio schema: top-level `ignoreStructuredData` on
+ * the PDP section, and nested under `configJsonLD` on the PLP section. Shared by
+ * the fetch-skip path (`resolvePageSeoBlock`, pre-resolution) and the
+ * output-strip path (`deriveCommerceSeoFromJsonLD`, post-resolution) so the two
+ * decisions can never read the toggle differently.
+ */
+function sectionIgnoresStructuredData(props: Record<string, unknown>): boolean {
+  if (props.ignoreStructuredData === true) return true;
+  const configJsonLD = props.configJsonLD as { ignoreStructuredData?: boolean } | undefined;
+  return configJsonLD?.ignoreStructuredData === true;
+}
+
 /**
  * Return a copy of `rawProps` with every top-level field that resolves to a
  * commerce loader removed. Applied to page SEO props for human (non-bot)
@@ -1264,7 +1297,9 @@ function resolvesToCommerceLoader(value: unknown, depth = 0): boolean {
  * serialized into the HTML. Lightweight literal props (title, description,
  * canonical, …) are preserved.
  */
-function stripCommerceLoaderProps(rawProps: Record<string, unknown>): Record<string, unknown> {
+function stripCommerceLoaderProps(
+  rawProps: Record<string, unknown>,
+): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(rawProps)) {
     if (resolvesToCommerceLoader(v)) continue;
@@ -1745,7 +1780,11 @@ function pruneCommerceJsonLD(
  * gaps and appends the JSON-LD. The caller guards on `seo.jsonLDs` so a real
  * site SEO section that already computed structured data is never touched.
  */
-function deriveCommerceSeoFromJsonLD(seo: PageSeo, props: Record<string, unknown>): void {
+function deriveCommerceSeoFromJsonLD(
+  seo: PageSeo,
+  props: Record<string, unknown>,
+  isEager: boolean,
+): void {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const jsonLD = props.jsonLD as Record<string, any> | undefined;
   if (!jsonLD) return;
@@ -1779,12 +1818,15 @@ function deriveCommerceSeoFromJsonLD(seo: PageSeo, props: Record<string, unknown
   }
 
   // Structured data — opt out via `ignoreStructuredData` (top-level on PDP,
-  // under `configJsonLD` on PLP). An empty page contributes no ItemList.
+  // under `configJsonLD` on PLP). Bot-aware: the toggle suppresses JSON-LD for
+  // humans only; crawlers (and the `?__deco_ssr=1` audit override) still get it
+  // so indexing/rich results are unaffected. An empty page contributes no
+  // ItemList regardless.
   const configJsonLD = props.configJsonLD as
     | { ignoreStructuredData?: boolean; removeVideos?: boolean }
     | undefined;
-  const ignore = props.ignoreStructuredData === true || configJsonLD?.ignoreStructuredData === true;
-  if (ignore || isEmpty) return;
+  const ignore = sectionIgnoresStructuredData(props);
+  if ((ignore && !isEager) || isEmpty) return;
 
   seo.jsonLDs = [
     pruneCommerceJsonLD(jsonLD, {
@@ -1798,7 +1840,11 @@ function deriveCommerceSeoFromJsonLD(seo: PageSeo, props: Record<string, unknown
  * Pick standard SEO fields from a props object.
  * Works for both framework SEO types (SeoV2) and site SEO sections (SEOPDP).
  */
-export function extractSeoFromProps(props: Record<string, unknown>): PageSeo {
+export function extractSeoFromProps(
+  props: Record<string, unknown>,
+  opts?: { isEager?: boolean },
+): PageSeo {
+  const isEager = opts?.isEager ?? false;
   const seo: PageSeo = {};
   if (props.title) seo.title = props.title as string;
   if (props.description) seo.description = props.description as string;
@@ -1813,7 +1859,7 @@ export function extractSeoFromProps(props: Record<string, unknown>): PageSeo {
   // Legacy commerce PLP/PDP sections carry a `jsonLD` data source with no
   // component to turn it into structured data — derive it here (only when a
   // real SEO section hasn't already emitted `jsonLDs`).
-  if (!seo.jsonLDs) deriveCommerceSeoFromJsonLD(seo, props);
+  if (!seo.jsonLDs) deriveCommerceSeoFromJsonLD(seo, props, isEager);
   return seo;
 }
 
@@ -1822,11 +1868,14 @@ export function extractSeoFromProps(props: Record<string, unknown>): PageSeo {
  * `registerSeoSections`. Later sections override earlier ones
  * (e.g., a PDP SEO section overrides a generic page SEO).
  */
-export function extractSeoFromSections(sections: ResolvedSection[]): PageSeo {
+export function extractSeoFromSections(
+  sections: ResolvedSection[],
+  opts?: { isEager?: boolean },
+): PageSeo {
   const seo: PageSeo = {};
   for (const section of sections) {
     if (!seoSectionKeys.has(section.component)) continue;
-    const extracted = extractSeoFromProps(section.props);
+    const extracted = extractSeoFromProps(section.props, opts);
     if (extracted.jsonLDs) {
       extracted.jsonLDs = [...(seo.jsonLDs ?? []), ...extracted.jsonLDs];
     }

package/src/cms/schema.test.ts

@@ -253,9 +253,10 @@ describe("commerce SEO section schemas", () => {
     // PLP-specific structured-data config (see seo-form-mode.ts PLP_SEO_FIELD_KEYS).
     expect(props.configJsonLD.properties).toHaveProperty("removeVideos");
     expect(props.configJsonLD.properties).toHaveProperty("ignoreStructuredData");
-    // The data source is set once at creation and stays hidden in the SEO panel;
-    // it round-trips via the form rather than being re-picked here.
-    expect(props.jsonLD.hide).toBe(true);
+    // The data source is a loader picker (anyOf over the loader union), not
+    // hidden — the user picks the PLP loader that feeds the structured data.
+    expect(Array.isArray(props.jsonLD.anyOf)).toBe(true);
+    expect(props.jsonLD.title).toBe("Data Source");
   });
 
   it("emits editable props for the product-details SEO section (pdp mode)", () => {
@@ -268,7 +269,8 @@ describe("commerce SEO section schemas", () => {
     // PDP-specific fields (see seo-form-mode.ts PDP_SEO_FIELD_KEYS).
     expect(props).toHaveProperty("omitVariants");
     expect(props).toHaveProperty("ignoreStructuredData");
-    expect(props.jsonLD.hide).toBe(true);
+    expect(Array.isArray(props.jsonLD.anyOf)).toBe(true);
+    expect(props.jsonLD.title).toBe("Data Source");
   });
 
   it("registers the defs + manifest blocks and offers them as page.seo options", () => {
@@ -285,6 +287,51 @@ describe("commerce SEO section schemas", () => {
       expect(meta.schema.root.sections.anyOf).toContainEqual(b64Ref(key));
     }
   });
+
+  // Mirrors a generated site meta: a loader carries a real def AND is listed in
+  // the site's loader union. `@ignore`d loaders are the exception — they get a
+  // def but are withheld from the union.
+  function siteMetaWithLoader(key: string, opts: { inUnion: boolean }) {
+    const site = emptySiteMeta();
+    site.schema.definitions[b64(key)] = {
+      title: key,
+      type: "object",
+      properties: { __resolveType: { type: "string", enum: [key] } },
+    };
+    site.manifest.blocks.loaders = {
+      [key]: { $ref: `#/definitions/${b64(key)}`, namespace: "site" },
+    };
+    site.schema.root = { loaders: { anyOf: opts.inUnion ? [b64Ref(key)] : [] } };
+    return site;
+  }
+
+  it("feeds the site's own loaders into the jsonLD data-source picker", () => {
+    // The runtime loader registry is empty at generation time, so the union must
+    // be seeded from the site's own loader union — else the picker has no
+    // options and the user can't wire the data source.
+    const loaderKey = "site/loaders/product/productDetailsPage.ts";
+    const meta = composeMeta(siteMetaWithLoader(loaderKey, { inUnion: true }));
+
+    // The picker option is real, not a dangling $ref: its def survives.
+    expect(meta.schema.definitions).toHaveProperty(b64(loaderKey));
+    // …offered in both the root union and the commerce SEO jsonLD picker.
+    expect(meta.schema.root.loaders.anyOf).toContainEqual(b64Ref(loaderKey));
+    const seoDef =
+      meta.schema.definitions[b64("commerce/sections/Seo/SeoPDPV2.tsx")];
+    expect(seoDef.properties.jsonLD.anyOf).toContainEqual(b64Ref(loaderKey));
+  });
+
+  it("keeps @ignore'd loaders (in the manifest, not the union) out of the picker", () => {
+    // Seeding from `manifest.blocks.loaders` would resurrect hidden loaders;
+    // seeding from the union keeps them out.
+    const hiddenKey = "site/loaders/internal/hidden.ts";
+    const meta = composeMeta(siteMetaWithLoader(hiddenKey, { inUnion: false }));
+
+    expect(meta.schema.root.loaders.anyOf).not.toContainEqual(b64Ref(hiddenKey));
+    const seoDef =
+      meta.schema.definitions[b64("commerce/sections/Seo/SeoPDPV2.tsx")];
+    expect(seoDef.properties.jsonLD.anyOf).not.toContainEqual(b64Ref(hiddenKey));
+  });
 });
 
 describe("composeMeta idempotency", () => {

package/src/cms/schema.ts

@@ -731,7 +731,16 @@ function buildPageSchema(sectionAnyOf: any[]) {
 // Framework sections
 // ---------------------------------------------------------------------------
 
-function buildFrameworkSections(sectionAnyOf: any[]) {
+// Merchant-facing help for the per-section `ignoreStructuredData` toggle, shared
+// by the PLP (`configJsonLD`) and PDP (top-level) SEO sections. The fetch-skip is
+// deliberately scoped to "the page's SEO source" — it only fires when this block
+// is wired as the page's SEO (`page.seo`), not when the section is dropped inline
+// in the sections array (there the commerce loader still runs; only the JSON-LD
+// output is omitted for visitors).
+const IGNORE_STRUCTURED_DATA_DESCRIPTION =
+  "By default, Structured Data (JSON-LD) is sent to everyone. Turn this on to omit it for regular visitors while crawlers and bots still receive the full Structured Data. When this block is the page's SEO source, the product fetch is also skipped for visitors, so the page loads faster. Some integrations may rely on Structured Data being present for all users.";
+
+function buildFrameworkSections(sectionAnyOf: any[], loaderUnion: any[]) {
   const definitions: Record<string, any> = {};
   const manifestBlocks: Record<string, any> = {};
   const extraAnyOf: any[] = [];
@@ -839,8 +848,12 @@ function buildFrameworkSections(sectionAnyOf: any[]) {
   // there is no manifest to emit these props from. The Studio's SEO editor
   // already knows this type as its "plp" mode (see seo-form-mode.ts); it just
   // needs the props schema to render the override fields. `jsonLD` is the
-  // data-source block-ref set once when the page is created; it round-trips via
-  // the form (kept `hide`) rather than being re-picked in the SEO panel.
+  // data-source loader picker (mirrors deco-cx's `@title Data Source`) — an
+  // inline anyOf over the loader union so the editor lets you pick the PLP/PDP
+  // loader that feeds the structured data. Inlined (a fresh copy) rather than a
+  // `$ref: "#/root/loaders"` because the Studio drops the prop-level title when
+  // resolving a `$ref` union, which would lose the "Data Source" label; the
+  // copy also avoids sharing one array instance across the two defs + root.
   //
   // Added to `extraAnyOf` (offered as a selectable page.seo type) unconditionally,
   // like the website Seo sections above. Gating this on "is a commerce site" via
@@ -861,12 +874,7 @@ function buildFrameworkSections(sectionAnyOf: any[]) {
         enum: [SEO_PLP_V2_TYPE],
         default: SEO_PLP_V2_TYPE,
       },
-      jsonLD: {
-        type: "object",
-        title: "Data Source",
-        additionalProperties: true,
-        hide: true,
-      },
+      jsonLD: { title: "Data Source", anyOf: [...loaderUnion] },
       title: { type: "string", title: "Title Override" },
       description: { type: "string", title: "Description Override" },
       noIndexing: { type: "boolean", title: "Disable indexing" },
@@ -875,7 +883,11 @@ function buildFrameworkSections(sectionAnyOf: any[]) {
         title: "Structured Data",
         properties: {
           removeVideos: { type: "boolean", title: "Remove videos" },
-          ignoreStructuredData: { type: "boolean", title: "Ignore Structured Data" },
+          ignoreStructuredData: {
+            type: "boolean",
+            title: "Ignore Structured Data",
+            description: IGNORE_STRUCTURED_DATA_DESCRIPTION,
+          },
         },
       },
     },
@@ -900,17 +912,16 @@ function buildFrameworkSections(sectionAnyOf: any[]) {
         enum: [SEO_PDP_V2_TYPE],
         default: SEO_PDP_V2_TYPE,
       },
-      jsonLD: {
-        type: "object",
-        title: "Data Source",
-        additionalProperties: true,
-        hide: true,
-      },
+      jsonLD: { title: "Data Source", anyOf: [...loaderUnion] },
       omitVariants: { type: "boolean", title: "Omit variants" },
       title: { type: "string", title: "Title Override" },
       description: { type: "string", title: "Description Override" },
       noIndexing: { type: "boolean", title: "Disable indexing" },
-      ignoreStructuredData: { type: "boolean", title: "Ignore Structured Data" },
+      ignoreStructuredData: {
+        type: "boolean",
+        title: "Ignore Structured Data",
+        description: IGNORE_STRUCTURED_DATA_DESCRIPTION,
+      },
     },
   };
   manifestBlocks[SEO_PDP_V2_TYPE] = {
@@ -1089,7 +1100,10 @@ export interface ComposeMetaOptions {
   framework?: string;
 }
 
-export function composeMeta(siteMeta: MetaResponse, options?: ComposeMetaOptions): MetaResponse {
+export function composeMeta(
+  siteMeta: MetaResponse,
+  options?: ComposeMetaOptions,
+): MetaResponse {
   // Idempotency guard. composeMeta is NOT structurally idempotent — it appends
   // the framework section refs to `root.sections.anyOf` (and `__SECTION_REF__`),
   // so composing an already-composed meta a second time duplicates those refs.
@@ -1106,11 +1120,36 @@ export function composeMeta(siteMeta: MetaResponse, options?: ComposeMetaOptions
 
   const siteAnyOf = siteMeta.schema?.root?.sections?.anyOf || [];
 
-  // Build all framework components
-  const fwSections = buildFrameworkSections(siteAnyOf);
+  // Build all framework components. Loaders first: the commerce SEO sections'
+  // `jsonLD` data-source picker references the loader union, and that union must
+  // include the site's OWN loaders. The runtime registry (loaderRegistry) is
+  // empty at generation time, so `buildLoaderDefinitions` alone yields just
+  // `Resolvable` — merge in the site's own loaders so loader-backed pickers have
+  // real options in the baked meta, not only at runtime.
+  //
+  // Seed from the site's loader UNION (`schema.root.loaders.anyOf`), NOT
+  // `manifest.blocks.loaders`: the generator keeps `@ignore`d loaders in the
+  // manifest (they still need a def) while withholding them from the union so
+  // they can't be picked — reading the manifest would resurrect them. This
+  // source is also already `{ $ref }`-shaped and only points at defs that exist
+  // (no dangling refs).
+  //
+  // TODO: `root.matchers`/`root.actions` have the same empty-union-at-gen-time
+  // gap; only loaders are merged here (commerce SEO scope). Generalize if a
+  // matcher/action picker ever needs baked options.
+  const loaders = buildLoaderDefinitions();
+  const siteLoaderRefs = (siteMeta.schema?.root?.loaders?.anyOf ?? []).filter(
+    (ref: any): ref is { $ref: string } => Boolean(ref) && typeof ref.$ref === "string",
+  );
+  const seenLoaderRefs = new Set<string>(loaders.loaderAnyOf.map((r: any) => r.$ref));
+  const loaderUnion = [
+    ...loaders.loaderAnyOf,
+    ...siteLoaderRefs.filter((r) => !seenLoaderRefs.has(r.$ref)),
+  ];
+
+  const fwSections = buildFrameworkSections(siteAnyOf, loaderUnion);
   const fullSectionAnyOf = [...siteAnyOf, ...fwSections.extraAnyOf];
   const page = buildPageSchema(fullSectionAnyOf);
-  const loaders = buildLoaderDefinitions();
   const actions = buildActionDefinitions();
   const matchers = buildMatcherDefinitions();
 
@@ -1171,7 +1210,7 @@ export function composeMeta(siteMeta: MetaResponse, options?: ComposeMetaOptions
         ...(siteMeta.schema?.root || {}),
         sections: { anyOf: fullSectionAnyOf },
         pages: { anyOf: page.rootAnyOf },
-        loaders: { anyOf: loaders.loaderAnyOf },
+        loaders: { anyOf: loaderUnion },
         matchers: { anyOf: matchers.matcherAnyOf },
       },
     },

package/src/cms/sectionMixins.test.ts

@@ -17,7 +17,8 @@ import {
 // request must opt in by setting this flag — and `compose` must propagate
 // it whenever any input has it.
 const isRequestDependent = (fn: unknown): boolean =>
-  typeof fn === "function" && (fn as { __requestDependent?: boolean }).__requestDependent === true;
+  typeof fn === "function" &&
+  (fn as { __requestDependent?: boolean }).__requestDependent === true;
 
 const makeReq = (url = "https://store.example/foo?q=hello") =>
   new Request(url, { headers: { "user-agent": "vitest" } });
@@ -86,10 +87,12 @@ describe("withSectionLoader", () => {
 
   it("composes alongside mixins: mixins run first, then the section loader sees the enriched props", async () => {
     const seen: Array<Record<string, unknown>> = [];
-    const sectionLoader = vi.fn(async (props: Record<string, unknown>) => {
-      seen.push({ ...props });
-      return { ...props, sectionLoaderRan: true };
-    });
+    const sectionLoader = vi.fn(
+      async (props: Record<string, unknown>) => {
+        seen.push({ ...props });
+        return { ...props, sectionLoaderRan: true };
+      },
+    );
 
     const composed = compose(
       withSearchParam(),
@@ -151,14 +154,7 @@ describe("request-dependent tagging (#206)", () => {
   });
 
   it("compose does NOT set the flag when no input is request-dependent", () => {
-    expect(
-      isRequestDependent(
-        compose(
-          async (p) => p,
-          async (p) => p,
-        ),
-      ),
-    ).toBe(false);
+    expect(isRequestDependent(compose(async (p) => p, async (p) => p))).toBe(false);
   });
 
   it("empty compose() is not request-dependent", () => {

package/src/cms/sectionMixins.ts

@@ -135,7 +135,9 @@ export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
  * });
  * ```
  */
-export function withSectionLoader(modImport: () => Promise<unknown>): SectionLoaderFn {
+export function withSectionLoader(
+  modImport: () => Promise<unknown>,
+): SectionLoaderFn {
   return async (props, req, ctx) => {
     const mod = (await modImport()) as { loader?: unknown } | undefined;
     const loader = mod?.loader;