@sitecore-content-sdk/nextjs 2.1.1 → 2.2.0-canary.20260527110239

package/dist/cjs/tools/generate-map.js

@@ -33,11 +33,39 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateMap = exports.defaultClientMapTemplate = void 0;
+exports.generateMap = exports.defaultClientMapTemplate = exports.defaultServerMapTemplate = void 0;
 const tools_1 = require("@sitecore-content-sdk/content/tools");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const utils_1 = require("./templating/utils");
+const DEFAULT_HEADER_COMMENT = "Below are built-in components that are available in the app, it's recommended to keep them as is";
+const APP_ROUTER_BUILTIN_IMPORTS = `
+import { BYOCServerWrapper, NextjsContentSdkComponent, FEaaSServerWrapper } from '@sitecore-content-sdk/nextjs';
+import { Form } from '@sitecore-content-sdk/nextjs';
+`;
+const APP_ROUTER_BUILTIN_ENTRIES = [
+    `['BYOCWrapper', BYOCServerWrapper]`,
+    `['FEaaSWrapper', FEaaSServerWrapper]`,
+    `['Form', { ...Form, componentType: 'client' }]`,
+];
+const PAGES_ROUTER_BUILTIN_IMPORTS = `
+import { BYOCWrapper, NextjsContentSdkComponent, FEaaSWrapper } from '@sitecore-content-sdk/nextjs';
+import { Form } from '@sitecore-content-sdk/nextjs';
+`;
+const PAGES_ROUTER_BUILTIN_ENTRIES = [
+    `['BYOCWrapper', BYOCWrapper]`,
+    `['FEaaSWrapper', FEaaSWrapper]`,
+    `['Form', Form]`,
+];
+const CLIENT_MAP_BUILTIN_IMPORTS = `
+import { BYOCClientWrapper, NextjsContentSdkComponent, FEaaSClientWrapper } from '@sitecore-content-sdk/nextjs';
+import { Form } from '@sitecore-content-sdk/nextjs';
+`;
+const CLIENT_MAP_BUILTIN_ENTRIES = [
+    `['BYOCWrapper', BYOCClientWrapper]`,
+    `['FEaaSWrapper', FEaaSClientWrapper]`,
+    `['Form', Form]`,
+];
 // Common builder for Next.js component map content
 const prepareComponentsForMap = (components, opts) => {
     const groups = new Map();
@@ -113,21 +141,16 @@ const prepareComponentsForMap = (components, opts) => {
     }
     return entries;
 };
-const buildNextjsMapContent = (entries, componentImports, options = {}) => {
-    const isAppRouter = (0, utils_1.detectRouterType)() === 'app';
-    const { headerComment = "Below are built-in components that are available in the app, it's recommended to keep them as is", isClientMap = false, } = options;
+/**
+ * Distinguishes the simple 2-arity ComponentMapTemplate from the 3-arity EnhancedComponentMapTemplate.
+ * @param {ComponentMapTemplate | EnhancedComponentMapTemplate} fn The template function to check.
+ * @internal
+ */
+const isComponentMapTemplate = (fn) => fn.length === 2;
+const buildNextjsMapContent = (entries, componentImports, options) => {
+    const { headerComment = DEFAULT_HEADER_COMMENT, isClientMap = false, builtInImports, builtInMapEntries, } = options;
     const wildcardImports = [];
     const namedImports = [];
-    const builtInImports = options.builtInImports ||
-        `
-import { BYOCWrapper, NextjsContentSdkComponent, FEaaSWrapper } from '@sitecore-content-sdk/nextjs';
-import { Form } from '@sitecore-content-sdk/nextjs';
-`;
-    const builtInMapEntries = options.builtInMapEntries || [
-        `['BYOCWrapper', BYOCWrapper]`,
-        `['FEaaSWrapper', FEaaSWrapper]`,
-        `['Form', ${isAppRouter ? '{ ...Form, componentType: \'client\' }' : 'Form'}]`,
-    ];
     // Add per-entry imports
     entries.forEach((e) => wildcardImports.push(...e.imports));
     // Handle package imports
@@ -145,8 +168,8 @@ import { Form } from '@sitecore-content-sdk/nextjs';
         ...namedImports,
     ].filter(Boolean);
     const importsSection = importLines.length ? `\n${importLines.join('\n')}` : '';
-    // Build entry lines (package named imports are appended below)
-    const componentMapEntries = builtInMapEntries;
+    // Clone to avoid mutating the caller's array
+    const componentMapEntries = structuredClone(builtInMapEntries);
     for (const e of entries) {
         const value = !isClientMap && e.annotateClient
             ? `{ ${e.valueExpr}, componentType: 'client' }`
@@ -179,26 +202,31 @@ ${componentMapEntries
 export default componentMap;
 `;
 };
-// default client template
+// Default App Router (server) component map template
+const defaultServerMapTemplate = (components, componentImports, ctx) => {
+    var _a, _b;
+    const entries = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.entries) !== null && _a !== void 0 ? _a : prepareComponentsForMap(components, {
+        includeVariants: (_b = ctx === null || ctx === void 0 ? void 0 : ctx.includeVariants) !== null && _b !== void 0 ? _b : true,
+    });
+    return buildNextjsMapContent(entries, componentImports, {
+        headerComment: DEFAULT_HEADER_COMMENT,
+        isClientMap: false,
+        builtInImports: APP_ROUTER_BUILTIN_IMPORTS,
+        builtInMapEntries: APP_ROUTER_BUILTIN_ENTRIES,
+    });
+};
+exports.defaultServerMapTemplate = defaultServerMapTemplate;
+// Default client-safe component map template for App Router
 const defaultClientMapTemplate = (components, componentImports, ctx) => {
     var _a, _b;
-    const builtInImports = `
-import { BYOCClientWrapper, NextjsContentSdkComponent, FEaaSClientWrapper } from '@sitecore-content-sdk/nextjs';
-import { Form } from '@sitecore-content-sdk/nextjs';
-`;
-    const builtInMapEntries = [
-        `['BYOCWrapper', BYOCClientWrapper]`,
-        `['FEaaSWrapper', FEaaSClientWrapper]`,
-        `['Form', Form]`,
-    ];
     const entries = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.entries) !== null && _a !== void 0 ? _a : prepareComponentsForMap(components, {
         includeVariants: (_b = ctx === null || ctx === void 0 ? void 0 : ctx.includeVariants) !== null && _b !== void 0 ? _b : true,
     });
     return buildNextjsMapContent(entries, componentImports, {
         headerComment: 'Client-safe component map for App Router',
         isClientMap: true,
-        builtInImports,
-        builtInMapEntries,
+        builtInImports: CLIENT_MAP_BUILTIN_IMPORTS,
+        builtInMapEntries: CLIENT_MAP_BUILTIN_ENTRIES,
     });
 };
 exports.defaultClientMapTemplate = defaultClientMapTemplate;
@@ -219,116 +247,93 @@ const collectComponents = (opts) => {
 /**
  * Generate and write componentMap.ts files based on provided params.
  *
- * When clientComponentMap is true, generates:
+ * Pages Router:
+ * - component-map.ts          : Single component map with Pages Router wrappers
+ *
+ * App Router (clientComponentMap=true or undefined):
  * - component-map.ts          : Full component map with all components (server, client, universal)
- * - component-map.client.ts   : Client-safe map with only client + universal components
+ * - component-map.client.ts   : Client-safe map with client + universal components
  *
- * When clientComponentMap is false, generates:
- * - component-map.ts          : Single component map (traditional behavior)
+ * App Router (clientComponentMap=false):
+ * - component-map.ts          : Full component map with all components (server, client, universal)
+ * - component-map.client.ts   : Client-safe map with built-in components only (no user components)
  *
- * When includeVariants is true (in either mode):
+ * When includeVariants is true:
  * - Includes component **variants** in the generated map(s) alongside base components
  * - Preserves the same client/server filtering rules (variants obey clientComponentMap filtering)
  * - Variant entries are emitted using the same naming/keys convention as their base components
  *
  * Template Customization:
  * - mapTemplate: Custom template for main component map (works for both single and dual map modes)
- * - clientMapTemplate: Custom template for client component map (only used when clientComponentMap is true)
+ * - clientMapTemplate: Custom template for client component map (App Router only)
  * @param {GenerateMapArgs} params - The parameters for the generateMap function.
  * @public
  */
 const generateMap = ({ paths, destination = '.sitecore', exclude, componentImports, mapTemplate, clientMapTemplate, clientComponentMap, includeVariants = true, }) => {
-    const isAppRouter = (0, utils_1.detectRouterType)() === 'app';
-    const shouldGenerateClientMap = clientComponentMap !== null && clientComponentMap !== void 0 ? clientComponentMap : isAppRouter;
-    if (shouldGenerateClientMap) {
-        // App Router case, main map
-        const getComponents = collectComponents({ paths, exclude, includeVariants, filter: 'all' });
-        let mainContent;
-        if (mapTemplate) {
-            mainContent = mapTemplate(getComponents.raw, componentImports, {
-                entries: getComponents.entries,
+    const routerType = (0, utils_1.detectRouterType)();
+    const allComponents = collectComponents({ paths, exclude, includeVariants, filter: 'all' });
+    if (routerType === utils_1.ROUTER_TYPE.PAGES) {
+        const content = mapTemplate
+            ? mapTemplate(allComponents.raw, componentImports, {
+                entries: allComponents.entries,
                 includeVariants,
                 isClientMap: false,
-            });
-        }
-        else {
-            // default app router server map
-            const builtInImports = `
-import { BYOCServerWrapper, NextjsContentSdkComponent, FEaaSServerWrapper } from '@sitecore-content-sdk/nextjs';
-import { Form } from '@sitecore-content-sdk/nextjs';
-`;
-            const builtInMapEntries = [
-                `['BYOCWrapper', BYOCServerWrapper]`,
-                `['FEaaSWrapper', FEaaSServerWrapper]`,
-                `['Form', { ...Form, componentType: 'client' }]`,
-            ];
-            mainContent = buildNextjsMapContent(getComponents.entries, componentImports, {
-                headerComment: "Below are built-in components that are available in the app, it's recommended to keep them as is",
+            })
+            : buildNextjsMapContent(allComponents.entries, componentImports, {
                 isClientMap: false,
-                builtInImports,
-                builtInMapEntries,
+                builtInImports: PAGES_ROUTER_BUILTIN_IMPORTS,
+                builtInMapEntries: PAGES_ROUTER_BUILTIN_ENTRIES,
             });
+        try {
+            fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.ts'), content, 'utf8');
         }
-        fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.ts'), mainContent, 'utf8');
-        // App Router, client map
-        const clientComponents = collectComponents({
-            paths,
-            exclude,
-            includeVariants,
-            filter: 'client',
-        });
-        const clientTemplate = clientMapTemplate || exports.defaultClientMapTemplate;
-        let clientContent;
-        if (clientTemplate.length >= 2) {
-            clientContent = clientTemplate(clientComponents.raw, componentImports);
-        }
-        else {
-            clientContent = clientTemplate(clientComponents.raw, componentImports, {
-                entries: clientComponents.entries,
-                includeVariants,
-                isClientMap: true,
-            });
+        catch (error) {
+            console.error(`Component Map generation failed. Error writing to file ${destination}:`, error);
+            throw error;
         }
-        fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.client.ts'), clientContent, 'utf8');
+        return;
     }
-    else {
-        // Either in pages/app router or clientComponentMap = false
-        const components = collectComponents({
-            paths,
-            exclude,
+    const mainContent = mapTemplate
+        ? mapTemplate(allComponents.raw, componentImports, {
+            entries: allComponents.entries,
+            includeVariants,
+            isClientMap: false,
+        })
+        : (0, exports.defaultServerMapTemplate)(allComponents.raw, componentImports, {
+            entries: allComponents.entries,
             includeVariants,
-            filter: 'all',
-        }).entries;
-        const content = buildNextjsMapContent(components, componentImports, {
-            headerComment: "Below are built-in components that are available in the app, it's recommended to keep them as is",
             isClientMap: false,
         });
-        fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.ts'), content, 'utf8');
-        // For App Router compatibility, always generate client map file even when clientComponentMap is false
-        // When clientComponentMap is false, only include built-in components (no custom client components)
-        if (shouldGenerateClientMap || isAppRouter) {
-            const clientMapTemplateToUse = clientMapTemplate || exports.defaultClientMapTemplate;
-            const components = collectComponents({ paths: [], includeVariants, filter: 'all' });
-            let clientMapContent;
-            if (clientMapTemplateToUse.length >= 2) {
-                clientMapContent = clientMapTemplateToUse([], componentImports);
-            }
-            else {
-                clientMapContent = clientMapTemplateToUse([], componentImports, {
-                    entries: components.entries,
-                    includeVariants,
-                    isClientMap: true,
-                });
-            }
-            const clientMapFile = path.join(process.cwd(), destination, 'component-map.client.ts');
-            try {
-                fs.writeFileSync(clientMapFile, clientMapContent, { encoding: 'utf8' });
-            }
-            catch (error) {
-                console.error(`Client Component Map generation failed. Error writing to file ${destination}:`, error);
-                throw error;
-            }
-        }
+    try {
+        fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.ts'), mainContent, 'utf8');
+    }
+    catch (error) {
+        console.error(`Main Component Map generation failed. Error writing to file ${destination}:`, error);
+        throw error;
+    }
+    // clientComponentMap=true  -> include user client+universal components
+    // clientComponentMap=undefined  -> include user client+universal components
+    // clientComponentMap=false -> built-ins only
+    const shouldGenerateClientMap = clientComponentMap !== null && clientComponentMap !== void 0 ? clientComponentMap : true;
+    const clientComponents = shouldGenerateClientMap
+        ? collectComponents({ paths, exclude, includeVariants, filter: 'client' })
+        : { raw: [], entries: [] };
+    const clientTemplate = clientMapTemplate || exports.defaultClientMapTemplate;
+    let clientContent;
+    if (isComponentMapTemplate(clientTemplate))
+        clientContent = clientTemplate(clientComponents.raw, componentImports);
+    else
+        clientContent = clientTemplate(clientComponents.raw, componentImports, {
+            entries: clientComponents.entries,
+            includeVariants,
+            isClientMap: true,
+        });
+    try {
+        fs.writeFileSync(path.join(process.cwd(), destination, 'component-map.client.ts'), clientContent, 'utf8');
+    }
+    catch (error) {
+        console.error(`Client Component Map generation failed. Error writing to file ${destination}:`, error);
+        throw error;
     }
 };
 exports.generateMap = generateMap;

package/dist/cjs/tools/templating/utils.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTER_TYPE = void 0;
 exports.detectRouterType = detectRouterType;
 exports.detectComponentType = detectComponentType;
 exports.getComponentListWithTypes = getComponentListWithTypes;
@@ -12,6 +13,17 @@ exports.nextjsDefaultMapTemplate = nextjsDefaultMapTemplate;
 const node_tools_1 = require("@sitecore-content-sdk/content/node-tools");
 const typescript_1 = __importDefault(require("typescript"));
 const fs_1 = __importDefault(require("fs"));
+/**
+ * Constants for Next.js router types. Used for consistent detection and comparison throughout the codebase.
+ * Values are based on Next.js conventions:
+ * - 'app' for App Router (src/app or app directory)
+ * - 'pages' for Pages Router (src/pages or pages directory)
+ * @internal
+ */
+exports.ROUTER_TYPE = {
+    APP: 'app',
+    PAGES: 'pages',
+};
 /**
  * Detects the Next.js router type (App Router or Pages Router) based on directory structure.
  * @param {string} projectRoot - The project root directory. Defaults to current working directory.
@@ -19,15 +31,15 @@ const fs_1 = __importDefault(require("fs"));
  * @internal
  */
 function detectRouterType(projectRoot = process.cwd()) {
-    const appDirExists = fs_1.default.existsSync(`${projectRoot}/src/app`) || fs_1.default.existsSync(`${projectRoot}/app`);
-    const pagesDirExists = fs_1.default.existsSync(`${projectRoot}/src/pages`) || fs_1.default.existsSync(`${projectRoot}/pages`);
-    if (appDirExists) {
-        return 'app';
-    }
-    if (pagesDirExists) {
-        return 'pages';
-    }
-    return 'pages';
+    const appDirExists = fs_1.default.existsSync(`${projectRoot}/src/${exports.ROUTER_TYPE.APP}`) ||
+        fs_1.default.existsSync(`${projectRoot}/${exports.ROUTER_TYPE.APP}`);
+    const pagesDirExists = fs_1.default.existsSync(`${projectRoot}/src/${exports.ROUTER_TYPE.PAGES}`) ||
+        fs_1.default.existsSync(`${projectRoot}/${exports.ROUTER_TYPE.PAGES}`);
+    if (appDirExists)
+        return exports.ROUTER_TYPE.APP;
+    if (pagesDirExists)
+        return exports.ROUTER_TYPE.PAGES;
+    return exports.ROUTER_TYPE.PAGES;
 }
 /**
  * Detects the component type based on directives, imports, and router context.
@@ -155,7 +167,7 @@ function detectComponentType(filePath, routerType) {
         // Router-aware defaults:
         // - App Router: defaults to server (RSC by default)
         // - Pages Router: defaults to universal (isomorphic by default)
-        if (detectedRouterType === 'app') {
+        if (detectedRouterType === exports.ROUTER_TYPE.APP) {
             return 'server';
         }
         else {

package/dist/esm/cache/sitecore-cache-tags.js

@@ -0,0 +1,119 @@
+/**
+ * Stable cache tag strings for Sitecore content (Next.js `cacheTag`, `unstable_cache` tags, `revalidateTag`).
+ * Tags are deterministic for the same logical inputs so app code and invalidation webhooks stay aligned.
+ * @internal
+ */
+export const SITECORE_CONTENT_CACHE_TAG_PREFIX = 'sc';
+/**
+ * Sanitizes a single segment for use inside Sitecore cache tags.
+ * Colons are reserved as delimiters; slashes and whitespace are normalized for stable keys.
+ * @param {string} value - Raw segment (site name, locale, path segment, etc.).
+ * @internal
+ */
+export function sanitizeSitecoreCacheTagSegment(value) {
+    return value.trim().toLowerCase().replace(/[/:\s]+/g, '_');
+}
+/**
+ * Normalizes a Sitecore item GUID for use in cache tags (lowercase, no braces).
+ * @param {string} itemId - Sitecore item id or GUID string.
+ * @internal
+ */
+export function normalizeSitecoreItemIdForCacheTag(itemId) {
+    return itemId.trim().toLowerCase().replace(/[{}]/g, '');
+}
+/**
+ * Tag for a resolved route (site + language + logical path). Use for URL-level invalidation.
+ * @param {BuildSitecoreRouteCacheTagParams} params - Site, locale, and optional path segments.
+ * @internal
+ */
+export function buildSitecoreRouteCacheTag(params) {
+    var _a;
+    const site = sanitizeSitecoreCacheTagSegment(params.site);
+    const locale = sanitizeSitecoreCacheTagSegment(params.locale);
+    const segments = ((_a = params.pathSegments) !== null && _a !== void 0 ? _a : []).map((s) => sanitizeSitecoreCacheTagSegment(s));
+    const pathKey = segments.length > 0 ? segments.join('/') : '_';
+    return `${SITECORE_CONTENT_CACHE_TAG_PREFIX}:route:${site}:${locale}:${pathKey}`;
+}
+/**
+ * Tag for a layout/route item (and anything else keyed the same way). Use for item-level invalidation.
+ * @param {BuildSitecoreItemCacheTagParams} params - Item id, locale, and optional published version.
+ * @internal
+ */
+export function buildSitecoreItemCacheTag(params) {
+    const id = normalizeSitecoreItemIdForCacheTag(params.itemId);
+    const locale = sanitizeSitecoreCacheTagSegment(params.locale);
+    const ver = params.version !== undefined && Number.isFinite(params.version)
+        ? `v${Math.trunc(params.version)}`
+        : 'latest';
+    return `${SITECORE_CONTENT_CACHE_TAG_PREFIX}:item:${id}:${locale}:${ver}`;
+}
+/**
+ * Tag for dictionary data scoped to site + locale.
+ * @param {BuildSitecoreDictionaryCacheTagParams} params - Site and locale for the dictionary fetch.
+ * @public
+ */
+export function buildSitecoreDictionaryCacheTag(params) {
+    const site = sanitizeSitecoreCacheTagSegment(params.site);
+    const locale = sanitizeSitecoreCacheTagSegment(params.locale);
+    return `${SITECORE_CONTENT_CACHE_TAG_PREFIX}:dict:${site}:${locale}`;
+}
+/**
+ * Builds deduplicated dictionary cache tags from a sites list.
+ * @param {BuildSitecoreDictionaryCacheTagsFromSitesParams} params - Sites list and fallback locale.
+ * @internal
+ */
+export function buildSitecoreDictionaryCacheTagsFromSites(params) {
+    var _a;
+    const seen = new Set();
+    const out = [];
+    const push = (tag) => {
+        if (!seen.has(tag)) {
+            seen.add(tag);
+            out.push(tag);
+        }
+    };
+    for (const site of params.sites) {
+        const locale = ((_a = site.language) === null || _a === void 0 ? void 0 : _a.trim()) ? site.language : params.baseLocale;
+        push(buildSitecoreDictionaryCacheTag({ site: site.name, locale }));
+    }
+    return out;
+}
+/**
+ * Builds an item cache tag from Sitecore layout route data when `itemId` is present.
+ * Prefers `itemLanguage` from Sitecore when set; otherwise uses `fallbackLocale`.
+ * Accepts the same `RouteData` shape returned by the layout service (e.g. `page.layout.sitecore.route`,
+ * which is `RouteData | null`) or `undefined` when the page did not resolve.
+ * @param {RouteData | null | undefined} route - Route node from layout (item id, language, version).
+ * @param {string} fallbackLocale - Locale used when `route.itemLanguage` is not set.
+ * @returns `null` when `route` is missing or `route.itemId` is not set.
+ * @internal
+ */
+export function buildSitecoreItemCacheTagFromRouteData(route, fallbackLocale) {
+    if (!(route === null || route === void 0 ? void 0 : route.itemId)) {
+        return null;
+    }
+    const locale = route.itemLanguage
+        ? sanitizeSitecoreCacheTagSegment(route.itemLanguage)
+        : sanitizeSitecoreCacheTagSegment(fallbackLocale);
+    const id = normalizeSitecoreItemIdForCacheTag(route.itemId);
+    const ver = route.itemVersion !== undefined && Number.isFinite(route.itemVersion)
+        ? `v${Math.trunc(route.itemVersion)}`
+        : 'latest';
+    return `${SITECORE_CONTENT_CACHE_TAG_PREFIX}:item:${id}:${locale}:${ver}`;
+}
+/**
+ * Deduplicates tag strings while preserving first-seen order.
+ * @param {string[]} tags - Tag strings possibly containing duplicates.
+ * @internal
+ */
+export function dedupeSitecoreCacheTags(tags) {
+    const seen = new Set();
+    const out = [];
+    for (const t of tags) {
+        if (!seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    }
+    return out;
+}

package/dist/esm/cache/sitecore-edge-webhook-revalidation.js

@@ -0,0 +1,63 @@
+import { SITECORE_CONTENT_CACHE_TAG_PREFIX, buildSitecoreItemCacheTag, dedupeSitecoreCacheTags, } from './sitecore-cache-tags';
+/**
+ * Strips Experience Edge style suffixes from an `identifier` so the value can be used as an item id in cache tags.
+ * Handles `{GUID}`, `{GUID}-media`, `{GUID}-layout` style strings.
+ * @param {string} identifier - Raw identifier from a webhook update row.
+ * @internal
+ */
+export function extractSitecoreEdgeContentId(identifier) {
+    if (!identifier || typeof identifier !== 'string') {
+        return '';
+    }
+    const trimmed = identifier.trim();
+    return trimmed.replace(/-(?:media|layout)$/i, '');
+}
+const FULL_TAG_PREFIX = `${SITECORE_CONTENT_CACHE_TAG_PREFIX}:`;
+/**
+ * @param {string} value - Candidate tag string from a webhook body.
+ * @returns True when `value` is already a full `sc:` content cache tag.
+ */
+function isFullSitecoreContentCacheTag(value) {
+    return value.startsWith(FULL_TAG_PREFIX);
+}
+/**
+ * Maps an Experience Edge webhook JSON body to Content SDK cache tag strings used by
+ * {@link collectSitecorePageCacheTags} / {@link buildSitecoreItemCacheTag} (`sc:item:...`), so
+ * `revalidateTag` matches tags registered during cached reads.
+ * **`updates`** rows resolve to **`sc:item:…`** (locale from `entity_culture` or `defaultLocale`). **`tags`**: full `sc:` strings pass through; bare ids become **`sc:item:…`** with `defaultLocale`. Route/variant tags are not inferred.
+ * @param {SitecoreEdgeRevalidateRequestBody | null | undefined} body - Webhook JSON body (tags and/or updates).
+ * @param {CollectSitecoreTagsFromEdgeBodyOptions} options - Default locale when culture is missing on an update or bare tag.
+ * @internal
+ */
+export function collectSitecoreTagsFromEdgeRevalidateRequestBody(body, options) {
+    var _a, _b, _c, _d;
+    const { defaultLocale } = options;
+    const out = [];
+    for (const raw of (_a = body === null || body === void 0 ? void 0 : body.tags) !== null && _a !== void 0 ? _a : []) {
+        if (typeof raw !== 'string') {
+            continue;
+        }
+        const s = raw.trim();
+        if (!s) {
+            continue;
+        }
+        if (isFullSitecoreContentCacheTag(s)) {
+            out.push(s);
+        }
+        else {
+            const id = extractSitecoreEdgeContentId(s);
+            if (id) {
+                out.push(buildSitecoreItemCacheTag({ itemId: id, locale: defaultLocale }));
+            }
+        }
+    }
+    for (const u of (_b = body === null || body === void 0 ? void 0 : body.updates) !== null && _b !== void 0 ? _b : []) {
+        const id = extractSitecoreEdgeContentId((_c = u === null || u === void 0 ? void 0 : u.identifier) !== null && _c !== void 0 ? _c : '');
+        if (!id) {
+            continue;
+        }
+        const locale = ((_d = u === null || u === void 0 ? void 0 : u.entity_culture) === null || _d === void 0 ? void 0 : _d.trim()) || defaultLocale;
+        out.push(buildSitecoreItemCacheTag({ itemId: id, locale }));
+    }
+    return dedupeSitecoreCacheTags(out).filter(Boolean);
+}

package/dist/esm/cache/sitecore-page-cache-tags.js

@@ -0,0 +1,80 @@
+import { normalizePersonalizedRewrite } from '@sitecore-content-sdk/content/personalize';
+import { buildSitecoreItemCacheTagFromRouteData, buildSitecoreRouteCacheTag, dedupeSitecoreCacheTags, } from './sitecore-cache-tags';
+/** @param {string} pathname - Raw pathname (may omit leading slash). */
+function normalizePathname(pathname) {
+    const trimmed = pathname.trim() || '/';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/**
+ * Trims leading and trailing `/` from a single path segment without regex (linear time; avoids ReDoS flags on path-derived input).
+ * @param {string} part - One App Router catch-all path segment.
+ */
+function trimSlashes(part) {
+    let start = 0;
+    let end = part.length;
+    while (start < end && part[start] === '/') {
+        start++;
+    }
+    while (end > start && part[end - 1] === '/') {
+        end--;
+    }
+    return part.slice(start, end);
+}
+/**
+ * Normalizes App Router catch-all `path` segments the same way as `SitecoreClient.parsePath` for a
+ * string array (leading slash, trim segments, drop empty `/` parts).
+ * @param {string[]} path - App Router catch-all segments.
+ */
+function personalizedPathnameFromPathSegments(path) {
+    if (path.length === 0) {
+        return '/';
+    }
+    return `/${path
+        .filter((part) => part !== '/')
+        .map((part) => trimSlashes(part))
+        .join('/')}`;
+}
+/**
+ * Route segments after removing personalization rewrite markers, for stable route-level tags.
+ * @param {string} personalizedPathname - Pathname that may include personalization rewrite segments.
+ */
+function routeSegmentsFromPersonalizedPathname(personalizedPathname) {
+    const pathname = normalizePathname(personalizedPathname);
+    const n = normalizePersonalizedRewrite(pathname);
+    if (!n || n === '/') {
+        return [];
+    }
+    const noLead = n.startsWith('/') ? n.slice(1) : n;
+    return noLead.split('/').filter(Boolean);
+}
+/**
+ * Builds cache tags for a Sitecore page read (`getPage`): the route tag and the route's item tag.
+ * Dictionary data is not part of `getPage`; tag dictionary fetches separately (for example with
+ * `buildSitecoreDictionaryCacheTag` on a dedicated `use cache` helper).
+ *
+ * Registers **`sc:route:…`** and **`sc:item:…`** (when layout has `itemId`). Edge-style webhooks emit
+ * item ids, which the Sitecore revalidate route handler maps to **`sc:item:…`**; route tags are only
+ * invalidated when callers send the full `sc:route:…` strings in the `tags[]` array of the same revalidate request.
+ *
+ * Personalization variants are isolated naturally by URL path (each variant rewrite yields a distinct
+ * Cache Components key) so no `sc:pvv:…` tag is added here. If a personalize-specific webhook is wired
+ * up later, build that tag in the dedicated helper and add it on top of these.
+ * @param {CollectSitecorePageCacheTagsParams} params - Site, locale, path or personalized pathname, and route metadata.
+ * @public
+ */
+export function collectSitecorePageCacheTags(params) {
+    var _a, _b;
+    const pathnameInput = params.personalizedPathname !== undefined
+        ? params.personalizedPathname
+        : personalizedPathnameFromPathSegments((_a = params.path) !== null && _a !== void 0 ? _a : []);
+    const pathname = normalizePathname(pathnameInput);
+    const pathSegments = routeSegmentsFromPersonalizedPathname(pathname);
+    return dedupeSitecoreCacheTags([
+        buildSitecoreRouteCacheTag({
+            site: params.site,
+            locale: params.locale,
+            pathSegments,
+        }),
+        (_b = buildSitecoreItemCacheTagFromRouteData(params.route, params.locale)) !== null && _b !== void 0 ? _b : '',
+    ]).filter(Boolean);
+}

package/dist/esm/debug.js

@@ -1,9 +1,9 @@
-import { debug as coreDebug } from '@sitecore-content-sdk/core';
+import { debug as coreDebug, debugModule, debugNamespace, } from '@sitecore-content-sdk/core';
 import { debug as contentDebug } from '@sitecore-content-sdk/content';
 import { debug as searchDebug } from '@sitecore-content-sdk/react/search';
 /**
  * Unified debug object containing all debug namespaces from referenced content-sdk packages.
  * @public
  */
-const debug = Object.assign(Object.assign(Object.assign({}, coreDebug), contentDebug), { search: searchDebug });
+const debug = Object.assign(Object.assign(Object.assign({}, coreDebug), contentDebug), { search: searchDebug, revalidate: debugModule(`${debugNamespace}:revalidate`) });
 export default debug;