@decocms/blocks 7.0.0

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@decocms/blocks",
+  "version": "7.0.0",
+  "type": "module",
+  "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./cms": "./src/cms/index.ts",
+    "./cms/loadDecofileDirectory": "./src/cms/loadDecofileDirectory.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./types": "./src/types/index.ts",
+    "./types/widgets": "./src/types/widgets.ts",
+    "./setup": "./src/setup.ts",
+    "./matchers/builtins": "./src/matchers/builtins.ts",
+    "./matchers/posthog": "./src/matchers/posthog.ts",
+    "./matchers/override": "./src/matchers/override.ts",
+    "./middleware": "./src/middleware/index.ts",
+    "./middleware/healthMetrics": "./src/middleware/healthMetrics.ts",
+    "./middleware/hydrationContext": "./src/middleware/hydrationContext.ts",
+    "./middleware/observability": "./src/middleware/observability.ts",
+    "./middleware/validateSection": "./src/middleware/validateSection.ts",
+    "./sdk": "./src/sdk/index.ts",
+    "./sdk/abTesting": "./src/sdk/abTesting.ts",
+    "./sdk/analytics": "./src/sdk/analytics.ts",
+    "./sdk/cachedLoader": "./src/sdk/cachedLoader.ts",
+    "./sdk/cacheHeaders": "./src/sdk/cacheHeaders.ts",
+    "./sdk/clx": "./src/sdk/clx.ts",
+    "./sdk/cn": "./src/sdk/cn.ts",
+    "./sdk/composite": "./src/sdk/composite.ts",
+    "./sdk/cookie": "./src/sdk/cookie.ts",
+    "./sdk/crypto": "./src/sdk/crypto.ts",
+    "./sdk/csp": "./src/sdk/csp.ts",
+    "./sdk/djb2": "./src/sdk/djb2.ts",
+    "./sdk/encoding": "./src/sdk/encoding.ts",
+    "./sdk/env": "./src/sdk/env.ts",
+    "./sdk/http": "./src/sdk/http.ts",
+    "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",
+    "./sdk/invoke": "./src/sdk/invoke.ts",
+    "./sdk/logger": "./src/sdk/logger.ts",
+    "./sdk/mergeCacheControl": "./src/sdk/mergeCacheControl.ts",
+    "./sdk/normalizeUrls": "./src/sdk/normalizeUrls.ts",
+    "./sdk/observability": "./src/sdk/observability.ts",
+    "./sdk/otel": "./src/sdk/otel.ts",
+    "./sdk/otelAdapters": "./src/sdk/otelAdapters.ts",
+    "./sdk/otelAdapters/clickhouseCollector": "./src/sdk/otelAdapters/clickhouseCollector.ts",
+    "./sdk/otelHttpLog": "./src/sdk/otelHttpLog.ts",
+    "./sdk/otelHttpMeter": "./src/sdk/otelHttpMeter.ts",
+    "./sdk/otelHttpTracer": "./src/sdk/otelHttpTracer.ts",
+    "./sdk/redirects": "./src/sdk/redirects.ts",
+    "./sdk/requestContext": "./src/sdk/requestContext.ts",
+    "./sdk/requestContextStorage": {
+      "workerd": "./src/sdk/requestContextStorage.ts",
+      "node": "./src/sdk/requestContextStorage.ts",
+      "browser": "./src/sdk/requestContextStorage.browser.ts",
+      "default": "./src/sdk/requestContextStorage.ts"
+    },
+    "./sdk/retry": "./src/sdk/retry.ts",
+    "./sdk/serverTimings": "./src/sdk/serverTimings.ts",
+    "./sdk/signal": "./src/sdk/signal.ts",
+    "./sdk/sitemap": "./src/sdk/sitemap.ts",
+    "./sdk/urlUtils": "./src/sdk/urlUtils.ts",
+    "./sdk/useDevice": "./src/sdk/useDevice.ts",
+    "./sdk/useId": "./src/sdk/useId.ts",
+    "./sdk/useScript": "./src/sdk/useScript.ts",
+    "./sdk/useSuggestions": "./src/sdk/useSuggestions.ts",
+    "./sdk/wrapCaughtErrors": "./src/sdk/wrapCaughtErrors.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/blocks/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@tanstack/store": "^0.9.1",
+    "clsx": "^2.1.1",
+    "fast-json-patch": "^3.1.0",
+    "tailwind-merge": "^3.3.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/cms/applySectionConventions.ts

@@ -0,0 +1,128 @@
+/**
+ * Applies convention-based section metadata generated by generate-sections.ts.
+ *
+ * Reads the generated sectionMeta/syncComponents/loadingFallbacks and calls
+ * the appropriate registration functions — replacing manual calls to
+ * registerSectionsSync, setAsyncRenderingConfig, registerCacheableSections,
+ * registerLayoutSections, registerSeoSections, and registerSection.
+ */
+import {
+  registerSection,
+  registerSectionsSync,
+} from "./registry";
+import {
+  type CacheableSectionInput,
+  registerCacheableSections,
+  registerLayoutSections,
+} from "./sectionLoaders";
+import {
+  type AsyncRenderingConfig,
+  registerEagerSections,
+  registerNeverDeferSections,
+  registerSeoSections,
+  setAsyncRenderingConfig,
+  getAsyncRenderingConfig,
+} from "./resolve";
+
+export interface SectionMetaEntry {
+  eager?: boolean;
+  neverDefer?: boolean;
+  cache?: string;
+  layout?: boolean;
+  sync?: boolean;
+  clientOnly?: boolean;
+  seo?: boolean;
+  hasLoadingFallback?: boolean;
+}
+
+export interface ApplySectionConventionsInput {
+  /** Section metadata map from sections.gen.ts */
+  meta: Record<string, SectionMetaEntry>;
+  /** Sync-imported section modules from sections.gen.ts */
+  syncComponents?: Record<string, any>;
+  /** LoadingFallback components from sections.gen.ts */
+  loadingFallbacks?: Record<string, React.ComponentType<any>>;
+  /** Lazy section loaders from import.meta.glob (used for clientOnly/loadingFallback registration) */
+  sectionGlob?: Record<string, () => Promise<any>>;
+}
+
+export function applySectionConventions(input: ApplySectionConventionsInput): void {
+  const { meta, syncComponents, loadingFallbacks, sectionGlob } = input;
+
+  const eagerSections: string[] = [];
+  const neverDeferSections: string[] = [];
+  const layoutSections: string[] = [];
+  const seoSections: string[] = [];
+  const cacheableSections: Record<string, CacheableSectionInput> = {};
+
+  for (const [key, entry] of Object.entries(meta)) {
+    if (entry.eager) eagerSections.push(key);
+    if (entry.neverDefer) neverDeferSections.push(key);
+    if (entry.layout) layoutSections.push(key);
+    if (entry.seo) seoSections.push(key);
+    if (entry.cache) cacheableSections[key] = entry.cache as CacheableSectionInput;
+
+    if (entry.clientOnly && sectionGlob) {
+      const globKey = sectionGlobKey(key, sectionGlob);
+      if (globKey) {
+        registerSection(key, sectionGlob[globKey] as any, { clientOnly: true });
+      }
+    }
+
+    if (entry.hasLoadingFallback && loadingFallbacks?.[key] && sectionGlob) {
+      const globKey = sectionGlobKey(key, sectionGlob);
+      if (globKey) {
+        registerSection(key, sectionGlob[globKey] as any, {
+          loadingFallback: loadingFallbacks[key],
+        });
+      }
+    }
+  }
+
+  if (syncComponents && Object.keys(syncComponents).length > 0) {
+    registerSectionsSync(syncComponents);
+  }
+
+  if (eagerSections.length > 0) {
+    registerEagerSections(eagerSections);
+  }
+
+  if (neverDeferSections.length > 0) {
+    registerNeverDeferSections(neverDeferSections);
+  }
+
+  // Always initialize asyncConfig so CMS Lazy deferral (`respectCmsLazy`) is
+  // active — this is what makes the admin ⚡ toggle the source of truth. Without
+  // it, asyncConfig stays null, `useAsync` is false in resolveDecoPage, and
+  // even editor-marked ⚡ sections render eagerly. (The default foldThreshold is
+  // Infinity, so position-based deferral stays off unless a site opts in.)
+  const existing: Partial<AsyncRenderingConfig> =
+    getAsyncRenderingConfig() ?? {};
+  setAsyncRenderingConfig({
+    ...existing,
+    alwaysEager: [...(existing.alwaysEager ?? []), ...eagerSections],
+  });
+
+  if (layoutSections.length > 0) {
+    registerLayoutSections(layoutSections);
+  }
+
+  if (seoSections.length > 0) {
+    registerSeoSections(seoSections);
+  }
+
+  if (Object.keys(cacheableSections).length > 0) {
+    registerCacheableSections(cacheableSections);
+  }
+}
+
+function sectionGlobKey(
+  sectionKey: string,
+  glob: Record<string, () => Promise<any>>,
+): string | null {
+  const relative = sectionKey.replace("site/sections/", "./sections/");
+  if (glob[relative]) return relative;
+  const withDot = sectionKey.replace("site/", "./");
+  if (glob[withDot]) return withDot;
+  return null;
+}

package/src/cms/blockSource.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  BundledBlockSource,
+  computeRevision,
+  KV_KEYS,
+  type KVNamespace,
+} from "./blockSource";
+import { djb2Hex } from "../sdk/djb2";
+
+describe("computeRevision", () => {
+  it("matches loader.ts computeRevision (djb2Hex of JSON.stringify)", () => {
+    const blocks = { Site: { name: "x" }, "pages-home": { path: "/" } };
+    expect(computeRevision(blocks)).toBe(djb2Hex(JSON.stringify(blocks)));
+  });
+
+  it("is stable for the same input and differs on change", () => {
+    const a = { a: 1 };
+    const b = { a: 2 };
+    expect(computeRevision(a)).toBe(computeRevision(a));
+    expect(computeRevision(a)).not.toBe(computeRevision(b));
+  });
+
+  it("hashes an empty decofile without throwing", () => {
+    expect(typeof computeRevision({})).toBe("string");
+  });
+});
+
+describe("BundledBlockSource", () => {
+  it("loadSnapshot resolves null (bundled is applied at startup, not here)", async () => {
+    const src = new BundledBlockSource();
+    await expect(src.loadSnapshot()).resolves.toBeNull();
+  });
+
+  it("getRevision resolves null", async () => {
+    const src = new BundledBlockSource();
+    await expect(src.getRevision()).resolves.toBeNull();
+  });
+});
+
+describe("KV_KEYS", () => {
+  it("exposes the snapshot and revision key contract", () => {
+    expect(KV_KEYS.SNAPSHOT).toBe("decofile:current");
+    expect(KV_KEYS.REVISION).toBe("index:revision");
+  });
+});
+
+describe("KVNamespace structural type", () => {
+  it("a plain Map-backed stub satisfies the interface", async () => {
+    const store = new Map<string, string>();
+    const kv: KVNamespace = {
+      get: (k) => Promise.resolve(store.get(k) ?? null),
+      put: (k, v) => {
+        store.set(k, v);
+        return Promise.resolve();
+      },
+      delete: (k) => {
+        store.delete(k);
+        return Promise.resolve();
+      },
+    };
+
+    await kv.put(KV_KEYS.REVISION, "abc");
+    await expect(kv.get(KV_KEYS.REVISION)).resolves.toBe("abc");
+    await kv.delete(KV_KEYS.REVISION);
+    await expect(kv.get(KV_KEYS.REVISION)).resolves.toBeNull();
+  });
+});

package/src/cms/blockSource.ts

@@ -0,0 +1,124 @@
+/**
+ * BlockSource — the runtime source of truth for the CMS decofile.
+ *
+ * A `BlockSource` asynchronously yields the *whole* decofile snapshot (the
+ * `Record<string, unknown>` blocks map) plus its revision hash. This is the
+ * "fast deploy" seam: the framework can hydrate the in-memory block map from a
+ * remote source (Cloudflare KV) on cold start and swap it on revision change,
+ * WITHOUT making the synchronous resolution hot path (`loadBlocks()` in
+ * `loader.ts`) async.
+ *
+ * Design note (whole-snapshot vs per-block): the resolver calls `loadBlocks()`
+ * synchronously in dozens of places (matchers, deferral checks, page lookup,
+ * SEO). Rather than threading `async` through all of that, a `BlockSource`
+ * loads the entire decofile once and the framework calls `setBlocks()` to swap
+ * the in-memory map. Per-request reads stay in-memory (zero added latency); KV
+ * is touched only on cold start and during the opportunistic revision poll.
+ *
+ * Mirrors the `DecofileProvider` pattern from the original deco-cx/deco Fresh
+ * runtime (`engine/decofile/provider.ts`), trimmed to what the snapshot-swap
+ * model needs.
+ */
+
+import { djb2Hex } from "../sdk/djb2";
+
+/** A fully-loaded decofile snapshot: the blocks map and its revision hash. */
+export interface BlockSnapshot {
+  /** The decofile — a flat map of block name → block JSON. */
+  blocks: Record<string, unknown>;
+  /** DJB2 hex revision computed over the blocks (see `computeRevision`). */
+  revision: string;
+}
+
+/**
+ * Source of the runtime decofile snapshot.
+ *
+ * Implementations:
+ * - `BundledBlockSource` — the build-time `blocks.gen` snapshot (fallback /
+ *   local dev). A no-op here because `setup.ts` already loads it via
+ *   `setBlocks()` at module init.
+ * - `KVBlockSource` (PR2) — reads `decofile:current` + `index:revision` from a
+ *   Cloudflare KV namespace.
+ */
+export interface BlockSource {
+  /**
+   * Load the full decofile snapshot. Returns `null` when this source has no
+   * snapshot to offer (e.g. KV key missing, or the bundled source which is
+   * already applied at startup) — the caller then keeps whatever blocks are
+   * currently in memory.
+   */
+  loadSnapshot(): Promise<BlockSnapshot | null>;
+
+  /**
+   * Cheap revision probe used for change detection during polling. Returns the
+   * current revision without transferring the full snapshot, or `null` when
+   * unavailable.
+   */
+  getRevision(): Promise<string | null>;
+}
+
+/**
+ * Compute the revision hash for a blocks map.
+ *
+ * MUST match `computeRevision` in `loader.ts` (DJB2 over the JSON string) so
+ * that a snapshot written to KV and the revision stored alongside it agree
+ * with the revision an isolate computes after `setBlocks()` — otherwise the
+ * poller would see a permanent mismatch and reload on every tick.
+ */
+export function computeRevision(blocks: Record<string, unknown>): string {
+  return djb2Hex(JSON.stringify(blocks));
+}
+
+/**
+ * Bundled (build-time) snapshot source.
+ *
+ * Intentionally a no-op `loadSnapshot()`: the bundled `blocks.gen` is applied
+ * by `createSiteSetup()` → `setBlocks()` at module load, before any request.
+ * This exists so callers can treat "bundled" uniformly through the
+ * `BlockSource` interface and so the composition layer (KV primary + bundled
+ * fallback) has a concrete fallback object.
+ */
+export class BundledBlockSource implements BlockSource {
+  loadSnapshot(): Promise<BlockSnapshot | null> {
+    return Promise.resolve(null);
+  }
+
+  getRevision(): Promise<string | null> {
+    return Promise.resolve(null);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Minimal Cloudflare KV type
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal structural type for a Cloudflare KV namespace binding.
+ *
+ * Declared locally (matching the pattern in `workerEntry.ts`, which defines
+ * its own `WorkerExecutionContext`) so `@decocms/start` does not depend on
+ * `@cloudflare/workers-types`. Only the methods the framework actually uses
+ * are modeled.
+ */
+export interface KVNamespace {
+  get(key: string, options?: { type?: "text" }): Promise<string | null>;
+  put(
+    key: string,
+    value: string,
+    options?: { expirationTtl?: number; metadata?: Record<string, unknown> },
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// KV key names — shared by the runtime reader (PR2), the write-through path
+// (PR3), and the CI sync/migrate scripts (PR4). Single source of truth so the
+// contract can't drift between read and write sides.
+// ---------------------------------------------------------------------------
+
+export const KV_KEYS = {
+  /** Full decofile JSON (the blocks map). */
+  SNAPSHOT: "decofile:current",
+  /** DJB2 hex revision of the snapshot — polled for change detection. */
+  REVISION: "index:revision",
+} as const;

package/src/cms/index.ts

@@ -0,0 +1,104 @@
+export type { BlockSnapshot, BlockSource, KVNamespace } from "./blockSource";
+export { BundledBlockSource, computeRevision, KV_KEYS } from "./blockSource";
+export type { DecoPage, Resolvable } from "./loader";
+export {
+  findPageByPath,
+  getAllPages,
+  getRevision,
+  getSiteSeo,
+  loadBlocks,
+  onChange,
+  setBlocks,
+  withBlocksOverride,
+} from "./loader";
+export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
+export {
+  getResolvedComponent,
+  getSection,
+  getSectionOptions,
+  getSectionRegistry,
+  getSyncComponent,
+  listRegisteredSections,
+  preloadSectionComponents,
+  preloadSectionModule,
+  registerOnBeforeResolveProps,
+  registerSection,
+  registerSections,
+  registerSectionsSync,
+  setResolvedComponent,
+} from "./registry";
+export type {
+  AsyncRenderingConfig,
+  CommerceLoader,
+  DanglingReferenceHandler,
+  DecoPageResult,
+  DeferredSection,
+  MatcherContext,
+  PageSeo,
+  ResolvedSection,
+  ResolveErrorHandler,
+} from "./resolve";
+export {
+  addSkipResolveType,
+  evaluateMatcher,
+  extractSeoFromProps,
+  extractSeoFromSections,
+  cacheDeferredRawProps,
+  getAsyncRenderingConfig,
+  getDeferredRawProps,
+  isBot,
+  isSeoSection,
+  onBeforeResolve,
+  reExtractRawProps,
+  registerBotPattern,
+  registerCommerceLoader,
+  registerCommerceLoaders,
+  unregisterCommerceLoader,
+  clearCommerceLoaders,
+  registerMatcher,
+  registerEagerSections,
+  registerNeverDeferSections,
+  registerSeoSections,
+  resolveDecoPage,
+  resolvePageSections,
+  resolvePageSeoBlock,
+  resolveDeferredSection,
+  resolveDeferredSectionFull,
+  resolveValue,
+  setAsyncRenderingConfig,
+  setDanglingReferenceHandler,
+  setResolveErrorHandler,
+  WELL_KNOWN_TYPES,
+} from "./resolve";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export {
+  isLayoutSection,
+  registerCacheableSections,
+  registerLayoutSections,
+  registerSectionLoader,
+  registerSectionLoaders,
+  runSectionLoaders,
+  runSingleSectionLoader,
+  unregisterLayoutSections,
+} from "./sectionLoaders";
+export {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";
+export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
+export { applySectionConventions } from "./applySectionConventions";
+export type { ActionConfig, LoaderConfig, MatcherConfig, MetaResponse } from "./schema";
+export {
+  composeMeta,
+  getRegisteredLoaders,
+  getRegisteredMatchers,
+  registerActionSchema,
+  registerActionSchemas,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "./schema";

package/src/cms/layoutCacheRace.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import {
+  registerLayoutSections,
+  registerSections,
+  resolveDecoPage,
+  setBlocks,
+  unregisterLayoutSections,
+} from "./index";
+
+/**
+ * Regression test for the layout-cache index-corruption bug that shipped in
+ * @decocms/start@6.12.1 and was fixed in 6.12.2 (deco-start commit 73d4f19,
+ * "fix(cms): don't mutate shared cached section objects when stamping
+ * index"). Two live production sites (casaevideo-tanstack, bagaggio-tanstack)
+ * hit this in the wild as an intermittent "footer renders above other
+ * sections" bug under concurrent traffic.
+ *
+ * Mechanism: resolveDecoPage caches a layout section's (Header/Footer)
+ * resolved output in a module-level Map, shared across every request that
+ * references the same layout block — and dedupes concurrent in-flight
+ * resolutions to the same shared Promise. Each request then stamps its own
+ * page's flat position onto `.index` so mergeSections can sort eager +
+ * deferred sections back into CMS order. If two concurrent requests need the
+ * SAME cached layout section at DIFFERENT flat positions (e.g. page A has
+ * Footer at index 0, page B has Footer at index 2), and stamping mutates the
+ * shared cached object in place, whichever request's stamp lands last wins —
+ * and both requests then see that same (possibly wrong-for-them) index.
+ *
+ * The fix clones the wrapper object before stamping, so each caller gets its
+ * own `{ ...section, index }` and the shared cache/in-flight objects are
+ * never touched.
+ */
+describe("resolveDecoPage — layout section cache does not leak `.index` across concurrent requests", () => {
+  it("gives each page its own correct Footer index when resolved concurrently", async () => {
+    const FOOTER_TYPE = "site/sections/RaceFooter.tsx";
+    const FILLER_TYPE = "site/sections/RaceFiller.tsx";
+
+    // A controllable delay on Footer's resolver forces both concurrent
+    // resolveDecoPage() calls to land on the SAME in-flight promise
+    // (resolvedLayoutInflight), reproducing the exact shared-object window
+    // the original bug required — without this, the two calls might resolve
+    // sequentially and never actually share state.
+    let releaseFooter: () => void = () => {};
+    const footerGate = new Promise<void>((resolve) => {
+      releaseFooter = resolve;
+    });
+
+    registerSections({
+      [FOOTER_TYPE]: async () => {
+        await footerGate;
+        return { default: () => null };
+      },
+      [FILLER_TYPE]: async () => ({ default: () => null }),
+    });
+    registerLayoutSections([FOOTER_TYPE]);
+
+    setBlocks({
+      "pages-race-a": {
+        path: "/race-a",
+        // Footer at flat index 0 for this page.
+        sections: [{ __resolveType: FOOTER_TYPE }, { __resolveType: FILLER_TYPE }],
+      },
+      "pages-race-b": {
+        path: "/race-b",
+        // Same Footer, but at flat index 2 for this page.
+        sections: [
+          { __resolveType: FILLER_TYPE },
+          { __resolveType: FILLER_TYPE },
+          { __resolveType: FOOTER_TYPE },
+        ],
+      },
+    });
+
+    try {
+      const pending = Promise.all([resolveDecoPage("/race-a"), resolveDecoPage("/race-b")]);
+
+      // Let both resolveDecoPage() calls start and reach the shared
+      // in-flight Footer promise before releasing it — this is what forces
+      // them onto the SAME cached/in-flight object rather than resolving
+      // one after the other.
+      await new Promise((r) => setTimeout(r, 10));
+      releaseFooter();
+
+      const [pageA, pageB] = await pending;
+
+      const footerA = pageA?.resolvedSections.find((s) => s.component === FOOTER_TYPE);
+      const footerB = pageB?.resolvedSections.find((s) => s.component === FOOTER_TYPE);
+
+      expect(footerA).toBeDefined();
+      expect(footerB).toBeDefined();
+
+      // The bug: mutating a shared cached object in place means both pages
+      // would observe whichever index was stamped last (either both 0 or
+      // both 2), not their own correct position.
+      expect(footerA?.index).toBe(0);
+      expect(footerB?.index).toBe(2);
+
+      // The fix clones the wrapper before stamping — each page's Footer
+      // section must be its own object, not the same shared reference.
+      expect(footerA).not.toBe(footerB);
+    } finally {
+      unregisterLayoutSections([FOOTER_TYPE]);
+    }
+  });
+
+  it("mechanism check: mutating a shared object in place under concurrent stamping loses one side's index (isolated, framework-independent)", async () => {
+    // This isolates the exact bug mechanism from the diff that shipped in
+    // 6.12.1 and was reverted after the rollback, independent of the CMS
+    // registry/cache machinery — proof that the failure mode is a plain JS
+    // shared-mutable-object race, not something specific to this framework's
+    // plumbing.
+    type Wrapper = { component: string; index?: number };
+
+    const sharedCached: Wrapper[] = [{ component: "Footer" }];
+
+    // Old (buggy) behavior: mutate the shared array's objects in place.
+    function stampBuggy(indexForThisCaller: number): Promise<Wrapper[]> {
+      return Promise.resolve(sharedCached).then((sections) => {
+        for (const s of sections) s.index = indexForThisCaller;
+        return sections;
+      });
+    }
+
+    // New (fixed) behavior: clone before stamping.
+    function stampFixed(indexForThisCaller: number): Promise<Wrapper[]> {
+      return Promise.resolve(sharedCached).then((sections) =>
+        sections.map((s) => ({ ...s, index: indexForThisCaller })),
+      );
+    }
+
+    // Two "requests" concurrently want different indices for the same
+    // shared cached object. With the buggy stamper, whichever `.then()`
+    // callback runs last (caller B, since microtasks run in scheduling
+    // order) overwrites the object caller A already received a *reference*
+    // to — so caller A's array ends up reporting caller B's index too.
+    const [buggyA, buggyB] = await Promise.all([stampBuggy(0), stampBuggy(2)]);
+    expect(buggyA[0].index).toBe(2); // <- corrupted: A wanted 0, sees 2
+    expect(buggyB[0].index).toBe(2);
+    expect(buggyA[0]).toBe(buggyB[0]); // same object reference — the bug
+
+    const [fixedA, fixedB] = await Promise.all([stampFixed(0), stampFixed(2)]);
+    expect(fixedA[0].index).toBe(0); // <- correct
+    expect(fixedB[0].index).toBe(2); // <- correct
+    expect(fixedA[0]).not.toBe(fixedB[0]); // independent objects — the fix
+  });
+});