@shop-on/theme-server 0.4.0 → 0.6.0

package/dist/account.js

@@ -2,13 +2,16 @@ import { fetchShopInfo } from "./shop.js";
 import { checkOrigin } from "./csrf.js";
 import { escapeHtmlAttr } from "./html.js";
 //#region src/account.ts
+const RETURN_TO_BASE = "http://return-to.invalid";
 const FORBIDDEN_RETURN_TO = /^(?:\/[^/]+)?\/(?:account|customer_logout)(?:\/|$)/;
 function normalizeReturnToPath(raw) {
 	if (typeof raw !== "string") return "/";
-	if (!raw.startsWith("/") || raw.startsWith("//")) return "/";
-	const pathOnly = raw.split(/[?#]/, 1)[0];
-	if (FORBIDDEN_RETURN_TO.test(pathOnly)) return "/";
-	return raw;
+	const path = raw.replace(/[\t\n\r]/g, "");
+	if (!path.startsWith("/") || path.startsWith("//") || path.startsWith("/\\")) return "/";
+	const url = new URL(path, RETURN_TO_BASE);
+	if (url.origin !== RETURN_TO_BASE || url.pathname.startsWith("//")) return "/";
+	if (FORBIDDEN_RETURN_TO.test(url.pathname)) return "/";
+	return url.pathname + url.search + url.hash;
 }
 async function getAccountRedirectUrl(data) {
 	const shop = await fetchShopInfo();

package/dist/analytics-proxy.d.ts

@@ -4,7 +4,7 @@ declare const PATHS: {
   readonly events: "/storefront/analytics/events";
 };
 export type AnalyticsEndpoint = keyof typeof PATHS;
-export declare function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, eventSourceUrl }: {
+export declare function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, cookies, eventSourceUrl }: {
   endpoint: AnalyticsEndpoint;
   body: unknown;
   visitToken?: string | null;
@@ -13,6 +13,7 @@ export declare function proxyAnalytics({ endpoint, body, visitToken, visitorToke
   clientIp?: string | null;
   fbp?: string | null;
   fbc?: string | null;
+  cookies?: string | null;
   eventSourceUrl?: string | null;
 }): Promise<{
   status: number;

package/dist/analytics-proxy.js

@@ -6,7 +6,7 @@ const PATHS = {
 	visits: "/storefront/analytics/visits",
 	events: "/storefront/analytics/events"
 };
-async function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, eventSourceUrl }) {
+async function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, cookies, eventSourceUrl }) {
 	const headers = {
 		Authorization: `Bearer ${await getStorefrontToken()}`,
 		"Content-Type": "application/json",
@@ -18,6 +18,7 @@ async function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAg
 	if (clientIp) headers["X-Buyer-IP"] = clientIp;
 	if (fbp) headers["X-Marketing-Fbp"] = fbp;
 	if (fbc) headers["X-Marketing-Fbc"] = fbc;
+	if (cookies) headers["X-Marketing-Cookies"] = cookies;
 	if (eventSourceUrl) headers["X-Event-Source-Url"] = eventSourceUrl;
 	return { status: (await fetch(`${storefrontApiUrl()}${PATHS[endpoint]}`, {
 		method: "POST",

package/dist/blog.d.ts

@@ -1,4 +1,5 @@
 import { ImageFileInfo } from "./files.js";
+import { MetafieldMap } from "./metafields.js";
 //#region src/blog.d.ts
 export type ArticleAuthor = {
   name: string;
@@ -105,5 +106,30 @@ export declare const fetchAdjacentArticles: (params: {
   newer: ArticleCardData | null;
   older: ArticleCardData | null;
 }>;
+/** The blog's storefront metafields keyed `"namespace.key"` — the
+ * `blog_metafield` dynamic source, read only when a template binds one. `{}`
+ * on a miss or a failure, so the literal renders. */
+export declare const fetchBlogMetafields: (ref: string, locale?: string) => Promise<MetafieldMap>;
+/** The article's storefront metafields — the `article_metafield` dynamic
+ * source. `ref` is what every article read takes (`parseArticleRef`): the
+ * route's `<blog-handle>/<article-handle>` composite, or a node id. */
+export declare const fetchArticleMetafields: (ref: string, locale?: string) => Promise<MetafieldMap>;
+/** The route blog as the theme loader's dynamic sources read it
+ * (`DynamicSourceBlog` in `@shop-on/theme-loader`): the title off the blog read
+ * the theme already made, and a lazy provider the loader calls only when a
+ * template binds a blog field. */
+export declare function routeBlogSource(blog: {
+  handle: string;
+  title: string;
+}, locale?: string): {
+  title: string;
+  getMetafields: () => Promise<MetafieldMap>;
+};
+/** The route article as the theme loader's dynamic sources read it
+ * (`DynamicSourceArticle`): the same shape as `routeBlogSource`. */
+export declare function routeArticleSource(article: Pick<ArticleData, "blogHandle" | "handle" | "title">, locale?: string): {
+  title: string;
+  getMetafields: () => Promise<MetafieldMap>;
+};
 //#endregion
 export {};

package/dist/blog.js

@@ -2,6 +2,7 @@ import { memoTTL } from "./cache.js";
 import { graphql, request } from "./graphql.js";
 import { getContentVersion } from "./content-version.js";
 import { toFileInfo } from "./files.js";
+import { metafieldsReader } from "./metafields.js";
 //#region src/blog.ts
 const FetchBlogQuery = graphql(`
   query FetchBlog($handle: String!, $first: Int!) {
@@ -477,5 +478,68 @@ const fetchAdjacentArticles = async (params) => {
 		};
 	}
 };
+const FetchBlogMetafieldsQuery = graphql(`
+  query FetchBlogMetafields($handle: String, $id: ID) {
+    blog(handle: $handle, id: $id) {
+      metafields(first: 50) {
+        nodes {
+          namespace
+          key
+          type
+          value
+        }
+      }
+    }
+  }
+`);
+const FetchArticleMetafieldsQuery = graphql(`
+  query FetchArticleMetafields($blogHandle: String, $handle: String, $id: ID) {
+    article(blogHandle: $blogHandle, handle: $handle, id: $id) {
+      metafields(first: 50) {
+        nodes {
+          namespace
+          key
+          type
+          value
+        }
+      }
+    }
+  }
+`);
+/** The blog's storefront metafields keyed `"namespace.key"` — the
+* `blog_metafield` dynamic source, read only when a template binds one. `{}`
+* on a miss or a failure, so the literal renders. */
+const fetchBlogMetafields = metafieldsReader("fetchBlogMetafields", async (handle, locale) => {
+	return (await request(FetchBlogMetafieldsQuery, handle.startsWith("gid://") ? { id: handle } : { handle }, locale ? { acceptLanguage: locale } : void 0)).blog?.metafields.nodes ?? null;
+});
+/** The article's storefront metafields — the `article_metafield` dynamic
+* source. `ref` is what every article read takes (`parseArticleRef`): the
+* route's `<blog-handle>/<article-handle>` composite, or a node id. */
+const fetchArticleMetafields = metafieldsReader("fetchArticleMetafields", async (ref, locale) => {
+	const parts = parseArticleRef(ref);
+	return (await request(FetchArticleMetafieldsQuery, {
+		blogHandle: parts.blogHandle ?? null,
+		handle: parts.handle ?? null,
+		id: parts.id ?? null
+	}, locale ? { acceptLanguage: locale } : void 0)).article?.metafields.nodes ?? null;
+});
+/** The route blog as the theme loader's dynamic sources read it
+* (`DynamicSourceBlog` in `@shop-on/theme-loader`): the title off the blog read
+* the theme already made, and a lazy provider the loader calls only when a
+* template binds a blog field. */
+function routeBlogSource(blog, locale) {
+	return {
+		title: blog.title,
+		getMetafields: () => fetchBlogMetafields(blog.handle, locale)
+	};
+}
+/** The route article as the theme loader's dynamic sources read it
+* (`DynamicSourceArticle`): the same shape as `routeBlogSource`. */
+function routeArticleSource(article, locale) {
+	return {
+		title: article.title,
+		getMetafields: () => fetchArticleMetafields(`${article.blogHandle}/${article.handle}`, locale)
+	};
+}
 //#endregion
-export { fetchAdjacentArticles, fetchArticle, fetchArticleByRef, fetchArticleCard, fetchBlog, fetchBlogMeta, fetchBlogPage };
+export { fetchAdjacentArticles, fetchArticle, fetchArticleByRef, fetchArticleCard, fetchArticleMetafields, fetchBlog, fetchBlogMeta, fetchBlogMetafields, fetchBlogPage, routeArticleSource, routeBlogSource };

package/dist/cart.d.ts

@@ -92,17 +92,17 @@ export declare const CartFields: import("gql.tada").TadaDocumentNode<{
   attachedToCurrentCustomer: boolean;
   discountAmount: {
     amount: string;
-    currencyCode: "MNT";
+    currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
   };
   discountApplications: {
     allocatedAmount: {
       amount: string;
-      currencyCode: "MNT";
+      currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
     };
     allocations: {
       amount: {
         amount: string;
-        currencyCode: "MNT";
+        currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
       };
       targetLineItemId: string | null;
     }[];
@@ -119,7 +119,7 @@ export declare const CartFields: import("gql.tada").TadaDocumentNode<{
     nodes: {
       cost: {
         amount: string;
-        currencyCode: "MNT";
+        currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
       };
       customAttributes: {
         name: string;
@@ -132,7 +132,7 @@ export declare const CartFields: import("gql.tada").TadaDocumentNode<{
         availableForSale: boolean;
         compareAtV2: {
           amount: string;
-          currencyCode: "MNT";
+          currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
         } | null;
         featuredMedia: {
           __typename: "ShopFont";
@@ -158,7 +158,7 @@ export declare const CartFields: import("gql.tada").TadaDocumentNode<{
         id: string;
         priceV2: {
           amount: string;
-          currencyCode: "MNT";
+          currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
         };
         product: {
           featuredMedia: {
@@ -201,7 +201,7 @@ export declare const CartFields: import("gql.tada").TadaDocumentNode<{
   note: string | null;
   subtotalAmount: {
     amount: string;
-    currencyCode: "MNT";
+    currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
   };
   totalQuantity: number;
 }, {}, {

package/dist/checkout.js

@@ -21,7 +21,7 @@ const readMarketingAttribution = createServerOnlyFn(async () => {
 	try {
 		const { getRequest } = await import("@tanstack/react-start/server");
 		const cookies = parseMarketingCookies(getRequest().headers.get("cookie"));
-		return cookies.fbp || cookies.fbc ? cookies : null;
+		return Object.keys(cookies).length > 0 ? cookies : null;
 	} catch (err) {
 		console.warn("[checkout] marketing attribution unavailable:", err);
 		return null;

package/dist/collection.d.ts

@@ -1,4 +1,5 @@
 import { FileInfo } from "./files.js";
+import { MetafieldMap } from "./metafields.js";
 import { ResultOf } from "gql.tada";
 import { Money } from "@shop-on/theme-runtime/money";
 import { ProductOption } from "@shop-on/theme-runtime/product-variants";
@@ -23,6 +24,10 @@ export type CollectionProductData = {
   media: FileInfo[];
   options?: ProductOption[];
   variantMedia?: FileInfo[];
+  metafields?: Record<string, {
+    type: string;
+    value: string;
+  }>;
 };
 export type CollectionData = {
   title: string;
@@ -41,12 +46,12 @@ export declare const CollectionProductNodeFragment: import("gql.tada").TadaDocum
     availableForSale: boolean;
     compareAtV2: {
       amount: string;
-      currencyCode: "MNT";
+      currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
     } | null;
     id: string;
     priceV2: {
       amount: string;
-      currencyCode: "MNT";
+      currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
     };
     sku: string | null;
   };
@@ -87,6 +92,14 @@ export declare const CollectionProductNodeFragment: import("gql.tada").TadaDocum
       width: number | null;
     })[];
   };
+  metafields?: {
+    nodes: {
+      key: string;
+      namespace: string;
+      type: "BOOLEAN" | "COLLECTION_REFERENCE" | "COLOR" | "DATE" | "DATE_TIME" | "DECIMAL" | "FILE_REFERENCE" | "INTEGER" | "JSON" | "LIST_BOOLEAN" | "LIST_COLLECTION_REFERENCE" | "LIST_COLOR" | "LIST_DATE" | "LIST_DATE_TIME" | "LIST_DECIMAL" | "LIST_INTEGER" | "LIST_METAOBJECT_REFERENCE" | "LIST_MULTI_LINE_TEXT" | "LIST_PRODUCT_REFERENCE" | "LIST_SINGLE_LINE_TEXT" | "LIST_TAXONOMY_VALUE_REFERENCE" | "LIST_URL" | "LIST_VARIANT_REFERENCE" | "METAOBJECT_REFERENCE" | "MULTI_LINE_TEXT" | "PAGE_REFERENCE" | "PRODUCT_REFERENCE" | "RICH_TEXT" | "SINGLE_LINE_TEXT" | "TAXONOMY_CATEGORY_REFERENCE" | "TAXONOMY_VALUE_REFERENCE" | "URL" | "VARIANT_REFERENCE";
+      value: string;
+    }[];
+  } | undefined;
   options?: {
     id: string;
     linkedMetafield: {
@@ -100,7 +113,7 @@ export declare const CollectionProductNodeFragment: import("gql.tada").TadaDocum
         availableForSale: boolean;
         compareAtV2: {
           amount: string;
-          currencyCode: "MNT";
+          currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
         } | null;
         featuredMedia: {
           __typename?: "ShopFont" | undefined;
@@ -115,7 +128,7 @@ export declare const CollectionProductNodeFragment: import("gql.tada").TadaDocum
         id: string;
         priceV2: {
           amount: string;
-          currencyCode: "MNT";
+          currencyCode: "CNY" | "EUR" | "GBP" | "JPY" | "KRW" | "MNT" | "RUB" | "USD";
         };
         sku: string | null;
       } | null | undefined;
@@ -213,6 +226,9 @@ export declare const fetchCollection: (data: {
   includeOptions?: boolean;
   includeVariants?: boolean;
   locale?: string;
+  /** Storefront-visible metafields (`"namespace.key"`) each card carries, for
+   * the `closest_product_metafield` sources bound on it. Omitted ⇒ none. */
+  metafieldKeys?: readonly string[];
 }) => Promise<CollectionData | null>;
 /** The liquid pass's `collection` drop source. The drop is metadata only
  * (`liquidCollection` maps no products; the grid's own page fetch stays the
@@ -300,6 +316,9 @@ type FetchCollectionPageInput = {
   includeOptions?: boolean;
   includeVariants?: boolean;
   locale?: string;
+  /** Storefront-visible metafields (`"namespace.key"`) each card carries, for
+   * the `closest_product_metafield` sources bound on it. Omitted ⇒ none. */
+  metafieldKeys?: readonly string[];
 };
 /** Server-driven collection listing. Always returns `null` on missing
  * collection / GraphQL error so the route loader can map the failure to
@@ -365,5 +384,23 @@ export declare const fetchCollectionMeta: (h: string, locale?: string | undefine
  * resolution stay lean; the theme loader calls it only when a template binds the
  * description. null on a miss, a failure, or an empty description. */
 export declare function fetchCollectionDescriptionHtml(handle: string, locale?: string): Promise<string | null>;
+/** The collection's storefront metafields keyed `"namespace.key"` — the
+ * `collection_metafield` dynamic source. Kept out of `fetchCollectionMeta` for
+ * the same reason as the description: that lean read is also what every
+ * collection list asks for, so metafields there would be fetched for every
+ * listed collection. The theme loader calls this only when a template binds a
+ * collection metafield. `{}` on a miss or a failure, so the literal renders. */
+export declare const fetchCollectionMetafields: (ref: string, locale?: string) => Promise<MetafieldMap>;
+/** The route collection as the theme loader's dynamic sources read it
+ * (`DynamicSourceCollection` in `@shop-on/theme-loader`): the title off the
+ * lean meta read the theme already made, and a lazy provider for each source
+ * the loader fetches only when a template binds it. One builder so a theme
+ * passes `routeCollectionSource(meta, locale)` and picks up a new provider on
+ * upgrade, instead of every theme re-listing them. */
+export declare function routeCollectionSource(meta: Pick<CollectionMeta, "handle" | "title">, locale?: string): {
+  title: string;
+  getDescriptionHtml: () => Promise<string | null>;
+  getMetafields: () => Promise<MetafieldMap>;
+};
 //#endregion
 export {};

package/dist/collection.js

@@ -2,7 +2,8 @@ import { memoTTL } from "./cache.js";
 import { graphql, request } from "./graphql.js";
 import { getContentVersion } from "./content-version.js";
 import { toFileInfo } from "./files.js";
-import { BadgeTagsFragment } from "./product.js";
+import { metafieldsReader, toMetafieldMap } from "./metafields.js";
+import { BadgeTagsFragment, metafieldKeysKey, metafieldKeysVariables } from "./product.js";
 //#region src/collection.ts
 const CollectionProductNodeFragment = graphql(`
     fragment CollectionProductNode on ShopProduct @_unmask {
@@ -124,6 +125,16 @@ const CollectionProductNodeFragment = graphql(`
           height
         }
       }
+      # Only the metafields a card's bound sources name (one API filter on top
+      # of the storefront-visible gate), and nothing unless some are named.
+      metafields(first: $metafieldFirst, keys: $metafieldKeys) @include(if: $withMetafields) {
+        nodes {
+          namespace
+          key
+          type
+          value
+        }
+      }
     }
   `, [BadgeTagsFragment]);
 const CollectionImageFragment = graphql(`
@@ -164,6 +175,7 @@ function toCollectionProduct(p) {
 		price: toMoney(p.defaultVariant.priceV2),
 		compare_at: p.defaultVariant.compareAtV2 ? toMoney(p.defaultVariant.compareAtV2) : null,
 		media: p.media.nodes.map((n) => toFileInfo(n, { baseWidth: 480 })).filter((m) => m !== null),
+		...p.metafields ? { metafields: toMetafieldMap(p.metafields.nodes) } : {},
 		...p.options ? { options: p.options.map((o) => ({
 			id: o.id,
 			name: o.name,
@@ -223,6 +235,9 @@ const FetchCollectionQuery = graphql(`
       $mediaFirst: Int!
       $includeOptions: Boolean!
       $includeVariants: Boolean = false
+      $withMetafields: Boolean = false
+      $metafieldFirst: Int = 0
+      $metafieldKeys: [MetafieldKeyInput!] = []
     ) {
       collection(handle: $handle, id: $id) {
         title
@@ -252,13 +267,14 @@ function toMoney(m) {
 function parseRef(ref) {
 	return ref.startsWith("gid://") ? { id: ref } : { handle: ref };
 }
-const fetchCollectionCached = memoTTL(async ({ handle, first, mediaFirst, includeOptions, includeVariants, locale }) => {
+const fetchCollectionCached = memoTTL(async ({ handle, first, mediaFirst, includeOptions, includeVariants, locale, metafieldKeys }) => {
 	const c = (await request(FetchCollectionQuery, {
 		...parseRef(handle),
 		first,
 		mediaFirst,
 		includeOptions,
-		...variantsVariable(includeVariants)
+		...variantsVariable(includeVariants),
+		...metafieldKeysVariables(metafieldKeys)
 	}, locale ? { acceptLanguage: locale } : void 0)).collection;
 	if (!c) return null;
 	return {
@@ -270,7 +286,7 @@ const fetchCollectionCached = memoTTL(async ({ handle, first, mediaFirst, includ
 		products: c.products.nodes.map(toCollectionProduct)
 	};
 }, {
-	key: ({ handle, first, mediaFirst, includeOptions, includeVariants, locale }) => `${handle}|${first}|${mediaFirst}|${includeOptions}|${includeVariants}|${locale ?? ""}`,
+	key: ({ handle, first, mediaFirst, includeOptions, includeVariants, locale, metafieldKeys }) => `${handle}|${first}|${mediaFirst}|${includeOptions}|${includeVariants}|${locale ?? ""}|${metafieldKeysKey(metafieldKeys)}`,
 	version: getContentVersion
 });
 const fetchCollection = async (data) => {
@@ -355,6 +371,9 @@ const FetchCollectionPageQuery = graphql(`
       $mediaFirst: Int!
       $includeOptions: Boolean!
       $includeVariants: Boolean = false
+      $withMetafields: Boolean = false
+      $metafieldFirst: Int = 0
+      $metafieldKeys: [MetafieldKeyInput!] = []
       $after: String
       $filter: CollectionProductFilterInput
       $sort: CollectionProductSortEnum
@@ -439,6 +458,7 @@ const fetchCollectionPage = async (data) => {
 			mediaFirst,
 			includeOptions,
 			...variantsVariable(data.includeVariants),
+			...metafieldKeysVariables(data.metafieldKeys),
 			after: after ?? null,
 			filter: filter ?? null,
 			sort: sort ?? null
@@ -493,6 +513,9 @@ const FetchAllProductsQuery = graphql(`
       $mediaFirst: Int!
       $includeOptions: Boolean!
       $includeVariants: Boolean = false
+      $withMetafields: Boolean = false
+      $metafieldFirst: Int = 0
+      $metafieldKeys: [MetafieldKeyInput!] = []
     ) {
       products(first: $first) {
         nodes {
@@ -655,5 +678,43 @@ const fetchCollectionDescriptionRaw = memoTTL(async (handle, locale) => {
 async function fetchCollectionDescriptionHtml(handle, locale) {
 	return await fetchCollectionDescriptionRaw(handle, locale) || null;
 }
+const FetchCollectionMetafieldsQuery = graphql(`
+  query FetchCollectionMetafields($handle: String, $id: ID) {
+    collection(handle: $handle, id: $id) {
+      # Storefront-visible only (the API gates on the storefront scope), so the
+      # set is a shop's published collection fields; 50 matches the product read.
+      metafields(first: 50) {
+        nodes {
+          namespace
+          key
+          type
+          value
+        }
+      }
+    }
+  }
+`);
+/** The collection's storefront metafields keyed `"namespace.key"` — the
+* `collection_metafield` dynamic source. Kept out of `fetchCollectionMeta` for
+* the same reason as the description: that lean read is also what every
+* collection list asks for, so metafields there would be fetched for every
+* listed collection. The theme loader calls this only when a template binds a
+* collection metafield. `{}` on a miss or a failure, so the literal renders. */
+const fetchCollectionMetafields = metafieldsReader("fetchCollectionMetafields", async (handle, locale) => {
+	return (await request(FetchCollectionMetafieldsQuery, parseRef(handle), locale ? { acceptLanguage: locale } : void 0)).collection?.metafields.nodes ?? null;
+});
+/** The route collection as the theme loader's dynamic sources read it
+* (`DynamicSourceCollection` in `@shop-on/theme-loader`): the title off the
+* lean meta read the theme already made, and a lazy provider for each source
+* the loader fetches only when a template binds it. One builder so a theme
+* passes `routeCollectionSource(meta, locale)` and picks up a new provider on
+* upgrade, instead of every theme re-listing them. */
+function routeCollectionSource(meta, locale) {
+	return {
+		title: meta.title,
+		getDescriptionHtml: () => fetchCollectionDescriptionHtml(meta.handle, locale),
+		getMetafields: () => fetchCollectionMetafields(meta.handle, locale)
+	};
+}
 //#endregion
-export { CollectionImageFragment, CollectionProductNodeFragment, fetchAllProducts, fetchCollection, fetchCollectionCard, fetchCollectionDescriptionHtml, fetchCollectionMeta, fetchCollectionPage, fetchCollectionsPage, fetchLiquidCollection, toCollectionProduct, toPriceBounds, variantsVariable };
+export { CollectionImageFragment, CollectionProductNodeFragment, fetchAllProducts, fetchCollection, fetchCollectionCard, fetchCollectionDescriptionHtml, fetchCollectionMeta, fetchCollectionMetafields, fetchCollectionPage, fetchCollectionsPage, fetchLiquidCollection, routeCollectionSource, toCollectionProduct, toPriceBounds, variantsVariable };

package/dist/content-version.d.ts

@@ -3,7 +3,8 @@
  * Per-shop storefront content version. Rails bumps a per-shop counter on any
  * catalog content write and serves it as the storefront `shop.contentVersion`
  * field; the catalog loaders prepend it to their `memoTTL` keys so an edit
- * busts the per-process cache within ~1s instead of waiting out the 60s TTL.
+ * busts the per-process cache within seconds instead of waiting out the 60s
+ * TTL.
  * Stock / availability changes are deliberately NOT covered — they stay on
  * the TTL.
  *
@@ -18,12 +19,17 @@ export declare function createContentVersionReader({ read, fallback, onError }:
   fallback?: string;
   onError?: (error: unknown) => void;
 }): () => Promise<string>;
+/** Set by the storefront shard's router on every request it forwards. */
+export declare const CONTENT_VERSION_HEADER = "x-shard-content-version";
+/** In the env of an isolate whose shard router sets or drops that header. */
+export declare const CONTENT_VERSION_FLAG = "SHARD_FORWARDS_CONTENT_VERSION";
 /**
- * Memoized for 1s so a fan-out of loaders in a single render shares one Rails
- * round trip, and concurrent renders take the lease holder's result — this
- * caps the polling cost at one tiny query per second per isolate, failed reads
- * included (the reader never throws, so its fallback is cached for the TTL).
+ * The version the shard router forwarded with this request (read from Redis by
+ * the orchestrator, at most one resolve cache old: ~5s), else the polled one.
+ * The header counts only under CONTENT_VERSION_FLAG: off a shard, such as
+ * behind `theme dev`'s tunnel or under `wrangler dev`, nothing strips a
+ * caller's copy, and a made-up version would miss every catalog cache entry.
  * Wired into the catalog loaders via the `version` option of `memoTTL`.
  */
-export declare const getContentVersion: () => Promise<string>;
+export declare function getContentVersion(): Promise<string>;
 //#endregion

package/dist/content-version.js

@@ -1,4 +1,5 @@
 import { memoTTL } from "./cache.js";
+import { currentRequest } from "./request-scope.js";
 import { graphql, request } from "./graphql.js";
 //#region src/content-version.ts
 const CONTENT_VERSION_TTL_MS = 1e3;
@@ -7,7 +8,8 @@ const FALLBACK_VERSION = "0";
 * Per-shop storefront content version. Rails bumps a per-shop counter on any
 * catalog content write and serves it as the storefront `shop.contentVersion`
 * field; the catalog loaders prepend it to their `memoTTL` keys so an edit
-* busts the per-process cache within ~1s instead of waiting out the 60s TTL.
+* busts the per-process cache within seconds instead of waiting out the 60s
+* TTL.
 * Stock / availability changes are deliberately NOT covered — they stay on
 * the TTL.
 *
@@ -53,11 +55,30 @@ const readContentVersion = createContentVersionReader({
 * round trip, and concurrent renders take the lease holder's result — this
 * caps the polling cost at one tiny query per second per isolate, failed reads
 * included (the reader never throws, so its fallback is cached for the TTL).
-* Wired into the catalog loaders via the `version` option of `memoTTL`.
 */
-const getContentVersion = memoTTL(readContentVersion, {
+const pollContentVersion = memoTTL(readContentVersion, {
 	ttlMs: CONTENT_VERSION_TTL_MS,
 	key: () => "v"
 });
+/** Set by the storefront shard's router on every request it forwards. */
+const CONTENT_VERSION_HEADER = "x-shard-content-version";
+/** In the env of an isolate whose shard router sets or drops that header. */
+const CONTENT_VERSION_FLAG = "SHARD_FORWARDS_CONTENT_VERSION";
+/**
+* The version the shard router forwarded with this request (read from Redis by
+* the orchestrator, at most one resolve cache old: ~5s), else the polled one.
+* The header counts only under CONTENT_VERSION_FLAG: off a shard, such as
+* behind `theme dev`'s tunnel or under `wrangler dev`, nothing strips a
+* caller's copy, and a made-up version would miss every catalog cache entry.
+* Wired into the catalog loaders via the `version` option of `memoTTL`.
+*/
+function getContentVersion() {
+	return forwardedHeader() ? readForwarded() : pollContentVersion();
+}
+function forwardedHeader() {
+	if (process.env["SHARD_FORWARDS_CONTENT_VERSION"] !== "1") return null;
+	return currentRequest()?.headers.get("x-shard-content-version") || null;
+}
+const readForwarded = createContentVersionReader({ read: async () => forwardedHeader() });
 //#endregion
-export { createContentVersionReader, getContentVersion };
+export { CONTENT_VERSION_FLAG, CONTENT_VERSION_HEADER, createContentVersionReader, getContentVersion };