@akinon/pz-theme 2.0.80-rc.0 → 2.0.81-beta.0

package/CHANGELOG.md

@@ -1,38 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.80-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.80-rc.0
-  - @akinon/theme-contract@2.0.80-rc.0
+## 2.0.81-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.81-beta.0
+  - @akinon/theme-contract@2.0.81-beta.0
+
+## 2.0.80
+
+### Patch Changes
+
+- 6fb7f650: ZERO-4869: Implement GA4 ecommerce event tracking across various components
+  - @akinon/next@2.0.80
+  - @akinon/theme-contract@2.0.80
 
 ## 2.0.79
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.80-rc.0",
+  "version": "2.0.81-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.80-rc.0",
+    "@akinon/next": "2.0.81-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.80-rc.0",
+    "@akinon/theme-contract": "2.0.81-beta.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.80-rc.0",
+    "@akinon/next": "2.0.81-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/add-to-cart-block.tsx

@@ -5,6 +5,11 @@ import { useAddProductMutation } from '@akinon/next/data/client/product';
 import { basketApi } from '@akinon/next/data/client/basket';
 import { useAppDispatch } from '@akinon/next/redux/hooks';
 import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 import { BlockRendererProps } from './block-renderer-registry';
 import {
   DesignerPlaceholder,
@@ -281,6 +286,10 @@ const AddToCartBlock = ({
       // by the mini-basket chrome block) has to be refreshed explicitly.
       dispatch(basketApi.util.invalidateTags(['Basket', 'MiniBasket']));
       setFeedback('added');
+      emitCommerceEvent('add_to_cart', {
+        currency: readItemsCurrency(product),
+        items: [buildCommerceItem(product, { quantity })]
+      });
     } catch {
       setFeedback('error');
     }

package/src/blocks/auth-form-block.tsx

@@ -6,6 +6,7 @@ import { useRouter } from 'next/navigation';
 import { signIn } from 'next-auth/react';
 import { useLocalization } from '@akinon/next/hooks';
 import { getResponsiveValue, partAttrs } from '../utils';
+import { emitCommerceEvent } from '../utils/analytics';
 import { readToggle } from './product-block-utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
@@ -156,6 +157,12 @@ const AuthFormBlock = ({
         return;
       }
 
+      // GA4 auth events, on success only: a failed submit is an error state,
+      // not a login. `method` mirrors what the credentials provider is.
+      emitCommerceEvent(mode === 'register' ? 'sign_up' : 'login', {
+        method: providerId
+      });
+
       router.refresh();
       router.push(callbackUrl);
     } catch {

package/src/blocks/basket-items-block.tsx

@@ -15,6 +15,11 @@ import {
 import { useLocalization } from '@akinon/next/hooks';
 import PluginModule, { Component } from '@akinon/next/components/plugin-module';
 import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 import { useThemePageContext } from '../theme-page-context';
 import {
   formatMoney,
@@ -614,6 +619,21 @@ const BasketItemsBlock = ({
 
     if (isDesigner || productPk === undefined || nextQuantity < 0) return;
 
+    if (nextQuantity === 0) {
+      const removedQuantity = Number(item.quantity ?? 1) || 1;
+      emitCommerceEvent('remove_from_cart', {
+        currency: readItemsCurrency(
+          item as Record<string, unknown>,
+          localeCurrency
+        ),
+        items: [
+          buildCommerceItem(item.product as Record<string, unknown>, {
+            quantity: removedQuantity
+          })
+        ]
+      });
+    }
+
     updateQuantity({
       product: productPk,
       quantity: nextQuantity,

package/src/blocks/favorite-button-block.tsx

@@ -9,6 +9,11 @@ import {
   useRemoveFavoriteMutation
 } from '@akinon/next/data/client/wishlist';
 import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 import { BlockRendererProps } from './block-renderer-registry';
 import {
   DesignerPlaceholder,
@@ -219,6 +224,10 @@ const FavoriteButtonBlock = ({
         await removeFavorite(favorite.pk).unwrap();
       } else {
         await addFavorite(productPk).unwrap();
+        emitCommerceEvent('add_to_wishlist', {
+          currency: readItemsCurrency(product),
+          items: [buildCommerceItem(product)]
+        });
       }
     } catch {
       // Commerce rejected the toggle; the list query stays authoritative so

package/src/blocks/favourites-grid-block.tsx

@@ -17,6 +17,11 @@ import {
   TABLET_MEDIA_QUERY_COMPACT
 } from '../utils/breakpoints';
 import { normalizeListingProduct } from './listing-context';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
 import { BlockRendererProps } from './block-renderer-registry';
 import { DesignerPlaceholder, readToggle } from './product-block-utils';
@@ -214,6 +219,13 @@ const FavouritesGridBlock = ({
       // addProduct only invalidates MiniBasket, so the full basket query (used
       // by the mini-basket chrome block) has to be refreshed explicitly.
       dispatch(basketApi.util.invalidateTags(['Basket', 'MiniBasket']));
+      emitCommerceEvent('add_to_cart', {
+        currency: readItemsCurrency(
+          product as Record<string, unknown>,
+          localeCurrency
+        ),
+        items: [buildCommerceItem(product as Record<string, unknown>)]
+      });
     } catch {
       // Commerce owns the failure message (out of stock, variant required);
       // the grid stays as it was rather than inventing an error state.
@@ -264,6 +276,28 @@ const FavouritesGridBlock = ({
     .filter((favourite) => Boolean(favourite.product))
     .map(describe);
 
+  // GA4 view_item_list (ZERO-4869), once per distinct wishlist content: the
+  // favourites grid IS the list impression on this screen. Keyed by row keys
+  // so a remove refires with the new list, a mere re-render does not. A ref,
+  // not a global — each visit mounts a fresh grid and must report again.
+  const rowsKey = rows.map((row) => row.key).join(',');
+  const pushedListKey = React.useRef<string | null>(null);
+  React.useEffect(() => {
+    if (isDesigner || rows.length === 0) return;
+    if (pushedListKey.current === rowsKey) return;
+    pushedListKey.current = rowsKey;
+    emitCommerceEvent('view_item_list', {
+      currency: localeCurrency,
+      items: rows.map((row) =>
+        buildCommerceItem(row as Record<string, unknown>, {
+          listId: 'favourites',
+          listName: 'Favourites'
+        })
+      )
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowsKey, isDesigner]);
+
   // A designer who marked a child as the card layout gets that layout repeated
   // per saved product; otherwise the built-in card renders unchanged.
   const customCards = hasItemTemplate(block, currentBreakpoint) ? (
@@ -326,6 +360,23 @@ const FavouritesGridBlock = ({
     if (isDesigner) event.preventDefault();
   };
 
+  // GA4 select_item for the BUILT-IN card; custom item-template cards get the
+  // same push from the group anchor via the row scope.
+  const cardClick = (card: ReturnType<typeof describe>) =>
+    (event: React.MouseEvent) => {
+      guard(event);
+      if (isDesigner) return;
+      emitCommerceEvent('select_item', {
+        currency: localeCurrency,
+        items: [
+          buildCommerceItem(card as unknown as Record<string, unknown>, {
+            listId: 'favourites',
+            listName: 'Favourites'
+          })
+        ]
+      });
+    };
+
   const imageStyle: React.CSSProperties = {
     width: '100%',
     height: 'auto',
@@ -386,7 +437,7 @@ const FavouritesGridBlock = ({
             >
               <NextLink
                 href={isDesigner ? '#' : card.href || '#'}
-                onClick={guard}
+                onClick={cardClick(card)}
                 data-favourites-card-link=""
                 {...partAttrs('link')}
                 style={{

package/src/blocks/group-block.tsx

@@ -1,7 +1,13 @@
 import React from 'react';
 import NextLink from 'next/link';
 import { getResponsiveValue } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 import { BlockRendererProps } from './block-renderer-registry';
+import { useThemeItemScope } from './product-block-utils';
 import { renderComposedChildren } from './render-composed-children';
 
 /**
@@ -29,6 +35,20 @@ const GroupBlock = ({
   );
   const Tag = tag as keyof React.JSX.IntrinsicElements;
   const href = tag === 'a' ? block.properties?.href : undefined;
+  const itemScope = useThemeItemScope();
+
+  // GA4 select_item (ZERO-4869): a composed anchor inside a repeated product
+  // row IS the product card's click. The row scope carries the product, so no
+  // per-card wiring is needed — and outside a row this stays silent.
+  const handleAnchorAnalytics = () => {
+    if (isDesigner) return;
+    const scopedProduct = itemScope?.product;
+    if (!scopedProduct) return;
+    emitCommerceEvent('select_item', {
+      currency: readItemsCurrency(scopedProduct as Record<string, unknown>),
+      items: [buildCommerceItem(scopedProduct as Record<string, unknown>)]
+    });
+  };
 
   const tagProps: Record<string, unknown> = {
     className: 'contents'
@@ -37,6 +57,9 @@ const GroupBlock = ({
   if (tag === 'a' && href && !useRouterLink) {
     tagProps.href = href;
   }
+  if (tag === 'a' && !isDesigner) {
+    tagProps.onClick = handleAnchorAnalytics;
+  }
   if (tag === 'form') {
     tagProps.onSubmit = (event: React.FormEvent<HTMLFormElement>) => {
       event.preventDefault();
@@ -76,7 +99,12 @@ const GroupBlock = ({
 
   if (useRouterLink) {
     return (
-      <NextLink href={href as string} prefetch={false} className="contents">
+      <NextLink
+        href={href as string}
+        prefetch={false}
+        className="contents"
+        onClick={handleAnchorAnalytics}
+      >
         {renderedChildren}
       </NextLink>
     );

package/src/blocks/listing-context.ts

@@ -173,6 +173,12 @@ export interface ListingProduct {
   images?: string[];
   price: string;
   retailPrice: string;
+  /**
+   * The same two prices as plain numbers, for consumers that compute rather
+   * than display — analytics items, sort keys. Absent when unparseable.
+   */
+  priceAmount?: number;
+  retailPriceAmount?: number;
   /**
    * `price_extra_field.previous_price` — the price-history line several
    * markets require by law. Absent when commerce did not send one.
@@ -652,6 +658,8 @@ const normalizeProduct = (
           options.money
         ) || undefined,
     hasDiscount,
+    ...(numericPrice !== null ? { priceAmount: numericPrice } : null),
+    ...(numericRetail !== null ? { retailPriceAmount: numericRetail } : null),
     // The grid already derived this to draw its badge; publishing it means a
     // designer-authored card does not have to re-derive it from two strings.
     discountPercent: percentFromRetail,

package/src/blocks/product-grid-block.tsx

@@ -3,6 +3,10 @@
 import React from 'react';
 import NextLink from 'next/link';
 import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent
+} from '../utils/analytics';
 import {
   DESKTOP_MIN_WIDTH,
   MOBILE_MEDIA_QUERY_COMPACT,
@@ -577,6 +581,28 @@ const ProductGridBlock = ({
   const allProducts = listing?.products || [];
   const products = limit > 0 ? allProducts.slice(0, limit) : allProducts;
 
+  // GA4 view_item_list (ZERO-4869), once per distinct result set: keyed by the
+  // product keys so pagination and refiltering refire while re-renders do not.
+  // A ref, not a global — each client-side visit mounts a fresh grid and must
+  // report its own impression.
+  const productsKey = products.map((product) => product.key).join(',');
+  const pushedListKey = React.useRef<string | null>(null);
+  React.useEffect(() => {
+    if (isDesigner || products.length === 0) return;
+    if (pushedListKey.current === productsKey) return;
+    pushedListKey.current = productsKey;
+    emitCommerceEvent('view_item_list', {
+      items: products.map((product, index) =>
+        buildCommerceItem(product as unknown as Record<string, unknown>, {
+          index,
+          listId: 'product_grid',
+          listName: listing?.title || 'Product Grid'
+        })
+      )
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [productsKey, isDesigner]);
+
   // A designer who marked a child as the card layout gets that layout
   // repeated per product; otherwise the built-in card renders unchanged.
   const customCards = hasItemTemplate(block, currentBreakpoint) ? (
@@ -784,7 +810,21 @@ const ProductGridBlock = ({
         // Navigating inside the designer iframe would drop the author out of
         // the page they are editing, so cards are inert there.
         onClick={(event) => {
-          if (isDesigner) event.preventDefault();
+          if (isDesigner) {
+            event.preventDefault();
+            return;
+          }
+          emitCommerceEvent('select_item', {
+            items: [
+              buildCommerceItem(
+                product as unknown as Record<string, unknown>,
+                {
+                  listId: 'product_grid',
+                  listName: listing?.title || 'Product Grid'
+                }
+              )
+            ]
+          });
         }}
         style={{
           display: 'flex',

package/src/blocks/product-recommendations-block.tsx

@@ -11,6 +11,10 @@ import { useLocalization } from '@akinon/next/hooks';
 import { useOverlay } from '../hooks/use-overlay';
 import { useThemeSectionData } from '../theme-section-data-context';
 import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  buildCommerceItem,
+  emitCommerceEvent
+} from '../utils/analytics';
 import { BlockRendererProps } from './block-renderer-registry';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
 import { DESIGNER_SAMPLE_PRODUCT } from './item-template-utils';
@@ -1160,7 +1164,21 @@ const ProductRecommendationsBlock = ({
               // Navigating inside the designer iframe would drop the author out
               // of the page they are editing, so cards are inert there.
               onClick={(event) => {
-                if (isDesigner) event.preventDefault();
+                if (isDesigner) {
+                  event.preventDefault();
+                  return;
+                }
+                emitCommerceEvent('select_item', {
+                  items: [
+                    buildCommerceItem(
+                      product as unknown as Record<string, unknown>,
+                      {
+                        listId: 'product_recommendations',
+                        listName: 'Product Recommendations'
+                      }
+                    )
+                  ]
+                });
               }}
               style={{
                 display: 'flex',

package/src/blocks/search-box-block.tsx

@@ -3,6 +3,7 @@
 import React, { useRef, useState } from 'react';
 import { useRouter } from 'next/navigation';
 import { getResponsiveValue, partAttrs, resolveForceOpen } from '../utils';
+import { emitCommerceEvent } from '../utils/analytics';
 import { useOverlay } from '../hooks/use-overlay';
 import ThemeBlock from '../theme-block';
 import { BlockRendererProps } from './block-renderer-registry';
@@ -184,6 +185,7 @@ const SearchBoxBlock = ({
     event.preventDefault();
     const value = term.trim();
     if (!value || isDesigner) return;
+    emitCommerceEvent('search', { searchTerm: value });
     const separator = searchUrl.includes('?') ? '&' : '?';
     router.push(
       `${searchUrl}${separator}${queryParam}=${encodeURIComponent(value)}`

package/src/chrome/page-context.ts

@@ -131,10 +131,39 @@ export const normalizeProductEntry = (
     retailPrice: activePrice.retail_price ?? product.retail_price,
     currency: activePrice.currency_type ?? product.currency_type ?? '',
     description: product.description || '',
-    attributes: normalizeAttributeEntries(product.attributes_kwargs)
+    attributes: normalizeAttributeEntries(product.attributes_kwargs),
+    // The same attributes as a keyed map, kwargs merged over the raw
+    // `attributes` payload — technical keys (integration_model_renk…) often
+    // live only in the raw map, and analytics bridges key off them. Additive:
+    // the positional `attributes` list above is what the PDP blocks render.
+    attributesKeyed: buildKeyedAttributes(product)
   };
 };
 
+const buildKeyedAttributes = (
+  product: Product & UnknownRecord
+): Record<string, string> => {
+  const keyed: Record<string, string> = {};
+
+  const raw = product.attributes;
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    for (const [key, value] of Object.entries(raw as UnknownRecord)) {
+      const text = toStringValue(value);
+      if (text) keyed[key] = text;
+    }
+  }
+
+  const kwargs = product.attributes_kwargs;
+  if (kwargs && typeof kwargs === 'object' && !Array.isArray(kwargs)) {
+    for (const [key, entry] of Object.entries(kwargs as UnknownRecord)) {
+      const text = toStringValue(toRecord(entry).value);
+      if (text) keyed[key] = text;
+    }
+  }
+
+  return keyed;
+};
+
 /**
  * `breadcrumbData` is fetched next to the product by `getProductData()` and was
  * previously handed only to the brand's own PDP layout, which left the PDP the

package/src/theme-placeholder-wrapper.tsx

@@ -1,6 +1,11 @@
 'use client';
 
-import { useEffect, useState, useMemo } from 'react';
+import { useEffect, useState, useMemo, useRef } from 'react';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from './utils/analytics';
 import ThemeSection, { Section } from './theme-section';
 import SectionErrorBoundary from './components/section-error-boundary';
 import { safeDeepClone } from './utils/safe-clone';
@@ -389,6 +394,112 @@ export default function ThemePlaceholderWrapper({
     };
   }, [inheritedPageContext, initialPageContext]);
 
+  // GA4 page-scope ecommerce events (ZERO-4869), pushed off the page context
+  // rather than off any single block: what the page is ABOUT is a
+  // composition-level fact, so a PDP fires view_item and a basket fires
+  // view_cart no matter which blocks the designer placed. The guard is a ref,
+  // not a global: each client-side visit mounts a fresh slot and must refire,
+  // while re-renders of the same mount (breakpoint, context identity churn)
+  // must not — the acceptance criteria forbid duplicate hits.
+  const pushedPageEventKey = useRef<string | null>(null);
+  useEffect(() => {
+    if (isDesigner || !resolvedPageContext) return;
+
+    const context = resolvedPageContext as Record<string, any>;
+    const pageType = context.page?.type;
+
+    const emitOnce = (
+      key: string,
+      action: string,
+      detail: Parameters<typeof emitCommerceEvent>[1]
+    ) => {
+      const fullKey = `${action}:${key}`;
+      if (pushedPageEventKey.current === fullKey) return;
+      pushedPageEventKey.current = fullKey;
+      emitCommerceEvent(action, detail);
+    };
+
+    const basketLineItems = (lines: any[]) =>
+      lines.map((line: any) =>
+        buildCommerceItem(line?.product ?? line, {
+          quantity: Number(line?.quantity) || 1
+        })
+      );
+
+    if (pageType === 'product' && context.product) {
+      const item = buildCommerceItem(context.product);
+      if (!item) return;
+      emitOnce(String(item.id ?? item.name), 'view_item', {
+        currency: readItemsCurrency(context.product),
+        ...(typeof item.price === 'number' ? { value: item.price } : null),
+        items: [item]
+      });
+      return;
+    }
+
+    if (pageType === 'basket' && Array.isArray(context.basket?.items)) {
+      // The live storefronts report view_cart on an EMPTY basket too
+      // (value 0, items []), so the empty case is emitted rather than skipped.
+      const lines = context.basket.items;
+      emitOnce(
+        lines
+          .map(
+            (line: any) => `${line?.product?.pk ?? ''}x${line?.quantity ?? ''}`
+          )
+          .join(','),
+        'view_cart',
+        {
+          currency: readItemsCurrency(context.basket),
+          items: basketLineItems(lines)
+        }
+      );
+      return;
+    }
+
+    // Checkout funnel page signals. Only the moments the PAGE can know are
+    // emitted here — reaching checkout and completing the order. The
+    // step-level moments (add_shipping_info, add_payment_info) belong to the
+    // checkout machinery the brand mounts, which already reports them from
+    // its own code; a brand whose bridge would double-report these two page
+    // signals excludes them there (see Ga4BridgeOptions.excludeActions).
+    if (pageType === 'checkout' && Array.isArray(context.basket?.items)) {
+      const lines = context.basket.items;
+      if (lines.length === 0) return;
+      emitOnce(
+        lines
+          .map(
+            (line: any) => `${line?.product?.pk ?? ''}x${line?.quantity ?? ''}`
+          )
+          .join(','),
+        'begin_checkout',
+        {
+          currency: readItemsCurrency(context.basket),
+          items: basketLineItems(lines)
+        }
+      );
+      return;
+    }
+
+    if (
+      (pageType === 'order-success' || pageType === 'order') &&
+      Array.isArray(context.order?.items) &&
+      context.order.items.length > 0
+    ) {
+      const order = context.order;
+      const totalAmount = Number(String(order.totalAmount ?? '').replace(',', '.'));
+      emitOnce(String(order.number ?? order.id ?? ''), 'purchase', {
+        currency: readItemsCurrency(order),
+        ...(Number.isFinite(totalAmount) ? { value: totalAmount } : null),
+        transactionId: String(order.number ?? order.id ?? ''),
+        items: order.items.map((line: any) =>
+          buildCommerceItem(line?.product ?? line, {
+            quantity: Number(line?.quantity) || 1
+          })
+        )
+      });
+    }
+  }, [isDesigner, resolvedPageContext]);
+
   // Inject theme colors when settings change
   useEffect(() => {
     if (themeSettings) {

package/src/utils/__tests__/analytics.test.ts

@@ -0,0 +1,263 @@
+import {
+  attachGa4DataLayerBridge,
+  buildCommerceItem,
+  COMMERCE_EVENT_NAME,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../analytics';
+
+declare global {
+  interface Window {
+    dataLayer?: Array<Record<string, unknown>>;
+  }
+}
+
+describe('neutral commerce events (ZERO-4869)', () => {
+  let received: Array<Record<string, unknown>>;
+  let listener: (event: Event) => void;
+
+  beforeEach(() => {
+    received = [];
+    listener = (event) => received.push((event as CustomEvent).detail);
+    window.addEventListener(COMMERCE_EVENT_NAME, listener);
+  });
+
+  afterEach(() => {
+    window.removeEventListener(COMMERCE_EVENT_NAME, listener);
+  });
+
+  it('emits normalized commerce facts, not GA4 fields', () => {
+    emitCommerceEvent('add_to_cart', {
+      currency: 'try',
+      items: [
+        buildCommerceItem({
+          pk: 42,
+          sku: '4798121',
+          base_code: '2210',
+          name: 'GANT Polo',
+          price: '5499.00'
+        })
+      ]
+    });
+
+    expect(received).toEqual([
+      {
+        action: 'add_to_cart',
+        currency: 'try',
+        items: [
+          {
+            id: '2210',
+            baseCode: '2210',
+            sku: '4798121',
+            name: 'GANT Polo',
+            price: 5499,
+            quantity: 1
+          }
+        ]
+      }
+    ]);
+  });
+
+  it('builds an item off a normalized listing row', () => {
+    expect(
+      buildCommerceItem(
+        {
+          key: '54964',
+          productPk: 54964,
+          name: 'GANT Polo',
+          price: '5.499,00 TL',
+          priceAmount: 5499
+        },
+        { index: 2, listId: 'product_grid' }
+      )
+    ).toEqual({
+      id: '54964',
+      name: 'GANT Polo',
+      price: 5499,
+      quantity: 1,
+      index: 2,
+      listId: 'product_grid'
+    });
+  });
+
+  it('refuses an item that identifies nothing and skips empty emits', () => {
+    expect(buildCommerceItem({ image: 'x.jpg' })).toBeNull();
+
+    emitCommerceEvent('add_to_cart', { items: [null] });
+    expect(received).toEqual([]);
+  });
+
+  it('reads the per-product currency before the active one', () => {
+    expect(readItemsCurrency({ currency_type: 'usd' }, 'try')).toBe('usd');
+    expect(readItemsCurrency({}, 'try')).toBe('try');
+    expect(readItemsCurrency(null)).toBeUndefined();
+  });
+});
+
+describe('default GA4 dataLayer bridge', () => {
+  beforeEach(() => {
+    window.dataLayer = [];
+  });
+
+  it('maps neutral facts onto the flat brand GA4 shape', () => {
+    const detach = attachGa4DataLayerBridge();
+
+    emitCommerceEvent('add_to_cart', {
+      currency: 'try',
+      items: [
+        buildCommerceItem({
+          base_code: '2210',
+          sku: '4798121',
+          name: 'GANT Polo',
+          price: 5499
+        })
+      ]
+    });
+    emitCommerceEvent('search', { searchTerm: 'polo' });
+
+    expect(window.dataLayer).toEqual([
+      {
+        event: 'add_to_cart',
+        currency: 'try',
+        items: [
+          {
+            item_id: '2210',
+            item_name: 'GANT Polo',
+            price: 5499,
+            quantity: 1,
+            item_variant: '4798121'
+          }
+        ]
+      },
+      { event: 'search', search_term: 'polo' }
+    ]);
+
+    detach();
+  });
+
+  it('maps purchase with transaction id and value', () => {
+    const detach = attachGa4DataLayerBridge();
+
+    emitCommerceEvent('purchase', {
+      currency: 'try',
+      value: 5999,
+      transactionId: '#1042',
+      items: [buildCommerceItem({ pk: 1, name: 'A', price: 5999 })]
+    });
+
+    expect(window.dataLayer).toEqual([
+      {
+        event: 'purchase',
+        currency: 'try',
+        value: 5999,
+        transaction_id: '#1042',
+        items: [{ item_id: '1', item_name: 'A', price: 5999, quantity: 1 }]
+      }
+    ]);
+
+    detach();
+  });
+
+  it('does not forward excluded actions (brand-owned funnel moments)', () => {
+    const detach = attachGa4DataLayerBridge({
+      excludeActions: ['begin_checkout', 'purchase']
+    });
+
+    emitCommerceEvent('begin_checkout', {
+      items: [buildCommerceItem({ pk: 1, name: 'A' })]
+    });
+    emitCommerceEvent('select_item', {
+      items: [buildCommerceItem({ pk: 1, name: 'A' })]
+    });
+
+    expect(window.dataLayer?.map((e) => e.event)).toEqual(['select_item']);
+
+    detach();
+  });
+
+  it('transformItem tweaks one field and keeps the rest default', () => {
+    const detach = attachGa4DataLayerBridge({
+      transformItem: (item, facts) => ({
+        ...item,
+        item_category: facts.listName ?? 'unknown'
+      })
+    });
+
+    emitCommerceEvent('select_item', {
+      items: [
+        buildCommerceItem(
+          { pk: 1, name: 'A', price: 10 },
+          { listId: 'favourites', listName: 'Favourites' }
+        )
+      ]
+    });
+
+    expect(window.dataLayer?.[0]).toMatchObject({
+      event: 'select_item',
+      items: [
+        {
+          item_id: '1',
+          item_name: 'A',
+          item_list_id: 'favourites',
+          item_category: 'Favourites'
+        }
+      ]
+    });
+
+    detach();
+  });
+
+  it('transformEvent renames an event and can drop one', () => {
+    const detach = attachGa4DataLayerBridge({
+      transformEvent: (event) => {
+        if (event.event === 'add_to_wishlist') {
+          return { ...event, event: 'wishlist_add', wishlist_source: 'pdp' };
+        }
+        if (event.event === 'search') return null;
+        return event;
+      }
+    });
+
+    emitCommerceEvent('add_to_wishlist', {
+      items: [buildCommerceItem({ pk: 1, name: 'A' })]
+    });
+    emitCommerceEvent('search', { searchTerm: 'polo' });
+
+    expect(window.dataLayer?.map((e) => e.event)).toEqual(['wishlist_add']);
+    expect(window.dataLayer?.[0]).toMatchObject({ wishlist_source: 'pdp' });
+
+    detach();
+  });
+
+  it('a throwing transform falls back to the default push', () => {
+    const detach = attachGa4DataLayerBridge({
+      transformEvent: () => {
+        throw new Error('brand bug');
+      },
+      transformItem: () => {
+        throw new Error('brand bug');
+      }
+    });
+
+    emitCommerceEvent('add_to_cart', {
+      items: [buildCommerceItem({ pk: 1, name: 'A', price: 10 })]
+    });
+
+    expect(window.dataLayer).toEqual([
+      {
+        event: 'add_to_cart',
+        items: [{ item_id: '1', item_name: 'A', price: 10, quantity: 1 }]
+      }
+    ]);
+
+    detach();
+  });
+
+  it('is silent for brands that attached nothing', () => {
+    emitCommerceEvent('add_to_cart', {
+      items: [buildCommerceItem({ pk: 1, name: 'A' })]
+    });
+
+    expect(window.dataLayer).toEqual([]);
+  });
+});

package/src/utils/analytics.ts

@@ -0,0 +1,339 @@
+import { parseAmount } from '../blocks/commerce-format';
+
+/**
+ * Neutral commerce signal layer (ZERO-4869).
+ *
+ * The theme ships to every brand, and analytics SCHEMA is a brand decision —
+ * so the blocks never talk to GTM directly. At each commerce moment (an add
+ * to cart that succeeded, a product card click, a viewed listing) they emit a
+ * `pz:commerce` CustomEvent carrying normalized commerce FACTS, and whatever
+ * the brand mounted decides what becomes of them: the default GA4 bridge
+ * below, the brand's own mapper in its repo, a different TMS, or nothing at
+ * all — a brand that attaches no listener gets exactly zero behavior change.
+ *
+ * The emit is fire-and-forget: analytics must never take a block down, so a
+ * malformed product just drops the item and an items-carrying action with no
+ * surviving item is not emitted at all.
+ */
+
+export const COMMERCE_EVENT_NAME = 'pz:commerce';
+
+/** Normalized product facts. Neutral names — GA4's item_* is the bridge's job. */
+export interface CommerceItem {
+  id?: string;
+  baseCode?: string;
+  sku?: string;
+  name?: string;
+  price?: number;
+  /** The struck list price, for bridges that report a discount amount. */
+  retailPrice?: number;
+  quantity?: number;
+  index?: number;
+  listId?: string;
+  listName?: string;
+  /**
+   * The product's keyed commerce attributes (`integration_renk_tonu`,
+   * `integration_model_renk`, size…), exactly as commerce names them. Brand
+   * bridges derive their own fields from these — the live GANT schema builds
+   * item_id and item_variant off them.
+   */
+  attributes?: Record<string, string>;
+}
+
+export interface CommerceEventDetail {
+  action: string;
+  currency?: string;
+  value?: number;
+  items?: CommerceItem[];
+  searchTerm?: string;
+  method?: string;
+  transactionId?: string;
+  [key: string]: unknown;
+}
+
+const toText = (value: unknown): string | undefined => {
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+};
+
+/**
+ * One commerce item off whatever product-shaped object a block holds: a raw
+ * commerce payload (`sku`, `base_code`, `retail_price`), a normalized listing
+ * row (`productPk`, `priceAmount`) or a ThemeProduct. Null when nothing
+ * identifies the product — an item that names nothing is noise for every
+ * bridge downstream.
+ */
+/**
+ * The keyed attribute map off whatever shape the source carries: a raw payload
+ * (`attributes_kwargs` of `{value}` records over a raw `attributes` map), a
+ * normalized listing row (already keyed strings) or a ThemeProduct (an array
+ * of `{key, value}` entries).
+ */
+const readItemAttributes = (
+  source: Record<string, unknown>
+): Record<string, string> | undefined => {
+  const keyed: Record<string, string> = {};
+
+  // A page-context product carries the merged map ready-made.
+  const preKeyed = source.attributesKeyed;
+  if (preKeyed && typeof preKeyed === 'object' && !Array.isArray(preKeyed)) {
+    for (const [key, value] of Object.entries(
+      preKeyed as Record<string, unknown>
+    )) {
+      const text = toText(value);
+      if (text) keyed[key] = text;
+    }
+  }
+
+  const kwargs = source.attributes_kwargs;
+  if (kwargs && typeof kwargs === 'object' && !Array.isArray(kwargs)) {
+    for (const [key, entry] of Object.entries(
+      kwargs as Record<string, unknown>
+    )) {
+      const value = toText((entry as Record<string, unknown>)?.value);
+      if (value) keyed[key] = value;
+    }
+  }
+
+  const raw = source.attributes;
+  if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      const record = entry as Record<string, unknown>;
+      const key = toText(record?.key);
+      const value = toText(record?.value);
+      if (key && value) keyed[key] = value;
+    }
+  } else if (raw && typeof raw === 'object') {
+    for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+      const text = toText(value);
+      if (text) keyed[key] = text;
+    }
+  }
+
+  return Object.keys(keyed).length > 0 ? keyed : undefined;
+};
+
+export const buildCommerceItem = (
+  source: Record<string, unknown> | null | undefined,
+  extra: Partial<CommerceItem> = {}
+): CommerceItem | null => {
+  if (!source || typeof source !== 'object') return null;
+
+  const baseCode = toText(source.base_code);
+  const sku = toText(source.sku);
+  const id =
+    baseCode ?? sku ?? toText(source.productPk) ?? toText(source.pk);
+  const name = toText(source.name) ?? toText(source.title);
+
+  if (!id && !name) return null;
+
+  const amount =
+    parseAmount(source.priceAmount) ??
+    parseAmount(source.price) ??
+    parseAmount((source.active_price as Record<string, unknown>)?.price);
+  const retailAmount =
+    parseAmount(source.retailPriceAmount) ??
+    parseAmount(source.retail_price) ??
+    parseAmount(source.retailPrice) ??
+    parseAmount(
+      (source.active_price as Record<string, unknown>)?.retail_price
+    );
+  const attributes = readItemAttributes(source);
+
+  return {
+    ...(id ? { id } : null),
+    ...(baseCode ? { baseCode } : null),
+    ...(sku ? { sku } : null),
+    ...(name ? { name } : null),
+    ...(amount !== null ? { price: amount } : null),
+    ...(retailAmount !== null ? { retailPrice: retailAmount } : null),
+    quantity: 1,
+    ...(attributes ? { attributes } : null),
+    ...extra
+  };
+};
+
+export const readItemsCurrency = (
+  source: Record<string, unknown> | null | undefined,
+  fallback?: string
+): string | undefined =>
+  toText(source?.currency_type) ?? toText(source?.currency) ?? toText(fallback);
+
+/**
+ * Emit one commerce moment. `items` may carry nulls from the builder; they are
+ * dropped, and an action whose items ALL dropped is not emitted.
+ */
+export const emitCommerceEvent = (
+  action: string,
+  detail: Omit<CommerceEventDetail, 'action'> & {
+    items?: Array<CommerceItem | null>;
+  } = {}
+): void => {
+  if (typeof window === 'undefined') return;
+
+  try {
+    const { items, value, currency, ...rest } = detail;
+    const presentItems = items?.filter(
+      (item): item is CommerceItem => item !== null
+    );
+    // An empty basket's view_cart is a real report (the live storefronts push
+    // it with items: []); only item-CARRYING actions with nothing left after
+    // the builder are dropped.
+    if (
+      items &&
+      items.length > 0 &&
+      (!presentItems || presentItems.length === 0)
+    ) {
+      return;
+    }
+
+    window.dispatchEvent(
+      new CustomEvent<CommerceEventDetail>(COMMERCE_EVENT_NAME, {
+        detail: {
+          action,
+          ...(currency ? { currency } : null),
+          ...(typeof value === 'number' && Number.isFinite(value)
+            ? { value }
+            : null),
+          ...(presentItems ? { items: presentItems } : null),
+          ...rest
+        }
+      })
+    );
+  } catch {
+    // Observability must never take a block down with it.
+  }
+};
+
+/* ------------------------------------------------------------------------ *
+ * Default GA4 dataLayer bridge.
+ *
+ * A brand opts in by CALLING this from its own code (client root/template) —
+ * ownership of the schema stays in the brand repo even when the default
+ * mapping is used. The shape is the flat one the hand-coded brand storefronts
+ * already push (`{event, currency, value, items}`, no `ecommerce` wrapper),
+ * with the same field sources: item_id = base_code first, sku on item_variant.
+ * ------------------------------------------------------------------------ */
+
+declare global {
+  interface Window {
+    dataLayer?: Array<Record<string, unknown>>;
+  }
+}
+
+export interface Ga4BridgeOptions {
+  /**
+   * Actions this bridge must NOT forward — for moments the brand already
+   * reports from its own code. GANT excludes the checkout funnel: its
+   * begin_checkout/add_shipping_info/add_payment_info/purchase pushes live in
+   * the brand checkout views and forwarding the page-level signals too would
+   * double-report the funnel.
+   */
+  excludeActions?: string[];
+  /**
+   * Small per-brand differences without rewriting the whole mapping: receives
+   * the default GA4 item plus the neutral facts it was built from, returns the
+   * item to push. Add a field, rename one, drop one — the rest stays default.
+   */
+  transformItem?: (
+    item: Record<string, unknown>,
+    facts: CommerceItem,
+    detail: CommerceEventDetail
+  ) => Record<string, unknown>;
+  /**
+   * Same idea at the event level: receives the default GA4 event object plus
+   * the neutral detail, returns what to push — or null to drop this one event.
+   * A transform that throws is ignored and the default event is pushed, so a
+   * brand callback bug can never silence analytics.
+   */
+  transformEvent?: (
+    event: Record<string, unknown>,
+    detail: CommerceEventDetail
+  ) => Record<string, unknown> | null;
+}
+
+const toGa4Item = (item: CommerceItem): Record<string, unknown> => ({
+  ...(item.baseCode ?? item.sku ?? item.id
+    ? { item_id: item.baseCode ?? item.sku ?? item.id }
+    : null),
+  ...(item.name ? { item_name: item.name } : null),
+  ...(typeof item.price === 'number' ? { price: item.price } : null),
+  quantity: item.quantity ?? 1,
+  ...(item.sku ? { item_variant: item.sku } : null),
+  ...(typeof item.index === 'number' ? { index: item.index } : null),
+  ...(item.listId ? { item_list_id: item.listId } : null),
+  ...(item.listName ? { item_list_name: item.listName } : null)
+});
+
+let ga4BridgeDetach: (() => void) | null = null;
+
+/** Attach the default GA4 mapping. Idempotent; returns a detach function. */
+export const attachGa4DataLayerBridge = (
+  options: Ga4BridgeOptions = {}
+): (() => void) => {
+  if (typeof window === 'undefined') return () => {};
+  if (ga4BridgeDetach) return ga4BridgeDetach;
+
+  const excluded = new Set(options.excludeActions ?? []);
+
+  const onCommerce = (event: Event) => {
+    const detail = (event as CustomEvent<CommerceEventDetail>).detail;
+    if (!detail?.action || excluded.has(detail.action)) return;
+
+    const {
+      action,
+      currency,
+      value,
+      items,
+      searchTerm,
+      method,
+      transactionId
+    } = detail;
+
+    try {
+      const mapItem = (item: CommerceItem): Record<string, unknown> => {
+        const ga4Item = toGa4Item(item);
+        if (!options.transformItem) return ga4Item;
+        try {
+          return options.transformItem(ga4Item, item, detail);
+        } catch {
+          return ga4Item;
+        }
+      };
+
+      let ga4Event: Record<string, unknown> | null = {
+        event: action,
+        ...(currency ? { currency } : null),
+        ...(typeof value === 'number' ? { value } : null),
+        ...(items && items.length > 0 ? { items: items.map(mapItem) } : null),
+        ...(searchTerm ? { search_term: searchTerm } : null),
+        ...(method ? { method } : null),
+        ...(transactionId ? { transaction_id: transactionId } : null)
+      };
+
+      if (options.transformEvent) {
+        try {
+          ga4Event = options.transformEvent(ga4Event, detail);
+        } catch {
+          // Keep the default event — a brand callback bug must not mute analytics.
+        }
+      }
+      if (!ga4Event) return;
+
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push(ga4Event);
+    } catch {
+      // Never let a mapping failure surface as a storefront error.
+    }
+  };
+
+  window.addEventListener(COMMERCE_EVENT_NAME, onCommerce);
+  ga4BridgeDetach = () => {
+    window.removeEventListener(COMMERCE_EVENT_NAME, onCommerce);
+    ga4BridgeDetach = null;
+  };
+  return ga4BridgeDetach;
+};