@decocms/blocks 7.28.0-beta.0 → 7.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.28.0-beta.0",
+  "version": "7.28.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/index.ts

@@ -12,16 +12,6 @@ export {
   revisionKey,
   snapshotKey,
 } from "./blockSource";
-export type { DraftPointer, ResolveDraftOptions } from "./draftSource";
-export {
-  buildDraftOrigin,
-  clearDraftCache,
-  getRequestDraftOverride,
-  isDraftPreviewEnabled,
-  parseDraftPointer,
-  resolveDraftDecofile,
-  setDraftOverrideGetter,
-} from "./draftSource";
 export type { DecoPage, Resolvable } from "./loader";
 export {
   findPageByPath,
@@ -70,6 +60,7 @@ export {
   getAsyncRenderingConfig,
   getDeferredRawProps,
   isBot,
+  isEagerRequest,
   isSeoSection,
   onBeforeResolve,
   reExtractRawProps,
@@ -92,6 +83,8 @@ export {
   unregisterCommerceLoader,
   WELL_KNOWN_TYPES,
 } from "./resolve";
+export type { SectionLoaderContext } from "./sectionLoaderContext";
+export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export type {
   ActionConfig,
   AppSchemas,
@@ -113,8 +106,6 @@ export {
   registerMatcherSchema,
   registerMatcherSchemas,
 } from "./schema";
-export type { SectionLoaderContext } from "./sectionLoaderContext";
-export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export type { SectionLoaderFn } from "./sectionLoaders";
 export {
   getDegradedSections,

package/src/cms/loader.ts

@@ -1,6 +1,5 @@
 import * as asyncHooks from "node:async_hooks";
 import { djb2Hex } from "../sdk/djb2";
-import { getRequestDraftOverride } from "./draftSource";
 
 export type Resolvable = {
   __resolveType?: string;
@@ -87,8 +86,7 @@ export function setBlocks(blocks: Record<string, unknown>) {
 
 /**
  * Load the current blocks. If running inside a `withBlocksOverride` scope
- * (admin preview) or a request carrying a draft-preview override, that
- * override is merged on top of the base blocks.
+ * (admin preview), the override is merged on top of the base blocks.
  */
 export function loadBlocks(): Record<string, unknown> {
   // Re-sync from globalThis in case setBlocks was called in another module instance
@@ -97,10 +95,7 @@ export function loadBlocks(): Record<string, unknown> {
     revision = G.__deco.revision ?? null;
   }
 
-  // `withBlocksOverride` (an explicit admin render of a specific payload) wins
-  // over an ambient draft: the caller named the exact blocks to render, so a
-  // draft pointer on the same request must not silently replace them.
-  const override = blocksOverrideStorage.getStore() ?? getRequestDraftOverride();
+  const override = blocksOverrideStorage.getStore();
   if (override) {
     const merged = { ...blockData };
     for (const [key, value] of Object.entries(override)) {
@@ -208,14 +203,12 @@ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
 // same regardless of whether @types/node has its own `URLPattern` global or
 // not — there's nothing for a local declaration to collide with.
 type MatchPatternResult = {
-  pathname: { groups: Record<string, string | undefined> };
+	pathname: { groups: Record<string, string | undefined> };
 };
 declare const URLPattern: {
-  new (init: {
-    pathname: string;
-  }): {
-    exec(input: { pathname: string }): MatchPatternResult | null;
-  };
+	new (init: { pathname: string }): {
+		exec(input: { pathname: string }): MatchPatternResult | null;
+	};
 };
 
 /**
@@ -238,7 +231,10 @@ declare const URLPattern: {
  * `URLPattern` is native in browsers, workerd, Deno, and Node >= 24 (this
  * package's `engines` floor). Node 22 and older lack it.
  */
-export function matchPath(pattern: string, urlPath: string): Record<string, string> | null {
+export function matchPath(
+  pattern: string,
+  urlPath: string,
+): Record<string, string> | null {
   if (typeof URLPattern === "undefined") {
     throw new Error(
       "@decocms/blocks: this runtime has no URLPattern Web API, so CMS page " +

package/src/cms/resolve.test.ts

@@ -623,6 +623,104 @@ describe("resolvePageSeoBlock — bot-aware commerce SEO", () => {
   });
 });
 
+describe("resolvePageSeoBlock — per-section ignoreStructuredData drives the fetch-skip", () => {
+  const KEY = "site/loaders/__test/plpSeoLoader";
+  const HUMAN_UA =
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36";
+  const BOT_UA = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
+
+  // PLP toggle lives under `configJsonLD`; PDP toggle is top-level.
+  const plpBlock = {
+    __resolveType: "commerce/sections/Seo/SeoPLPV2.tsx",
+    title: "Escolar",
+    jsonLD: { __resolveType: KEY },
+    configJsonLD: { ignoreStructuredData: true },
+  };
+  const pdpBlock = {
+    __resolveType: "commerce/sections/Seo/SeoPDPV2.tsx",
+    title: "Produto",
+    jsonLD: { __resolveType: KEY },
+    ignoreStructuredData: true,
+  };
+
+  const rctx = (userAgent?: string) =>
+    ({
+      matcherCtx: { userAgent, url: "https://store.com/escolar", path: "/escolar" },
+      memo: new Map(),
+      depth: 0,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }) as any;
+
+  beforeEach(() => {
+    clearCommerceLoaders();
+    // The per-section toggle is the PRIMARY lever — it must work with the
+    // site-wide botAwareSeo shortcut OFF.
+    setAsyncRenderingConfig({ botAwareSeo: false });
+  });
+  afterEach(() => {
+    clearCommerceLoaders();
+    setAsyncRenderingConfig({ botAwareSeo: false });
+  });
+
+  it("humans: toggle skips the commerce loader (PLP configJsonLD)", async () => {
+    let calls = 0;
+    registerCommerceLoader(KEY, async () => {
+      calls++;
+      return { seo: { title: "Rich SEO title" }, products: [{ id: 1 }] };
+    });
+
+    const res = await resolvePageSeoBlock(plpBlock, rctx(HUMAN_UA));
+
+    expect(calls).toBe(0); // no product fetch for humans
+    expect(res?.props).toHaveProperty("title", "Escolar");
+    expect(res?.props).not.toHaveProperty("jsonLD");
+  });
+
+  it("bots: toggle still resolves the commerce loader (PLP configJsonLD)", async () => {
+    let calls = 0;
+    registerCommerceLoader(KEY, async () => {
+      calls++;
+      return { seo: { title: "Rich SEO title" }, products: [{ id: 1 }] };
+    });
+
+    const res = await resolvePageSeoBlock(plpBlock, rctx(BOT_UA));
+
+    expect(calls).toBe(1);
+    expect(res?.props?.jsonLD).toMatchObject({ seo: { title: "Rich SEO title" } });
+  });
+
+  it("humans: top-level toggle skips the commerce loader (PDP)", async () => {
+    let calls = 0;
+    registerCommerceLoader(KEY, async () => {
+      calls++;
+      return { seo: { title: "Rich SEO title" }, product: { id: 1 } };
+    });
+
+    const res = await resolvePageSeoBlock(pdpBlock, rctx(HUMAN_UA));
+
+    expect(calls).toBe(0);
+    expect(res?.props).not.toHaveProperty("jsonLD");
+  });
+
+  it("toggle OFF: humans keep the full SEO even with botAwareSeo off (no regression)", async () => {
+    let calls = 0;
+    registerCommerceLoader(KEY, async () => {
+      calls++;
+      return { seo: { title: "Rich SEO title" }, products: [{ id: 1 }] };
+    });
+
+    const noToggle = {
+      __resolveType: "commerce/sections/Seo/SeoPLPV2.tsx",
+      title: "Escolar",
+      jsonLD: { __resolveType: KEY },
+    };
+    const res = await resolvePageSeoBlock(noToggle, rctx(HUMAN_UA));
+
+    expect(calls).toBe(1); // no toggle + no global flag → resolve for everyone
+    expect(res?.props?.jsonLD).toMatchObject({ seo: { title: "Rich SEO title" } });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // resolveDecoPage — #277 client-side navigation disables deferral
 // ---------------------------------------------------------------------------
@@ -648,6 +746,20 @@ describe("extractSeoFromProps — commerce jsonLD structured data", () => {
     ...overrides,
   });
 
+  const pdp = (overrides: Record<string, unknown> = {}) => ({
+    "@type": "ProductDetailsPage",
+    breadcrumbList: {
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", position: 1, item: "https://x.com/a" },
+        { "@type": "ListItem", position: 2, item: "https://x.com/a/p" },
+      ],
+    },
+    product: { "@type": "Product", name: "P1", image: [{ url: "https://x.com/p.jpg" }] },
+    seo: { title: "PDP Title", description: "PDP Desc" },
+    ...overrides,
+  });
+
   it("derives title/description/canonical and emits the ItemList JSON-LD (PLP)", () => {
     // The casaevideo.com.br/eletroportateis regression: a page.seo pointing at
     // commerce/sections/Seo/SeoPLPV2.tsx resolved its jsonLD but emitted no
@@ -695,7 +807,7 @@ describe("extractSeoFromProps — commerce jsonLD structured data", () => {
     expect(seo.jsonLDs).toHaveLength(1);
   });
 
-  it("omits structured data when ignoreStructuredData is set", () => {
+  it("omits structured data for humans when ignoreStructuredData is set", () => {
     const seo = extractSeoFromProps({
       jsonLD: plp(),
       configJsonLD: { ignoreStructuredData: true },
@@ -705,6 +817,35 @@ describe("extractSeoFromProps — commerce jsonLD structured data", () => {
     expect(seo.title).toBe("PLP Title");
   });
 
+  it("keeps structured data for bots even when ignoreStructuredData is set", () => {
+    // Bot-aware: the toggle suppresses JSON-LD for humans only. Crawlers (and the
+    // `?__deco_ssr=1` audit override, both surfaced via isEager) still get it.
+    const seo = extractSeoFromProps(
+      { jsonLD: plp(), configJsonLD: { ignoreStructuredData: true } },
+      { isEager: true },
+    );
+    expect(seo.jsonLDs).toHaveLength(1);
+    expect(seo.title).toBe("PLP Title");
+  });
+
+  it("omits structured data for bots too when the listing is empty", () => {
+    // ignoreStructuredData is bot-aware, but an empty listing contributes no
+    // ItemList regardless of bot status.
+    const seo = extractSeoFromProps(
+      { jsonLD: plp({ products: [] }), configJsonLD: { ignoreStructuredData: true } },
+      { isEager: true },
+    );
+    expect(seo.jsonLDs).toBeUndefined();
+  });
+
+  it("keeps PDP structured data for bots with top-level ignoreStructuredData", () => {
+    const seo = extractSeoFromProps(
+      { jsonLD: pdp(), ignoreStructuredData: true },
+      { isEager: true },
+    );
+    expect(seo.jsonLDs).toHaveLength(1);
+  });
+
   it("marks an empty listing noIndexing and emits no ItemList", () => {
     const seo = extractSeoFromProps({ jsonLD: plp({ products: [] }) });
     expect(seo.noIndexing).toBe(true);

package/src/cms/resolve.ts

@@ -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;
@@ -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)
@@ -1747,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;
@@ -1781,13 +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, {
@@ -1801,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;
@@ -1816,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;
 }
 
@@ -1825,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] = {
@@ -1109,11 +1120,36 @@ export function composeMeta(
 
   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();
 
@@ -1174,7 +1210,7 @@ export function composeMeta(
         ...(siteMeta.schema?.root || {}),
         sections: { anyOf: fullSectionAnyOf },
         pages: { anyOf: page.rootAnyOf },
-        loaders: { anyOf: loaders.loaderAnyOf },
+        loaders: { anyOf: loaderUnion },
         matchers: { anyOf: matchers.matcherAnyOf },
       },
     },

package/src/cms/draftSource.test.ts

@@ -1,201 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-
-import {
-  buildDraftOrigin,
-  clearDraftCache,
-  isDraftPreviewEnabled,
-  parseDraftPointer,
-  resolveDraftDecofile,
-} from "./draftSource";
-
-const ENV_ON = {
-  DECO_DRAFT_PREVIEW: "1",
-  DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
-};
-
-function jsonResponse(body: unknown, init?: ResponseInit): Response {
-  return new Response(JSON.stringify(body), {
-    status: 200,
-    headers: { "content-type": "application/json" },
-    ...init,
-  });
-}
-
-beforeEach(() => {
-  clearDraftCache();
-});
-
-describe("parseDraftPointer", () => {
-  it("parses handle@version", () => {
-    expect(parseDraftPointer("gimenes-abc123@ff00")).toEqual({
-      handle: "gimenes-abc123",
-      version: "ff00",
-    });
-  });
-
-  it("rejects more than one @", () => {
-    // A naive split("@") accepts this and silently uses the first two
-    // segments — the exact hole found while spiking the fetch path.
-    expect(parseDraftPointer("a@b@c")).toBeNull();
-  });
-
-  it("rejects a handle that could escape the authority", () => {
-    expect(parseDraftPointer("evil.com/x@v1")).toBeNull();
-    expect(parseDraftPointer("user:pw@v1")).toBeNull();
-    expect(parseDraftPointer("a/../b@v1")).toBeNull();
-    expect(parseDraftPointer(".leading-dot@v1")).toBeNull();
-  });
-
-  it("rejects empty halves and missing input", () => {
-    expect(parseDraftPointer("@v1")).toBeNull();
-    expect(parseDraftPointer("handle@")).toBeNull();
-    expect(parseDraftPointer("handle")).toBeNull();
-    expect(parseDraftPointer(null)).toBeNull();
-    expect(parseDraftPointer("")).toBeNull();
-  });
-});
-
-describe("buildDraftOrigin", () => {
-  it("builds https from the configured suffix", () => {
-    expect(buildDraftOrigin("abc", [".preview-studio.decocms.com"])).toBe(
-      "https://abc.preview-studio.decocms.com",
-    );
-  });
-
-  it("uses http for a localhost suffix (local e2e)", () => {
-    expect(buildDraftOrigin("abc", [".localhost:3200"])).toBe("http://abc.localhost:3200");
-  });
-
-  it("returns null with no configured suffix — never guesses an origin", () => {
-    expect(buildDraftOrigin("abc", [])).toBeNull();
-  });
-});
-
-describe("isDraftPreviewEnabled", () => {
-  it("needs both the flag and a suffix", () => {
-    expect(isDraftPreviewEnabled(ENV_ON)).toBe(true);
-    expect(isDraftPreviewEnabled({ DECO_DRAFT_PREVIEW: "1" })).toBe(false);
-    expect(
-      isDraftPreviewEnabled({
-        DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
-      }),
-    ).toBe(false);
-    expect(isDraftPreviewEnabled({})).toBe(false);
-  });
-});
-
-describe("resolveDraftDecofile", () => {
-  it("fetches the sandbox decofile and returns it", async () => {
-    const calls: string[] = [];
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async (url: string) => {
-        calls.push(String(url));
-        return jsonResponse({ "pages-home": { title: "draft" } });
-      }) as unknown as typeof fetch,
-    });
-
-    expect(blocks).toEqual({ "pages-home": { title: "draft" } });
-    expect(calls).toEqual(["https://abc.preview-studio.decocms.com/_sandbox/decofile"]);
-  });
-
-  it("is inert unless explicitly enabled — no fetch at all", async () => {
-    let called = false;
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: { DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com" },
-      fetchImpl: (async () => {
-        called = true;
-        return jsonResponse({});
-      }) as unknown as typeof fetch,
-    });
-
-    expect(blocks).toBeNull();
-    expect(called).toBe(false);
-  });
-
-  it("caches by version — one fetch per version, not per request", async () => {
-    let fetches = 0;
-    const fetchImpl = (async () => {
-      fetches++;
-      return jsonResponse({ n: fetches });
-    }) as unknown as typeof fetch;
-
-    const a = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
-    const b = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(1);
-    expect(b).toBe(a);
-
-    await resolveDraftDecofile({ pointer: "abc@v2", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(2);
-  });
-
-  it("bounds the cache so multi-MB decofiles can't accumulate", async () => {
-    let fetches = 0;
-    const fetchImpl = (async () => {
-      fetches++;
-      return jsonResponse({ n: fetches });
-    }) as unknown as typeof fetch;
-
-    for (const v of ["v1", "v2", "v3", "v4"]) {
-      await resolveDraftDecofile({ pointer: `abc@${v}`, env: ENV_ON, fetchImpl });
-    }
-    expect(fetches).toBe(4);
-
-    // v1 was evicted (cap is 3), so it must re-fetch rather than serve stale.
-    await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(5);
-
-    // v4 is still resident.
-    await resolveDraftDecofile({ pointer: "abc@v4", env: ENV_ON, fetchImpl });
-    expect(fetches).toBe(5);
-  });
-
-  it("degrades to published on a malformed pointer, without fetching", async () => {
-    let called = false;
-    const blocks = await resolveDraftDecofile({
-      pointer: "a@b@c",
-      env: ENV_ON,
-      fetchImpl: (async () => {
-        called = true;
-        return jsonResponse({});
-      }) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-    expect(called).toBe(false);
-  });
-
-  it("degrades to published on a non-2xx sandbox", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () => new Response("nope", { status: 404 })) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-  });
-
-  it("degrades to published when the sandbox is unreachable", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () => {
-        throw new Error("ECONNREFUSED");
-      }) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-  });
-
-  it("degrades to published on an unparseable body", async () => {
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc@v1",
-      env: ENV_ON,
-      fetchImpl: (async () =>
-        new Response("<html>not json</html>", {
-          status: 200,
-          headers: { "content-type": "text/html" },
-        })) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
-  });
-});

package/src/cms/draftSource.ts

@@ -1,197 +0,0 @@
-/**
- * Draft preview — pull-based decofile override.
- *
- * A Studio sandbox serves the working-tree draft at
- * `GET <origin>/_sandbox/decofile`; a production site pulls it and renders its
- * own real pages against it. This replaces pushing the decofile into a POST
- * body, which only deco's own runtime honours — Next.js and most frameworks
- * render on GET only.
- *
- * This module is the framework-agnostic half: pointer parsing, origin
- * construction, fetching, and version caching. Binding a resolved draft to a
- * request is framework-specific (see `@decocms/nextjs`'s draft wiring) and
- * reaches this module through {@link setDraftOverrideGetter} — the same
- * dependency-injection shape as `setFastDeployKVGetter`, so `blocks` keeps its
- * zero-dependency direction.
- *
- * Inert unless BOTH `DECO_DRAFT_PREVIEW=1` and `DECO_SANDBOX_ORIGIN_SUFFIXES`
- * are set, mirroring Fast Deploy's opt-in: upgrading the package must never be
- * enough to start fetching from the network and rendering unpublished content.
- */
-
-/** A parsed `<handle>@<version>` draft pointer. */
-export interface DraftPointer {
-  /** Sandbox handle — the subdomain under a configured origin suffix. */
-  handle: string;
-  /** Content version (the daemon's ETag). Immutable, so safe to cache on. */
-  version: string;
-}
-
-/**
- * Sandbox handles are `[a-z0-9-]`, always leading with an alphanumeric.
- *
- * Validated BEFORE the handle is interpolated into an authority, so it cannot
- * smuggle `/`, `@`, `:` or userinfo into the URL and redirect the fetch at some
- * other host.
- */
-const HANDLE_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]*$/;
-
-/**
- * Parse `<handle>@<version>`.
- *
- * Requires EXACTLY one `@`: a naive `split("@")` accepts `a@b@c` and silently
- * uses the first two segments, which is how a malformed pointer sneaks past
- * validation. Returns null on anything unexpected — callers fall back to
- * published content.
- */
-export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
-  if (!raw) return null;
-  const parts = raw.split("@");
-  if (parts.length !== 2) return null;
-  const [handle, version] = parts;
-  if (!handle || !version) return null;
-  if (!HANDLE_RE.test(handle)) return null;
-  return { handle, version };
-}
-
-/** Configured suffixes, e.g. `.preview-studio.decocms.com,.localhost:3200`. */
-function readSuffixes(env: Record<string, string | undefined>): string[] {
-  return (env.DECO_SANDBOX_ORIGIN_SUFFIXES ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-
-/**
- * Build the sandbox origin for a handle.
- *
- * The origin comes from CONFIGURED suffixes, never from caller input, so there
- * is no SSRF surface to defend and no allowlist to keep correct. A `localhost`
- * suffix (local e2e) speaks http; everything else is https.
- */
-export function buildDraftOrigin(handle: string, suffixes: string[]): string | null {
-  const suffix = suffixes[0];
-  if (!suffix) return null;
-  if (!HANDLE_RE.test(handle)) return null;
-  const scheme = suffix.includes("localhost") ? "http" : "https";
-  return `${scheme}://${handle}${suffix}`;
-}
-
-/**
- * Version cache.
- *
- * Bounded on purpose: a decofile is routinely multi-megabyte, so an unbounded
- * map keyed by version would grow with every save until the process died.
- * Keyed by version (content-addressed), so a hit is always correct.
- */
-const MAX_CACHED_VERSIONS = 3;
-const byVersion = new Map<string, Record<string, unknown>>();
-
-function cacheDraft(version: string, blocks: Record<string, unknown>): void {
-  // Re-insert to make this the most recently used key.
-  byVersion.delete(version);
-  byVersion.set(version, blocks);
-  while (byVersion.size > MAX_CACHED_VERSIONS) {
-    const oldest = byVersion.keys().next().value;
-    if (oldest === undefined) break;
-    byVersion.delete(oldest);
-  }
-}
-
-/** Test seam — drops every cached version. */
-export function clearDraftCache(): void {
-  byVersion.clear();
-}
-
-export interface ResolveDraftOptions {
-  /** Raw `<handle>@<version>` pointer from the request. */
-  pointer: string | null | undefined;
-  /** Defaults to `process.env`. */
-  env?: Record<string, string | undefined>;
-  /** Defaults to global `fetch`. Injected in tests. */
-  fetchImpl?: typeof fetch;
-}
-
-/**
- * Resolve a draft pointer to a decofile, or null to render published content.
- *
- * Null on every failure path — disabled, malformed pointer, unreachable
- * sandbox, non-2xx — because a draft that cannot be resolved must degrade to
- * published rather than break the page. Callers that need to *tell the user*
- * the draft failed should check {@link isDraftPreviewEnabled} and surface it
- * themselves; silently showing published content while the user believes they
- * are looking at a draft is the failure mode worth avoiding.
- */
-export async function resolveDraftDecofile(
-  options: ResolveDraftOptions,
-): Promise<Record<string, unknown> | null> {
-  const env =
-    options.env ??
-    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
-    {};
-  if (env.DECO_DRAFT_PREVIEW !== "1") return null;
-
-  const parsed = parseDraftPointer(options.pointer);
-  if (!parsed) return null;
-
-  const cached = byVersion.get(parsed.version);
-  if (cached) return cached;
-
-  const origin = buildDraftOrigin(parsed.handle, readSuffixes(env));
-  if (!origin) return null;
-
-  const doFetch = options.fetchImpl ?? fetch;
-  let res: Response;
-  try {
-    res = await doFetch(`${origin}/_sandbox/decofile`, { cache: "no-store" });
-  } catch {
-    return null;
-  }
-  if (!res.ok) return null;
-
-  let blocks: Record<string, unknown>;
-  try {
-    blocks = (await res.json()) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-
-  cacheDraft(parsed.version, blocks);
-  return blocks;
-}
-
-/** True when the feature is switched on and configured. Inert otherwise. */
-export function isDraftPreviewEnabled(env?: Record<string, string | undefined>): boolean {
-  const e =
-    env ??
-    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
-    {};
-  return e.DECO_DRAFT_PREVIEW === "1" && readSuffixes(e).length > 0;
-}
-
-// ---------------------------------------------------------------------------
-// Request binding (dependency-injected by the framework binding)
-// ---------------------------------------------------------------------------
-
-type DraftOverrideGetter = () => Record<string, unknown> | null | undefined;
-
-let getDraftOverride: DraftOverrideGetter = () => undefined;
-
-/**
- * Inject the request-scoped draft getter.
- *
- * Binding a value to "the current request" is framework-specific and `blocks`
- * must not know about any framework: `@decocms/nextjs` backs this with React
- * `cache()` (App Router has no AsyncLocalStorage request scope of its own —
- * `RequestContext.run` is never entered there). Bindings that do have an ALS
- * request scope can back it with that instead. Never called → returns
- * undefined → `loadBlocks()` behaves exactly as before.
- */
-export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
-  getDraftOverride = getter;
-}
-
-/** The current request's draft blocks, if a binding registered one. */
-export function getRequestDraftOverride(): Record<string, unknown> | null | undefined {
-  return getDraftOverride();
-}