@shop-on/theme-react 0.0.0-stage → 0.1.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/analytics.d.ts

@@ -0,0 +1,100 @@
+//#region src/analytics.d.ts
+export type EventProperties = Record<string, unknown>;
+export declare function trackVisit(properties?: EventProperties): Promise<void>;
+/** Every event carries a per-event `id`. Rails forwards it as the Meta CAPI
+ *  `event_id`, which is the dedup key for a job retry (and, later, for a
+ *  browser-side twin of a server event). */
+export declare function track(name: string, properties?: EventProperties): Promise<void>;
+/** Idempotent per page load — calls `trackVisit` only once even if several
+ *  components mount concurrently. Every tracking hook calls it first, so the
+ *  visit exists before any event references it. */
+export declare function ensureVisit(properties?: EventProperties): void;
+/** Storefront product ids arrive as stringified integer primary keys. Every
+ *  aggregate downstream casts `(properties->>'<key>')::int`, so an unparseable
+ *  id is dropped at the edge rather than written as a row that poisons a
+ *  window. */
+export declare function toInt(value: unknown): number | null;
+/** The discovery surfaces that emit `product_list_viewed` / `product_clicked`.
+ *  The recommendation rail is deliberately NOT one — it keeps its own
+ *  `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. */
+export declare function trackProductAddedToCart(input: {
+  productId: string | number | null | undefined;
+  variantId: string | number | null | undefined;
+  quantity: number;
+}): 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. */
+export declare function trackProductRemovedFromCart(input: {
+  productId: string | number | null | undefined;
+  variantId: string | number | null | undefined;
+  quantity: number;
+}): void;
+/** Fires `checkout_started` on the cart→checkout handoff. Returns the promise
+ *  so the caller can await it before the full-document hop: `keepalive` POSTs
+ *  have historically been dropped by Safari across cross-document navigation,
+ *  and this is the conversion signal. `beacon` swallows its own errors, so
+ *  awaiting is safe. */
+export declare function trackCheckoutStarted(input: {
+  totalQuantity: number;
+  subtotalAmount: number;
+  currency: string;
+}): Promise<void>;
+export declare function trackSearchSubmitted(input: {
+  query: string;
+  totalCount: number;
+}): void;
+export declare function trackCartViewed(input: {
+  lineCount: number;
+  totalQuantity: number;
+  subtotalAmount: number;
+  currency: string;
+}): void;
+/** Fires `product_clicked` (GA4 `select_item`) on click-through from a card in
+ *  a list. `position` is the card's index within the rendered page. */
+export declare function trackProductClicked(input: {
+  productId: string | number | null | undefined;
+  productHandle?: string;
+  listType: ProductListType;
+  listId?: string | number | null;
+  position?: number | null;
+}): void;
+/** Fires `product_list_viewed` (GA4 `view_item_list`) once a list scrolls into
+ *  view, carrying the rendered items and their positions so a funnel can
+ *  compute impression→click→ATC by position. Items with an unparseable id are
+ *  dropped; the event is skipped entirely when nothing survives. */
+export declare function trackProductListViewed(input: {
+  listType: ProductListType;
+  listId?: string | number | null;
+  listHandle?: string;
+  totalCount?: number;
+  items: {
+    productId: string | number | null | undefined;
+    position: number;
+  }[];
+}): void;
+/** One card of a recommendation rail: the product the rail recommends for,
+ *  the one it recommended, why, and where in the rail. */
+export type RecommendationAttribution = {
+  referenceProductId: string | number | null | undefined;
+  referenceProductHandle: string;
+  recommendedProductId: string | number | null | undefined;
+  recommendedProductHandle: string;
+  intent: "RELATED" | "COMPLEMENTARY";
+  position: number;
+};
+/** Fires `recommendation_shown` for a rail card in view. It carries no
+ *  `product_id` on purpose: "shown" is not a positive engagement signal, so
+ *  the trainer keeps ignoring it. The pair is separate from the listing's
+ *  `product_list_viewed` / `product_clicked`, so a rail impression never
+ *  double-counts as a list impression. */
+export declare function trackRecommendationShown(attribution: RecommendationAttribution): void;
+/** Fires `recommendation_clicked` for a click through to a rail card's product.
+ *  `product_id` mirrors `recommended_product_id` so the trainer accepts the
+ *  click as a positive signal for the product the buyer chose; the attribution
+ *  fields stay distinct for analytics queries. */
+export declare function trackRecommendationClicked(attribution: RecommendationAttribution): void;
+//#endregion

package/dist/analytics.js

@@ -0,0 +1,250 @@
+//#region src/analytics.ts
+const VISIT_KEY = "ahoy_visit";
+const VISITOR_KEY = "ahoy_visitor";
+const VISIT_TTL_MS = 144e5;
+const VISITOR_TTL_MS = 63072e6;
+function isBrowser() {
+	return typeof window !== "undefined" && typeof localStorage !== "undefined";
+}
+function isPreview() {
+	try {
+		return new URLSearchParams(window.location.search).has("preview");
+	} catch {
+		return false;
+	}
+}
+function readToken(key) {
+	if (!isBrowser()) return null;
+	try {
+		const raw = localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		if (!parsed?.token || !parsed.expiresAt || parsed.expiresAt < Date.now()) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function writeToken(key, token, ttlMs) {
+	if (!isBrowser()) return;
+	try {
+		localStorage.setItem(key, JSON.stringify({
+			token,
+			expiresAt: Date.now() + ttlMs
+		}));
+	} catch {}
+}
+function newToken() {
+	try {
+		return crypto.randomUUID();
+	} catch {
+		return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+	}
+}
+function getVisitToken() {
+	const existing = readToken(VISIT_KEY);
+	if (existing) {
+		writeToken(VISIT_KEY, existing.token, VISIT_TTL_MS);
+		return existing.token;
+	}
+	const token = newToken();
+	writeToken(VISIT_KEY, token, VISIT_TTL_MS);
+	return token;
+}
+function getVisitorToken() {
+	const existing = readToken(VISITOR_KEY);
+	if (existing) return existing.token;
+	const token = newToken();
+	writeToken(VISITOR_KEY, token, VISITOR_TTL_MS);
+	return token;
+}
+async function beacon(path, body) {
+	if (!isBrowser() || isPreview()) return;
+	try {
+		await fetch(path, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"Ahoy-Visit": getVisitToken(),
+				"Ahoy-Visitor": getVisitorToken()
+			},
+			body: JSON.stringify(body),
+			keepalive: true,
+			credentials: "same-origin"
+		});
+	} catch {}
+}
+async function trackVisit(properties) {
+	await beacon("/analytics/visits", {
+		started_at: (/* @__PURE__ */ new Date()).toISOString(),
+		...properties
+	});
+}
+/** Every event carries a per-event `id`. Rails forwards it as the Meta CAPI
+*  `event_id`, which is the dedup key for a job retry (and, later, for a
+*  browser-side twin of a server event). */
+async function track(name, properties = {}) {
+	await beacon("/analytics/events", { events: [{
+		name,
+		properties,
+		id: newToken(),
+		time: (/* @__PURE__ */ new Date()).toISOString()
+	}] });
+}
+let visitTrackedThisLoad = false;
+/** Idempotent per page load — calls `trackVisit` only once even if several
+*  components mount concurrently. Every tracking hook calls it first, so the
+*  visit exists before any event references it. */
+function ensureVisit(properties) {
+	if (!isBrowser() || visitTrackedThisLoad) return;
+	visitTrackedThisLoad = true;
+	trackVisit(properties);
+}
+/** Storefront product ids arrive as stringified integer primary keys. Every
+*  aggregate downstream casts `(properties->>'<key>')::int`, so an unparseable
+*  id is dropped at the edge rather than written as a row that poisons a
+*  window. */
+function toInt(value) {
+	if (typeof value === "number" && Number.isInteger(value)) return 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. */
+function trackProductAddedToCart(input) {
+	const productId = toInt(input.productId);
+	if (productId === null) return;
+	const variantId = toInt(input.variantId);
+	track("product_added_to_cart", {
+		product_id: productId,
+		...variantId !== null ? { variant_id: variantId } : {},
+		quantity: input.quantity
+	});
+}
+/** Fires `product_removed_from_cart` on line removal — the funnel-drop signal
+*  symmetric to the add event, so it carries the same join keys. */
+function trackProductRemovedFromCart(input) {
+	const productId = toInt(input.productId);
+	if (productId === null) return;
+	const variantId = toInt(input.variantId);
+	track("product_removed_from_cart", {
+		product_id: productId,
+		...variantId !== null ? { variant_id: variantId } : {},
+		quantity: input.quantity
+	});
+}
+/** Fires `checkout_started` on the cart→checkout handoff. Returns the promise
+*  so the caller can await it before the full-document hop: `keepalive` POSTs
+*  have historically been dropped by Safari across cross-document navigation,
+*  and this is the conversion signal. `beacon` swallows its own errors, so
+*  awaiting is safe. */
+function trackCheckoutStarted(input) {
+	return track("checkout_started", {
+		total_quantity: input.totalQuantity,
+		subtotal_amount: input.subtotalAmount,
+		currency: input.currency
+	});
+}
+/** Fires `search_submitted` once per unique query per page load. Keyed on the
+*  query alone, so paginating or refining filters on the same query doesn't
+*  refire — only a fresh query does. Blank queries (the empty state) are
+*  skipped. */
+const trackedSearches = /* @__PURE__ */ new Set();
+function trackSearchSubmitted(input) {
+	const q = input.query.trim();
+	if (!q || trackedSearches.has(q)) return;
+	trackedSearches.add(q);
+	track("search_submitted", {
+		query: q,
+		total_count: input.totalCount
+	});
+}
+/** Fires `cart_viewed` when the drawer opens or the cart page paints.
+*  Idempotent across consecutive views of the SAME cart state — reopening the
+*  drawer unchanged shouldn't refire. Keyed on `(line_count, total_quantity)`
+*  rather than a snapshot of every line, so routine open/close churn doesn't
+*  pollute the log. */
+let lastCartViewKey = null;
+function trackCartViewed(input) {
+	const key = `${input.lineCount}:${input.totalQuantity}`;
+	if (lastCartViewKey === key) return;
+	lastCartViewKey = key;
+	track("cart_viewed", {
+		line_count: input.lineCount,
+		total_quantity: input.totalQuantity,
+		subtotal_amount: input.subtotalAmount,
+		currency: input.currency
+	});
+}
+/** Fires `product_clicked` (GA4 `select_item`) on click-through from a card in
+*  a list. `position` is the card's index within the rendered page. */
+function trackProductClicked(input) {
+	const productId = toInt(input.productId);
+	if (productId === null) return;
+	const listId = input.listId == null ? null : toInt(input.listId);
+	track("product_clicked", {
+		product_id: productId,
+		...input.productHandle ? { product_handle: input.productHandle } : {},
+		list_type: input.listType,
+		...listId !== null ? { list_id: listId } : {},
+		...input.position != null ? { position: input.position } : {}
+	});
+}
+/** Fires `product_list_viewed` (GA4 `view_item_list`) once a list scrolls into
+*  view, carrying the rendered items and their positions so a funnel can
+*  compute impression→click→ATC by position. Items with an unparseable id are
+*  dropped; the event is skipped entirely when nothing survives. */
+function trackProductListViewed(input) {
+	const items = input.items.flatMap((it) => {
+		const product_id = toInt(it.productId);
+		return product_id === null ? [] : [{
+			product_id,
+			position: it.position
+		}];
+	});
+	if (items.length === 0) return;
+	const listId = input.listId == null ? null : toInt(input.listId);
+	track("product_list_viewed", {
+		list_type: input.listType,
+		...listId !== null ? { list_id: listId } : {},
+		...input.listHandle ? { list_handle: input.listHandle } : {},
+		...input.totalCount != null ? { total_count: input.totalCount } : {},
+		items
+	});
+}
+function recommendationPayload(a) {
+	const reference = toInt(a.referenceProductId);
+	const recommended = toInt(a.recommendedProductId);
+	if (reference === null || recommended === null) return null;
+	return {
+		reference_product_id: reference,
+		recommended_product_id: recommended,
+		reference_product_handle: a.referenceProductHandle,
+		recommended_product_handle: a.recommendedProductHandle,
+		intent: a.intent,
+		position: a.position
+	};
+}
+/** Fires `recommendation_shown` for a rail card in view. It carries no
+*  `product_id` on purpose: "shown" is not a positive engagement signal, so
+*  the trainer keeps ignoring it. The pair is separate from the listing's
+*  `product_list_viewed` / `product_clicked`, so a rail impression never
+*  double-counts as a list impression. */
+function trackRecommendationShown(attribution) {
+	const payload = recommendationPayload(attribution);
+	if (payload) track("recommendation_shown", payload);
+}
+/** Fires `recommendation_clicked` for a click through to a rail card's product.
+*  `product_id` mirrors `recommended_product_id` so the trainer accepts the
+*  click as a positive signal for the product the buyer chose; the attribution
+*  fields stay distinct for analytics queries. */
+function trackRecommendationClicked(attribution) {
+	const payload = recommendationPayload(attribution);
+	if (!payload) return;
+	track("recommendation_clicked", {
+		...payload,
+		product_id: payload.recommended_product_id
+	});
+}
+//#endregion
+export { ensureVisit, toInt, track, trackCartViewed, trackCheckoutStarted, trackProductAddedToCart, trackProductClicked, trackProductListViewed, trackProductRemovedFromCart, trackRecommendationClicked, trackRecommendationShown, trackSearchSubmitted, trackVisit };

package/dist/article-json-ld.d.ts

@@ -0,0 +1,7 @@
+import { ArticleSchemaSource } from "@shop-on/theme-runtime/template-types";
+//#region src/article-json-ld.d.ts
+export interface ArticleJsonLdProps {
+  data: ArticleSchemaSource;
+}
+export declare function ArticleJsonLd({ data }: ArticleJsonLdProps): import("react").JSX.Element;
+//#endregion

package/dist/article-json-ld.js

@@ -0,0 +1,33 @@
+import { escapeForScriptTag } from "@shop-on/theme-runtime/json-ld-escape";
+import { jsx } from "react/jsx-runtime";
+//#region src/article-json-ld.tsx
+function buildArticleLd(data) {
+	const ld = {
+		"@context": "https://schema.org",
+		"@type": "BlogPosting",
+		headline: data.headline,
+		description: data.description,
+		datePublished: data.datePublished,
+		dateModified: data.dateModified
+	};
+	if (data.imageUrl) ld.image = [data.imageUrl];
+	if (data.authorName) ld.author = {
+		"@type": "Person",
+		name: data.authorName
+	};
+	if (data.publisherName) ld.publisher = {
+		"@type": "Organization",
+		name: data.publisherName
+	};
+	if (data.mainEntityOfPage) ld.mainEntityOfPage = data.mainEntityOfPage;
+	return ld;
+}
+function ArticleJsonLd({ data }) {
+	const json = escapeForScriptTag(JSON.stringify(buildArticleLd(data)));
+	return /* @__PURE__ */ jsx("script", {
+		type: "application/ld+json",
+		dangerouslySetInnerHTML: { __html: json }
+	});
+}
+//#endregion
+export { ArticleJsonLd };

package/dist/breadcrumb-json-ld.d.ts

@@ -0,0 +1,7 @@
+import { BreadcrumbSchemaSource } from "@shop-on/theme-runtime/template-types";
+//#region src/breadcrumb-json-ld.d.ts
+export interface BreadcrumbJsonLdProps {
+  data: BreadcrumbSchemaSource;
+}
+export declare function BreadcrumbJsonLd({ data }: BreadcrumbJsonLdProps): import("react").JSX.Element;
+//#endregion

package/dist/breadcrumb-json-ld.js

@@ -0,0 +1,24 @@
+import { escapeForScriptTag } from "@shop-on/theme-runtime/json-ld-escape";
+import { jsx } from "react/jsx-runtime";
+//#region src/breadcrumb-json-ld.tsx
+function buildBreadcrumbLd(data) {
+	return {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: data.items.map((it, i) => ({
+			"@type": "ListItem",
+			position: i + 1,
+			name: it.name,
+			item: it.url
+		}))
+	};
+}
+function BreadcrumbJsonLd({ data }) {
+	const json = escapeForScriptTag(JSON.stringify(buildBreadcrumbLd(data)));
+	return /* @__PURE__ */ jsx("script", {
+		type: "application/ld+json",
+		dangerouslySetInnerHTML: { __html: json }
+	});
+}
+//#endregion
+export { BreadcrumbJsonLd };

package/dist/custom-css.d.ts

@@ -0,0 +1,17 @@
+//#region src/custom-css.d.ts
+export declare function escapeAttrValue(value: string): string;
+/** Guard + trim a merchant-authored CSS value from settings/instance data.
+ * Returns null for anything that isn't a non-empty string once trimmed, so
+ * callers can treat null uniformly as "nothing to render". The only
+ * transform applied is neutralizing a `</style>` (or `</script>`) breakout —
+ * `dangerouslySetInnerHTML` does not escape `</`, so a merchant value
+ * containing `</style>` would otherwise close the wrapping tag early. There
+ * is no other sanitization: this is merchant-authored CSS rendered on the
+ * merchant's own storefront (Shopify parity). */
+export declare function sanitizeCustomCss(css: unknown): string | null;
+/** Wrap sanitized CSS in `selector { … }` via native CSS nesting so a
+ * merchant can target the wrapper itself with `&` (the `display: contents`
+ * section/block wrapper the renderer emits) or descend into it. Returns null
+ * when there's nothing to render. */
+export declare function scopeCustomCss(selector: string, css: unknown): string | null;
+//#endregion

package/dist/custom-css.js

@@ -0,0 +1,29 @@
+//#region src/custom-css.ts
+function escapeAttrValue(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+/** Guard + trim a merchant-authored CSS value from settings/instance data.
+* Returns null for anything that isn't a non-empty string once trimmed, so
+* callers can treat null uniformly as "nothing to render". The only
+* transform applied is neutralizing a `</style>` (or `<\/script>`) breakout —
+* `dangerouslySetInnerHTML` does not escape `</`, so a merchant value
+* containing `</style>` would otherwise close the wrapping tag early. There
+* is no other sanitization: this is merchant-authored CSS rendered on the
+* merchant's own storefront (Shopify parity). */
+function sanitizeCustomCss(css) {
+	if (typeof css !== "string") return null;
+	const trimmed = css.trim();
+	if (!trimmed) return null;
+	return trimmed.replace(/<\//g, "<\\/");
+}
+/** Wrap sanitized CSS in `selector { … }` via native CSS nesting so a
+* merchant can target the wrapper itself with `&` (the `display: contents`
+* section/block wrapper the renderer emits) or descend into it. Returns null
+* when there's nothing to render. */
+function scopeCustomCss(selector, css) {
+	const sanitized = sanitizeCustomCss(css);
+	if (sanitized === null) return null;
+	return `${selector} { ${sanitized} }`;
+}
+//#endregion
+export { escapeAttrValue, sanitizeCustomCss, scopeCustomCss };

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

@@ -0,0 +1,32 @@
+import { EditorCommand } from "@shop-on/theme-contract";
+//#region src/editor-preview-bridge-utils.d.ts
+export interface EditorSelectedItem {
+  type: "section" | "block";
+  sectionId: string;
+  blockId?: string;
+  /** Container path: ids of the ancestor blocks between the section and
+   * `blockId`, section excluded, `blockId` excluded. Absent/`[]` = the block
+   * sits directly in the section. */
+  blockPath?: string[];
+  /** Legacy mirror of the last `blockPath` hop. Emitted so a rebuilt theme
+   * still nests one level when it talks to an admin build that predates block
+   * paths; never read by the new admin (it parses `blockPath`). */
+  parentBlockId?: string;
+  groupType?: string;
+}
+export declare function sameItem(a: EditorSelectedItem | null, b: EditorSelectedItem | null): boolean;
+export declare function parseSelected(raw: unknown): EditorSelectedItem | null;
+export declare function readClickTarget(target: EventTarget | null): EditorSelectedItem | null;
+/**
+ * Whether a key the editor binds should go to the editor from inside the
+ * preview, rather than stay with the storefront. The storefront keeps every
+ * key typed into its own fields (the search box, a quantity input), a text
+ * copy while its text is selected, and Esc inside its own dialogs — a cart
+ * drawer closes on Esc, and deselecting the section under it too would be a
+ * surprise.
+ */
+export declare function forwardsFromPreview(command: EditorCommand, target: EventTarget | null, ctx: {
+  textSelected: boolean;
+  selectionShown: boolean;
+}): boolean;
+//#endregion

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

@@ -0,0 +1,85 @@
+import { blockPathsEqual, normalizeBlockPath } from "@shop-on/theme-contract";
+//#region src/editor-preview-bridge-utils.ts
+function sameItem(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.type === b.type && a.sectionId === b.sectionId && (a.blockId ?? null) === (b.blockId ?? null) && blockPathsEqual(a.blockPath, b.blockPath) && (a.groupType ?? null) === (b.groupType ?? null);
+}
+function parseSelected(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const v = raw;
+	if (v.type !== "section" && v.type !== "block") return null;
+	if (typeof v.sectionId !== "string" || v.sectionId === "") return null;
+	return {
+		type: v.type,
+		sectionId: v.sectionId,
+		blockId: typeof v.blockId === "string" ? v.blockId : void 0,
+		blockPath: normalizeBlockPath(v.blockPath, v.parentBlockId),
+		groupType: typeof v.groupType === "string" ? v.groupType : void 0
+	};
+}
+function readClickTarget(target) {
+	if (!(target instanceof Element)) return null;
+	const sectionEl = target.closest("[data-editor-section-id]") ?? target.closest("[data-section-id]");
+	if (!sectionEl) return null;
+	const sectionId = sectionEl.getAttribute("data-editor-section-id") ?? sectionEl.getAttribute("data-section-id") ?? "";
+	if (!sectionId) return null;
+	const groupType = target.closest("[data-editor-section-id]")?.getAttribute("data-editor-group-type") || void 0;
+	const blockEl = target.closest("[data-editor-block-id]") ?? target.closest("[data-block-id]");
+	if (blockEl && sectionEl.contains(blockEl)) {
+		const blockId = blockEl.getAttribute("data-editor-block-id") ?? blockEl.getAttribute("data-block-id") ?? "";
+		if (!blockId) return null;
+		const blockPath = readAncestorBlockPath(blockEl, sectionEl);
+		return {
+			type: "block",
+			sectionId,
+			blockId,
+			blockPath,
+			parentBlockId: blockPath[blockPath.length - 1],
+			groupType
+		};
+	}
+	return {
+		type: "section",
+		sectionId,
+		groupType
+	};
+}
+function readAncestorBlockPath(blockEl, sectionEl) {
+	const path = [];
+	let node = blockEl.parentElement;
+	while (node && node !== sectionEl && sectionEl.contains(node)) {
+		const id = node.getAttribute("data-editor-block-id");
+		if (id) path.unshift(id);
+		node = node.parentElement;
+	}
+	return path;
+}
+const SELECTION_COMMANDS = /* @__PURE__ */ new Set([
+	"deselect",
+	"copy",
+	"paste",
+	"duplicate",
+	"remove",
+	"moveUp",
+	"moveDown"
+]);
+const STOREFRONT_FIELDS = "input, textarea, select, [role=\"textbox\"], [role=\"combobox\"], [role=\"slider\"], [role=\"spinbutton\"]";
+/**
+* Whether a key the editor binds should go to the editor from inside the
+* preview, rather than stay with the storefront. The storefront keeps every
+* key typed into its own fields (the search box, a quantity input), a text
+* copy while its text is selected, and Esc inside its own dialogs — a cart
+* drawer closes on Esc, and deselecting the section under it too would be a
+* surprise.
+*/
+function forwardsFromPreview(command, target, ctx) {
+	if (!ctx.selectionShown && SELECTION_COMMANDS.has(command)) return false;
+	if (target instanceof HTMLElement) {
+		if (target.isContentEditable || target.closest(STOREFRONT_FIELDS)) return false;
+		if (command === "deselect" && target.closest("dialog, [role=\"dialog\"]")) return false;
+	}
+	return !(command === "copy" && ctx.textSelected);
+}
+//#endregion
+export { forwardsFromPreview, parseSelected, readClickTarget, sameItem };

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

@@ -0,0 +1,8 @@
+import { EditorSelectedItem } from "./editor-preview-bridge-utils.js";
+//#region src/editor-preview-bridge.d.ts
+interface Props {
+  preview: string | undefined;
+}
+export declare function EditorPreviewBridge({ preview }: Props): import("react").JSX.Element | null;
+//#endregion
+export type { EditorSelectedItem };