@shop-on/theme-react 0.4.0 → 0.6.0

package/dist/analytics.d.ts

@@ -1,3 +1,4 @@
+import { EventSourceCart, EventSourceLine } from "./storefront-events.js";
 //#region src/analytics.d.ts
 export type EventProperties = Record<string, unknown>;
 export declare function trackVisit(properties?: EventProperties): Promise<void>;
@@ -19,12 +20,22 @@ export declare function toInt(value: unknown): number | null;
  *  `recommendation_shown` / `recommendation_clicked` pair, so the two event
  *  families stay mutually exclusive by surface and nothing double-counts. */
 export type ProductListType = "collection" | "search";
-/** Fires `product_added_to_cart` after a successful add. Wired once inside
- *  `use-cart`, so every add surface (buy buttons, quick add) is covered. */
+/** Reports one successful add, both ways every listener hears it:
+ *
+ *  - `shopon:cart:added` on `window`, the public event merchant scripts and
+ *    the platform's marketing script read (GA4 `add_to_cart` is built from it
+ *    alone). Fired in the editor preview too, like every theme event: it is a
+ *    DOM event, not a beacon.
+ *  - the `product_added_to_cart` beacon to Rails, which also feeds Meta CAPI.
+ *
+ *  Call it once per added variant, from `use-cart` after the cart has been
+ *  revalidated, so a listener reading the DOM sees the new cart. `line` is the
+ *  line the variant landed on in the result's cart; `quantity` is the quantity
+ *  ADDED, not the line's. */
 export declare function trackProductAddedToCart(input: {
-  productId: string | number | null | undefined;
-  variantId: string | number | null | undefined;
+  line: EventSourceLine;
   quantity: number;
+  cart: EventSourceCart;
 }): void;
 /** Fires `product_removed_from_cart` on line removal — the funnel-drop signal
  *  symmetric to the add event, so it carries the same join keys. */

package/dist/analytics.js

@@ -1,3 +1,4 @@
+import { toEventCart, toEventProduct, toEventVariant } from "./storefront-events.js";
 //#region src/analytics.ts
 const VISIT_KEY = "ahoy_visit";
 const VISITOR_KEY = "ahoy_visitor";
@@ -109,16 +110,36 @@ function toInt(value) {
 	const parsed = Number.parseInt(String(value ?? ""), 10);
 	return Number.isInteger(parsed) ? parsed : null;
 }
-/** Fires `product_added_to_cart` after a successful add. Wired once inside
-*  `use-cart`, so every add surface (buy buttons, quick add) is covered. */
+/** Reports one successful add, both ways every listener hears it:
+*
+*  - `shopon:cart:added` on `window`, the public event merchant scripts and
+*    the platform's marketing script read (GA4 `add_to_cart` is built from it
+*    alone). Fired in the editor preview too, like every theme event: it is a
+*    DOM event, not a beacon.
+*  - the `product_added_to_cart` beacon to Rails, which also feeds Meta CAPI.
+*
+*  Call it once per added variant, from `use-cart` after the cart has been
+*  revalidated, so a listener reading the DOM sees the new cart. `line` is the
+*  line the variant landed on in the result's cart; `quantity` is the quantity
+*  ADDED, not the line's. */
 function trackProductAddedToCart(input) {
-	const productId = toInt(input.productId);
+	const { line, quantity, cart } = input;
+	if (typeof window !== "undefined") {
+		const detail = {
+			product: toEventProduct(line),
+			variant: toEventVariant(line),
+			quantity,
+			cart: toEventCart(cart)
+		};
+		window.dispatchEvent(new CustomEvent("shopon:cart:added", { detail }));
+	}
+	const productId = toInt(line.variant.product.id);
 	if (productId === null) return;
-	const variantId = toInt(input.variantId);
+	const variantId = toInt(line.variant.id);
 	track("product_added_to_cart", {
 		product_id: productId,
 		...variantId !== null ? { variant_id: variantId } : {},
-		quantity: input.quantity
+		quantity
 	});
 }
 /** Fires `product_removed_from_cart` on line removal — the funnel-drop signal

package/dist/editor-preview-bridge-utils.d.ts

@@ -29,4 +29,13 @@ export declare function forwardsFromPreview(command: EditorCommand, target: Even
   textSelected: boolean;
   selectionShown: boolean;
 }): boolean;
+/** A teammate's selection, drawn in their colour under this editor's own. */
+export interface EditorPeerMark {
+  item: EditorSelectedItem;
+  color: string;
+  name: string;
+}
+/** The admin's `theme-editor:peers` payload, keeping only well-formed marks.
+ *  Null when it isn't a list at all. */
+export declare function parsePeerMarks(raw: unknown): EditorPeerMark[] | null;
 //#endregion

package/dist/editor-preview-bridge-utils.js

@@ -81,5 +81,28 @@ function forwardsFromPreview(command, target, ctx) {
 	}
 	return !(command === "copy" && ctx.textSelected);
 }
+const MAX_PEER_MARKS = 12;
+const MAX_PEER_NAME = 60;
+const PEER_COLOR_RE = /^(#[0-9a-f]{3,8}|(rgba?|hsla?|oklch|oklab|lab|lch)\([0-9a-z.%\s,/+-]*\))$/i;
+/** The admin's `theme-editor:peers` payload, keeping only well-formed marks.
+*  Null when it isn't a list at all. */
+function parsePeerMarks(raw) {
+	if (!Array.isArray(raw)) return null;
+	const out = [];
+	for (const entry of raw) {
+		if (out.length === MAX_PEER_MARKS) break;
+		if (!entry || typeof entry !== "object") continue;
+		const v = entry;
+		const item = parseSelected(v.item);
+		if (!item || typeof v.color !== "string" || !PEER_COLOR_RE.test(v.color.trim())) continue;
+		const name = typeof v.name === "string" ? v.name.trim().slice(0, MAX_PEER_NAME) : "";
+		out.push({
+			item,
+			color: v.color.trim(),
+			name
+		});
+	}
+	return out;
+}
 //#endregion
-export { forwardsFromPreview, parseSelected, readClickTarget, sameItem };
+export { forwardsFromPreview, parsePeerMarks, parseSelected, readClickTarget, sameItem };

package/dist/editor-preview-bridge.js

@@ -1,6 +1,6 @@
 "use client";
-import { forwardsFromPreview, parseSelected, readClickTarget, sameItem } from "./editor-preview-bridge-utils.js";
-import { jsx } from "react/jsx-runtime";
+import { forwardsFromPreview, parsePeerMarks, parseSelected, readClickTarget, sameItem } from "./editor-preview-bridge-utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { editorCommand } from "@shop-on/theme-contract";
 //#region src/editor-preview-bridge.tsx
@@ -100,10 +100,38 @@ const OVERLAY_RECT_STYLE = {
 	width: "0",
 	height: "0"
 };
+const PEER_RING_STEP_PX = 3;
+const PEER_LABEL_HEIGHT_PX = 18;
+const PEER_RECT_STYLE = {
+	...OVERLAY_RECT_STYLE,
+	boxShadow: "none"
+};
+const PEER_LABEL_STYLE = {
+	position: "absolute",
+	left: "-2px",
+	height: `${PEER_LABEL_HEIGHT_PX}px`,
+	padding: "0 6px",
+	borderRadius: "4px",
+	color: "#fff",
+	font: "500 11px/18px system-ui, sans-serif",
+	whiteSpace: "nowrap"
+};
+function createPeerRect() {
+	const div = document.createElement("div");
+	Object.assign(div.style, PEER_RECT_STYLE);
+	const label = document.createElement("span");
+	Object.assign(label.style, PEER_LABEL_STYLE);
+	div.appendChild(label);
+	return div;
+}
 function EditorPreviewBridge({ preview }) {
 	const isPreview = typeof preview === "string" && preview !== "";
 	const [selected, setSelected] = useState(null);
 	const [inspectorMode, setInspectorMode] = useState(true);
+	const peersRef = useRef([]);
+	const redrawRef = useRef(null);
+	const overlayRootRef = useRef(null);
+	const peerLayerRef = useRef(null);
 	const overlayContainerRef = useRef(null);
 	const selectedRef = useRef(null);
 	const pendingScrollRef = useRef(null);
@@ -126,6 +154,13 @@ function EditorPreviewBridge({ preview }) {
 				setInspectorMode(e.data.enabled);
 				return;
 			}
+			if (e.data.type === "theme-editor:peers") {
+				const marks = parsePeerMarks(e.data.peers);
+				if (!marks) return;
+				peersRef.current = marks;
+				redrawRef.current?.();
+				return;
+			}
 			if (e.data.type === "theme-editor:mutate") {
 				if (e.data.action !== "add") return;
 				const item = parseSelected(e.data.item);
@@ -209,7 +244,8 @@ function EditorPreviewBridge({ preview }) {
 	useEffect(() => {
 		if (!isPreview) return;
 		const container = overlayContainerRef.current;
-		if (!container) return;
+		const peerLayer = peerLayerRef.current;
+		if (!container || !peerLayer) return;
 		function ensureRectCount(n) {
 			while (container.childElementCount < n) {
 				const div = document.createElement("div");
@@ -243,6 +279,7 @@ function EditorPreviewBridge({ preview }) {
 				div.style.width = `${r.width}px`;
 				div.style.height = `${r.height}px`;
 			});
+			drawPeers(targets);
 			const rect = firstRect && firstRect.width > 0 && firstRect.height > 0 ? {
 				top: firstRect.top,
 				left: firstRect.left,
@@ -273,6 +310,38 @@ function EditorPreviewBridge({ preview }) {
 				scrollItemIntoView(settleItem);
 			}
 		}
+		function drawPeers(ownTargets) {
+			const rings = /* @__PURE__ */ new Map();
+			for (const t of ownTargets) rings.set(t, 1);
+			const marks = inspectorModeRef.current ? peersRef.current : [];
+			let n = 0;
+			for (const mark of marks) {
+				let named = false;
+				findEditorTargets(mark.item).forEach((t) => {
+					const r = t.getBoundingClientRect();
+					if (r.width === 0 || r.height === 0) return;
+					const depth = rings.get(t) ?? 0;
+					rings.set(t, depth + 1);
+					const out = depth * PEER_RING_STEP_PX;
+					if (peerLayer.childElementCount <= n) peerLayer.appendChild(createPeerRect());
+					const div = peerLayer.children[n++];
+					div.style.display = "block";
+					div.style.top = `${r.top - out}px`;
+					div.style.left = `${r.left - out}px`;
+					div.style.width = `${r.width + out * 2}px`;
+					div.style.height = `${r.height + out * 2}px`;
+					div.style.borderColor = mark.color;
+					const label = div.firstElementChild;
+					const showName = !named && mark.name !== "";
+					if (showName) named = true;
+					label.style.display = showName ? "block" : "none";
+					label.style.top = r.top - out < PEER_LABEL_HEIGHT_PX ? "0" : `-${PEER_LABEL_HEIGHT_PX}px`;
+					label.style.backgroundColor = mark.color;
+					if (label.textContent !== mark.name) label.textContent = mark.name;
+				});
+			}
+			while (peerLayer.childElementCount > n) peerLayer.removeChild(peerLayer.lastElementChild);
+		}
 		function schedule(fromResize) {
 			if (fromResize) resizePending = true;
 			if (rafPending) return;
@@ -280,12 +349,13 @@ function EditorPreviewBridge({ preview }) {
 			requestAnimationFrame(update);
 		}
 		const scheduleFromContent = () => schedule(false);
+		redrawRef.current = scheduleFromContent;
 		const scheduleFromResize = () => schedule(true);
 		update();
 		const resize = new ResizeObserver(scheduleFromResize);
 		resize.observe(document.documentElement);
 		const mut = new MutationObserver((records) => {
-			const overlayNode = overlayContainerRef.current;
+			const overlayNode = overlayRootRef.current;
 			if (overlayNode && records.every((r) => overlayNode.contains(r.target))) return;
 			schedule(false);
 		});
@@ -298,6 +368,7 @@ function EditorPreviewBridge({ preview }) {
 		window.addEventListener("scroll", scheduleFromContent, true);
 		window.addEventListener("resize", scheduleFromResize);
 		return () => {
+			redrawRef.current = null;
 			resize.disconnect();
 			mut.disconnect();
 			window.removeEventListener("scroll", scheduleFromContent, true);
@@ -309,10 +380,11 @@ function EditorPreviewBridge({ preview }) {
 		inspectorMode
 	]);
 	if (!isPreview) return null;
-	return /* @__PURE__ */ jsx("div", {
-		ref: overlayContainerRef,
+	return /* @__PURE__ */ jsxs("div", {
+		ref: overlayRootRef,
 		style: OVERLAY_CONTAINER_STYLE,
-		"aria-hidden": true
+		"aria-hidden": true,
+		children: [/* @__PURE__ */ jsx("div", { ref: peerLayerRef }), /* @__PURE__ */ jsx("div", { ref: overlayContainerRef })]
 	});
 }
 //#endregion

package/dist/index.d.ts

@@ -7,6 +7,6 @@ import { ProductJsonLd, ProductJsonLdProps } from "./product-json-ld.js";
 import { WebsiteJsonLd, WebsiteJsonLdProps } from "./website-json-ld.js";
 import { PreviewSearch, bouncePreviewToNotFound } from "./preview-guard.js";
 import { retainPreviewSearch } from "./preview-search-middleware.js";
-import { ArticleSchemaSource, BlockInstance, LayoutComponent, ProductSchemaSource, SectionGroupConfig, TemplateJSON, TemplateRendererInstance, TemplateRendererLoaders, TemplateSeoSource, createTemplateRenderer } from "./template-renderer.js";
+import { ArticleSchemaSource, BlockInstance, ClosestScope, LayoutComponent, ProductSchemaSource, SectionGroupConfig, TemplateJSON, TemplateRendererInstance, TemplateRendererLoaders, TemplateSeoSource, createTemplateRenderer, withClosestOverlays } from "./template-renderer.js";
 import { useIsoLayoutEffect } from "./use-iso-layout-effect.js";
-export { ArticleJsonLd, type ArticleJsonLdProps, type ArticleSchemaSource, type BlockInstance, BreadcrumbJsonLd, type BreadcrumbJsonLdProps, EditorPreviewBridge, type EditorSelectedItem, FaqJsonLd, type FaqJsonLdItem, type FaqJsonLdProps, type LayoutComponent, type PreviewSearch, ProductJsonLd, type ProductJsonLdProps, type ProductSchemaSource, type SectionGroupConfig, type TemplateJSON, type TemplateRendererInstance, type TemplateRendererLoaders, type TemplateSeoSource, WebsiteJsonLd, type WebsiteJsonLdProps, bouncePreviewToNotFound, createTemplateRenderer, parseSelected, readClickTarget, retainPreviewSearch, sameItem, useIsoLayoutEffect };
+export { ArticleJsonLd, type ArticleJsonLdProps, type ArticleSchemaSource, type BlockInstance, BreadcrumbJsonLd, type BreadcrumbJsonLdProps, ClosestScope, EditorPreviewBridge, type EditorSelectedItem, FaqJsonLd, type FaqJsonLdItem, type FaqJsonLdProps, type LayoutComponent, type PreviewSearch, ProductJsonLd, type ProductJsonLdProps, type ProductSchemaSource, type SectionGroupConfig, type TemplateJSON, type TemplateRendererInstance, type TemplateRendererLoaders, type TemplateSeoSource, WebsiteJsonLd, type WebsiteJsonLdProps, bouncePreviewToNotFound, createTemplateRenderer, parseSelected, readClickTarget, retainPreviewSearch, sameItem, useIsoLayoutEffect, withClosestOverlays };

package/dist/index.js

@@ -7,6 +7,6 @@ import { parseSelected, readClickTarget, sameItem } from "./editor-preview-bridg
 import { EditorPreviewBridge } from "./editor-preview-bridge.js";
 import { bouncePreviewToNotFound } from "./preview-guard.js";
 import { retainPreviewSearch } from "./preview-search-middleware.js";
-import { createTemplateRenderer } from "./template-renderer.js";
+import { ClosestScope, createTemplateRenderer, withClosestOverlays } from "./template-renderer.js";
 import { useIsoLayoutEffect } from "./use-iso-layout-effect.js";
-export { ArticleJsonLd, BreadcrumbJsonLd, EditorPreviewBridge, FaqJsonLd, ProductJsonLd, WebsiteJsonLd, bouncePreviewToNotFound, createTemplateRenderer, parseSelected, readClickTarget, retainPreviewSearch, sameItem, useIsoLayoutEffect };
+export { ArticleJsonLd, BreadcrumbJsonLd, ClosestScope, EditorPreviewBridge, FaqJsonLd, ProductJsonLd, WebsiteJsonLd, bouncePreviewToNotFound, createTemplateRenderer, parseSelected, readClickTarget, retainPreviewSearch, sameItem, useIsoLayoutEffect, withClosestOverlays };

package/dist/recommendation-tracking.d.ts

@@ -0,0 +1,33 @@
+import { RecommendationAttribution } from "./analytics.js";
+import { MouseEvent } from "react";
+//#region src/recommendation-tracking.d.ts
+/** The product a rail recommends for: the product page's, or the first line
+ * of the cart. */
+export type RecommendationReference = {
+  id?: string | number | null;
+  handle: string;
+};
+/** Impression + click tracking for a recommendation rail. Spread the returned
+ * `{ ref, onClickCapture }` onto an element around the rail's cards, and mark
+ * each card with `data-product-id` / `data-product-handle` / `data-position`.
+ * With no `reference` nothing is reported: products picked by hand are not
+ * recommendations.
+ *
+ * `recommendation_shown` fires per card once half of it is in view — a rail
+ * scrolls sideways, so a card past its edge was not seen — and once per
+ * reference product, however often the rail re-renders.
+ *
+ * `recommendation_clicked` fires in the CAPTURE phase for a click that lands
+ * on a link inside a card, so the beacon leaves in the same tick as the
+ * navigation and an add-to-cart button is not a click-through. */
+export declare function useRecommendationTracking({ reference, intent, signature }: {
+  reference: RecommendationReference | null | undefined;
+  intent: RecommendationAttribution["intent"];
+  /** The cards on show, as one string (their handles, joined): a new set is
+   * observed afresh. */
+  signature: string;
+}): {
+  ref: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+  onClickCapture: (event: MouseEvent<HTMLElement>) => void;
+};
+//#endregion

package/dist/recommendation-tracking.js

@@ -0,0 +1,78 @@
+import { ensureVisit, trackRecommendationClicked, trackRecommendationShown } from "./analytics.js";
+import { useEffect, useRef, useState } from "react";
+//#region src/recommendation-tracking.ts
+function cardAttribution(card, reference, intent) {
+	const position = Number.parseInt(card.dataset.position ?? "", 10);
+	return {
+		referenceProductId: reference.id,
+		referenceProductHandle: reference.handle,
+		recommendedProductId: card.dataset.productId,
+		recommendedProductHandle: card.dataset.productHandle ?? "",
+		intent,
+		position: Number.isInteger(position) ? position : 0
+	};
+}
+/** Impression + click tracking for a recommendation rail. Spread the returned
+* `{ ref, onClickCapture }` onto an element around the rail's cards, and mark
+* each card with `data-product-id` / `data-product-handle` / `data-position`.
+* With no `reference` nothing is reported: products picked by hand are not
+* recommendations.
+*
+* `recommendation_shown` fires per card once half of it is in view — a rail
+* scrolls sideways, so a card past its edge was not seen — and once per
+* reference product, however often the rail re-renders.
+*
+* `recommendation_clicked` fires in the CAPTURE phase for a click that lands
+* on a link inside a card, so the beacon leaves in the same tick as the
+* navigation and an add-to-cart button is not a click-through. */
+function useRecommendationTracking({ reference, intent, signature }) {
+	const [node, ref] = useState(null);
+	const shown = useRef(/* @__PURE__ */ new Set());
+	const referenceId = reference?.id;
+	const referenceHandle = reference?.handle;
+	useEffect(() => {
+		if (!node || !referenceHandle || !signature) return;
+		ensureVisit();
+		const current = {
+			id: referenceId,
+			handle: referenceHandle
+		};
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) {
+				if (!entry.isIntersecting) continue;
+				const card = entry.target;
+				observer.unobserve(card);
+				const key = `${referenceHandle}:${card.dataset.productId}`;
+				if (shown.current.has(key)) continue;
+				shown.current.add(key);
+				trackRecommendationShown(cardAttribution(card, current, intent));
+			}
+		}, { threshold: .5 });
+		for (const card of node.querySelectorAll("[data-product-id]")) observer.observe(card);
+		return () => observer.disconnect();
+	}, [
+		node,
+		referenceId,
+		referenceHandle,
+		intent,
+		signature
+	]);
+	const onClickCapture = (event) => {
+		if (!referenceHandle) return;
+		const target = event.target;
+		const card = target?.closest("[data-product-id]");
+		if (!card) return;
+		const anchor = target?.closest("a");
+		if (!anchor || !card.contains(anchor)) return;
+		trackRecommendationClicked(cardAttribution(card, {
+			id: referenceId,
+			handle: referenceHandle
+		}, intent));
+	};
+	return {
+		ref,
+		onClickCapture
+	};
+}
+//#endregion
+export { useRecommendationTracking };

package/dist/storefront-events.d.ts

@@ -0,0 +1,86 @@
+import { Money } from "@shop-on/theme-runtime/money";
+//#region src/storefront-events.d.ts
+/**
+ * The cart as merchant scripts see it, in every `shopon:cart:*` event.
+ *
+ * A PUBLIC CONTRACT: merchant scripts, app sections and the platform's
+ * marketing script (GA4 `add_to_cart`, `Shop::Marketing::PixelScript`) listen
+ * on these, so a field can't be renamed once shipped. One copy, here, so every
+ * theme sends the same shape and a listener survives a theme switch.
+ *
+ * Hand-mapped, never the server's `CartData`: that type carries fields that
+ * exist for a theme's own rendering (image `srcset` / `thumbhash`, the
+ * storefront-scope `visible` flag) and grows whenever a theme needs one.
+ * Emitting it raw would publish all of that. House rules: images are URL
+ * strings, prices are `Money`, optional values are `null`, never absent.
+ */
+export type EventProduct = {
+  id: string | null;
+  handle: string;
+  title: string;
+  image: string | null;
+};
+export type EventVariant = {
+  id: string;
+  title: string;
+  sku: string | null;
+  price: Money;
+  image: string | null;
+};
+export type EventCartLine = {
+  id: string;
+  quantity: number;
+  cost: Money;
+  product: EventProduct;
+  variant: EventVariant;
+};
+export type EventCart = {
+  id: string;
+  totalQuantity: number;
+  subtotalAmount: Money;
+  discountAmount: Money;
+  lines: EventCartLine[];
+};
+/** `shopon:cart:added`'s `detail`. `quantity` is the quantity ADDED, not the
+ *  resulting line quantity: adding 1 to a line that held 2 reports 1. */
+export type CartAddedDetail = {
+  product: EventProduct;
+  variant: EventVariant;
+  quantity: number;
+  cart: EventCart;
+};
+/** The slice of `@shop-on/theme-server/cart`'s `CartLine` the events read —
+ *  structural, so this package needs no server dependency. */
+export type EventSourceLine = {
+  id: string;
+  quantity: number;
+  cost: Money;
+  variant: {
+    id: string;
+    title: string;
+    sku: string | null;
+    price: Money;
+    image: {
+      url: string | null;
+    } | null;
+    product: {
+      id: string | null;
+      handle: string;
+      title: string;
+      image: {
+        url: string | null;
+      } | null;
+    };
+  };
+};
+export type EventSourceCart = {
+  id: string;
+  totalQuantity: number;
+  subtotalAmount: Money;
+  discountAmount: Money;
+  lines: EventSourceLine[];
+};
+export declare function toEventProduct(line: EventSourceLine): EventProduct;
+export declare function toEventVariant(line: EventSourceLine): EventVariant;
+export declare function toEventCart(cart: EventSourceCart): EventCart;
+//#endregion

package/dist/storefront-events.js

@@ -0,0 +1,36 @@
+//#region src/storefront-events.ts
+function toEventProduct(line) {
+	const product = line.variant.product;
+	return {
+		id: product.id,
+		handle: product.handle,
+		title: product.title,
+		image: product.image?.url ?? null
+	};
+}
+function toEventVariant(line) {
+	return {
+		id: line.variant.id,
+		title: line.variant.title,
+		sku: line.variant.sku ?? null,
+		price: line.variant.price,
+		image: line.variant.image?.url ?? null
+	};
+}
+function toEventCart(cart) {
+	return {
+		id: cart.id,
+		totalQuantity: cart.totalQuantity,
+		subtotalAmount: cart.subtotalAmount,
+		discountAmount: cart.discountAmount,
+		lines: cart.lines.map((line) => ({
+			id: line.id,
+			quantity: line.quantity,
+			cost: line.cost,
+			product: toEventProduct(line),
+			variant: toEventVariant(line)
+		}))
+	};
+}
+//#endregion
+export { toEventCart, toEventProduct, toEventVariant };

package/dist/template-renderer.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode } from "react";
-import { TemplateSection } from "@shop-on/theme-contract";
+import { ClosestOverlays, TemplateSection } from "@shop-on/theme-contract";
 import { ArticleSchemaSource, BlockInstance, BlockInstance as BlockInstance$1, ProductSchemaSource, SectionGroupConfig, SectionGroupConfig as SectionGroupConfig$1, TemplateJSON, TemplateJSON as TemplateJSON$1, TemplateSeoSource } from "@shop-on/theme-runtime/template-types";
 //#region src/template-renderer.d.ts
 export type LayoutComponent = ComponentType<{
@@ -14,6 +14,13 @@ export interface AppSectionProps {
   groupType?: string;
 }
 export type AppSectionComponent = ComponentType<AppSectionProps>;
+export declare const ClosestScope: import("react").Provider<string | undefined>;
+/** `block` (the `each` subtree root, whose id is `eachId`) with `overlays`
+ * merged into its subtree's `closestSettings`, for the `ClosestScope` mounts
+ * below it to read. A new tree along each touched path only — every other
+ * node, and the input, stay as they were — so a list can merge each page it
+ * fetches without re-rendering cards whose blocks did not change. */
+export declare function withClosestOverlays(block: BlockInstance$1, eachId: string, overlays: ClosestOverlays | null | undefined): BlockInstance$1;
 export declare function loadAppScript(src: string): Promise<void>;
 /** The current shop's handle, read from the root route's loader data: every
  * theme's root loader returns `fetchShopInfo()` as `shop`. An app's element

package/dist/template-renderer.js

@@ -1,19 +1,59 @@
 import { escapeAttrValue, scopeCustomCss } from "./custom-css.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createContext, createElement, useContext, useEffect } from "react";
-import { collectTypes, selectRenderableChildren, selectRenderableSections } from "@shop-on/theme-contract";
+import { MAX_APP_BLOCK_CONTAINER_DEPTH, collectTypes, selectRenderableChildren, selectRenderableSections } from "@shop-on/theme-contract";
 import { rootRouteId, useMatch } from "@tanstack/react-router";
 //#region src/template-renderer.tsx
 const EMPTY_BLOCK_PATH = [];
 const SectionIdContext = createContext(void 0);
 const BlockPathContext = createContext(EMPTY_BLOCK_PATH);
+const BlockDepthContext = createContext(void 0);
+const ClosestScopeContext = createContext(void 0);
+const ClosestScope = ClosestScopeContext.Provider;
+/** `block` (the `each` subtree root, whose id is `eachId`) with `overlays`
+* merged into its subtree's `closestSettings`, for the `ClosestScope` mounts
+* below it to read. A new tree along each touched path only — every other
+* node, and the input, stay as they were — so a list can merge each page it
+* fetches without re-rendering cards whose blocks did not change. */
+function withClosestOverlays(block, eachId, overlays) {
+	let root = block;
+	for (const [key, byItem] of Object.entries(overlays ?? {})) {
+		const [head, ...rest] = key.split("/");
+		if (head !== eachId) continue;
+		const merge = (node, path) => {
+			if (path.length === 0) {
+				const closestSettings = { ...node.closestSettings };
+				for (const [handle, settings] of Object.entries(byItem)) closestSettings[handle] = {
+					...Object.hasOwn(closestSettings, handle) ? closestSettings[handle] : void 0,
+					...settings
+				};
+				return {
+					...node,
+					closestSettings
+				};
+			}
+			const [id, ...tail] = path;
+			const child = node.blocks && Object.hasOwn(node.blocks, id) ? node.blocks[id] : void 0;
+			if (!child) return node;
+			return {
+				...node,
+				blocks: {
+					...node.blocks,
+					[id]: merge(child, tail)
+				}
+			};
+		};
+		root = merge(root, rest);
+	}
+	return root;
+}
 const appScriptPromises = /* @__PURE__ */ new Map();
 function loadAppScript(src) {
 	const cached = appScriptPromises.get(src);
 	if (cached) return cached;
 	const p = new Promise((resolve, reject) => {
 		if (typeof window === "undefined") return resolve();
-		const existing = document.querySelector(`script[data-app-bundle="${src}"]`);
+		const existing = document.querySelector(`script[data-app-bundle="${CSS.escape(src)}"]`);
 		if (existing) {
 			existing.addEventListener("load", () => resolve(), { once: true });
 			existing.addEventListener("error", () => reject(/* @__PURE__ */ new Error("app-script-load-failed")), { once: true });
@@ -46,21 +86,31 @@ function useShopHandle() {
 		select: (match) => shopHandleOf(match.loaderData)
 	});
 }
-function DefaultAppSection({ section, sectionId }) {
-	const { tag, scriptUrl } = section;
-	const settings = section.settings ?? {};
+function AppElement({ tag, scriptUrl, settings, kind, instanceId }) {
 	const shopHandle = useShopHandle();
 	useEffect(() => {
 		if (scriptUrl) loadAppScript(scriptUrl).catch(() => {});
 	}, [scriptUrl]);
-	if (!tag) return null;
 	return createElement(tag, {
-		"data-settings": JSON.stringify(settings),
-		"data-app-section-id": sectionId,
+		"data-settings": JSON.stringify(settings ?? {}),
+		[`data-app-${kind}-id`]: instanceId,
 		"data-shop-handle": shopHandle,
 		suppressHydrationWarning: true
 	});
 }
+function DefaultAppSection({ section, sectionId }) {
+	if (!section.tag) return null;
+	return /* @__PURE__ */ jsx(AppElement, {
+		tag: section.tag,
+		scriptUrl: section.scriptUrl,
+		settings: section.settings,
+		kind: "section",
+		instanceId: sectionId
+	});
+}
+function mountsAppBlock(block, depth) {
+	return !!block.id && depth !== void 0 && depth <= MAX_APP_BLOCK_CONTAINER_DEPTH && !block.static && !!block.tag && block.type.startsWith("app-");
+}
 /** `collectTypes` over every template, merged. */
 function collectTemplateTypes(templates) {
 	const sections = /* @__PURE__ */ new Set();
@@ -109,6 +159,7 @@ function createTemplateRenderer(loaders, opts) {
 	async function preloadBlocks(args) {
 		const types = /* @__PURE__ */ new Set();
 		const visit = (b) => {
+			if (b.source === "app") return;
 			types.add(b.type);
 			if (b.blocks) for (const child of Object.values(b.blocks)) visit(child);
 		};
@@ -143,9 +194,12 @@ function createTemplateRenderer(loaders, opts) {
 				style: { display: "contents" },
 				children: /* @__PURE__ */ jsx(SectionIdContext.Provider, {
 					value: instanceId,
-					children: /* @__PURE__ */ jsxs(BlockPathContext.Provider, {
+					children: /* @__PURE__ */ jsx(BlockPathContext.Provider, {
 						value: EMPTY_BLOCK_PATH,
-						children: [sectionCss ? /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: sectionCss } }) : null, renderSectionBody(section, instanceId, groupType, blocks, staticBlocks)]
+						children: /* @__PURE__ */ jsxs(BlockDepthContext.Provider, {
+							value: 0,
+							children: [sectionCss ? /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: sectionCss } }) : null, renderSectionBody(section, instanceId, groupType, blocks, staticBlocks)]
+						})
 					})
 				})
 			}, instanceId);
@@ -182,14 +236,26 @@ function createTemplateRenderer(loaders, opts) {
 			children: renderSections(template.sections, template.order)
 		});
 	}
+	function renderThemeBlock(block, scope) {
+		const BlockComponent = resolveBlock(block.type);
+		const overlay = scope !== void 0 && block.closestSettings && Object.hasOwn(block.closestSettings, scope) ? block.closestSettings[scope] : void 0;
+		return /* @__PURE__ */ jsx(BlockComponent, {
+			...block.settings,
+			...overlay,
+			blockId: block.id,
+			blocks: selectRenderableChildren(block)
+		});
+	}
 	function BlockRenderer({ blocks, parentBlockId }) {
 		const sectionId = useContext(SectionIdContext);
 		const inheritedPath = useContext(BlockPathContext);
 		const containerPath = inheritedPath.length > 0 ? inheritedPath : parentBlockId ? [parentBlockId] : EMPTY_BLOCK_PATH;
+		const depth = useContext(BlockDepthContext);
+		const scope = useContext(ClosestScopeContext);
 		return /* @__PURE__ */ jsx(Fragment, { children: blocks.map((block, i) => {
 			if (block.disabled) return null;
-			const BlockComponent = resolveBlock(block.type);
-			const children = selectRenderableChildren(block);
+			const isApp = block.source === "app";
+			if (isApp && !mountsAppBlock(block, depth)) return null;
 			const key = block.id ?? `${block.type}-${i}`;
 			const ownPath = block.id ? [...containerPath, block.id] : containerPath;
 			const blockCss = block.id && sectionId ? scopeCustomCss(`[data-editor-section-id="${escapeAttrValue(sectionId)}"] ${containerPath.map((seg) => `[data-editor-block-id="${escapeAttrValue(seg)}"] `).join("")}[data-editor-block-id="${escapeAttrValue(block.id)}"]`, block.custom_css) : null;
@@ -197,12 +263,17 @@ function createTemplateRenderer(loaders, opts) {
 				"data-editor-block-id": block.id || void 0,
 				className: `block-${block.type.replace(/^_/, "")}`,
 				style: { display: "contents" },
-				children: [blockCss ? /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: blockCss } }) : null, /* @__PURE__ */ jsx(BlockPathContext.Provider, {
+				children: [blockCss ? /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: blockCss } }) : null, isApp ? /* @__PURE__ */ jsx(AppElement, {
+					tag: block.tag,
+					scriptUrl: block.scriptUrl,
+					settings: block.settings,
+					kind: "block",
+					instanceId: block.id
+				}) : /* @__PURE__ */ jsx(BlockPathContext.Provider, {
 					value: ownPath,
-					children: /* @__PURE__ */ jsx(BlockComponent, {
-						...block.settings,
-						blockId: block.id,
-						blocks: children
+					children: /* @__PURE__ */ jsx(BlockDepthContext.Provider, {
+						value: depth === void 0 ? void 0 : depth + 1,
+						children: renderThemeBlock(block, scope)
 					})
 				})]
 			}, key);
@@ -218,4 +289,4 @@ function createTemplateRenderer(loaders, opts) {
 	};
 }
 //#endregion
-export { collectTemplateTypes, createTemplateRenderer, loadAppScript, useShopHandle };
+export { ClosestScope, collectTemplateTypes, createTemplateRenderer, loadAppScript, useShopHandle, withClosestOverlays };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-react",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -22,6 +22,8 @@
     "./preview-guard": "./dist/preview-guard.js",
     "./preview-search-middleware": "./dist/preview-search-middleware.js",
     "./product-json-ld": "./dist/product-json-ld.js",
+    "./recommendation-tracking": "./dist/recommendation-tracking.js",
+    "./storefront-events": "./dist/storefront-events.js",
     "./template-renderer": "./dist/template-renderer.js",
     "./turnstile-widget": "./dist/turnstile-widget.js",
     "./uploaded-font-faces": "./dist/uploaded-font-faces.js",
@@ -31,8 +33,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@shop-on/theme-contract": "0.4.0",
-    "@shop-on/theme-runtime": "0.4.0"
+    "@shop-on/theme-contract": "0.6.0",
+    "@shop-on/theme-runtime": "0.6.0"
   },
   "devDependencies": {
     "@tanstack/react-router": "1.170.45",