@shopify/hydrogen 2026.10.0 → 2026.10.2

package/dist/development/core/request-context.mjs

@@ -84,7 +84,7 @@ function applyStorefrontRequestHeaders(context, headers) {
 	headers.set(SDK_VARIANT_HEADER, "hydrogen");
 	headers.set(SDK_VARIANT_SOURCE_HEADER, "kit");
 	headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);
-	headers.set(HYDROGEN_VERSION_HEADER, "2026.10.0");
+	headers.set(HYDROGEN_VERSION_HEADER, "2026.10.2");
 	headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);
 	if (context.cookie) headers.set("cookie", context.cookie);
 	else headers.delete("cookie");

package/dist/development/core/request-routing/interceptors/proxy.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.mjs","names":[],"sources":["../../../../../src/core/request-routing/interceptors/proxy.ts"],"sourcesContent":["import { extractHeaders } from \"../../headers\";\nimport { getLogger } from \"../../logging\";\nimport type { HydrogenRouteInterceptor, HydrogenRoutesOptions } from \"../route-types\";\n\nconst PROXY_TIMEOUT_MS = 30_000;\n\n// Proxy errors are transient and may be buyer-specific: never cache them.\nconst PROXY_ERROR_CACHE_CONTROL = \"no-store\";\n\ntype ScopedLogger = ReturnType<typeof getLogger>;\n\ntype ProxyHeaderContext = HydrogenRoutesOptions & { url: URL };\n\ntype PrepareHeaders<ExtraContext extends object = object> = (\n  headers: Headers,\n  context: ProxyHeaderContext & ExtraContext,\n) => void;\n\ntype ProxyRequestHeaderOptions = (\n  | { allow: readonly string[]; deny?: never }\n  | { allow?: never; deny: readonly string[] }\n) & {\n  prepare?: PrepareHeaders;\n  applyStorefrontHeaders?: boolean;\n};\n\ntype ProxyUpstreamInfo = {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: Headers;\n};\n\ntype ProxyResponseHeaderOptions = {\n  allow?: readonly string[];\n  prepare?: PrepareHeaders<{ response: ProxyUpstreamInfo }>;\n};\n\ntype ProxyResponseRejection = {\n  status: number;\n  body: unknown;\n  logMessage?: string;\n  log?: Record<string, unknown>;\n};\n\ntype ProxyResponseValidation = (\n  upstream: ProxyUpstreamInfo,\n  options: HydrogenRoutesOptions,\n  url: URL,\n) => ProxyResponseRejection | null;\n\ntype ProxyErrorPhase = \"setup\" | \"fetch\";\n\ntype ProxyErrorMapping = { status?: number; body?: unknown };\n\ntype MapProxyError = (error: unknown, phase: ProxyErrorPhase) => ProxyErrorMapping;\n\ntype ProxyDescriptor = {\n  match: RegExp;\n  methods?: readonly string[];\n  formatError?: (message: string) => unknown;\n  redirect?: RequestRedirect;\n  scope: string;\n  timeoutMs?: number;\n  forwardSearch?: boolean;\n  rewritePathname?: (pathname: string) => string;\n  requestHeaders: ProxyRequestHeaderOptions;\n  responseHeaders?: ProxyResponseHeaderOptions;\n  responseValidation?: ProxyResponseValidation;\n  mapError?: MapProxyError;\n};\n\ntype ProxyRequestInit = { upstreamUrl: URL; init: RequestInit & { duplex?: \"half\" } };\n\nexport function createProxyInterceptor(descriptor: ProxyDescriptor): HydrogenRouteInterceptor {\n  const log = getLogger(descriptor.scope);\n  const formatError = descriptor.formatError ?? defaultFormatError;\n\n  return (url, options) => {\n    const { request } = options;\n    if (!descriptor.match.test(url.pathname)) return null;\n\n    // Disable JSONP requests for security:\n    if (url.searchParams.has(\"callback\")) {\n      return Promise.resolve(\n        createProxyRejectionResponse(\n          {\n            status: 400,\n            body: formatError(\"JSONP requests are not supported\"),\n          },\n          request.method,\n        ),\n      );\n    }\n\n    if (descriptor.methods && !descriptor.methods.includes(request.method)) {\n      // Method not allowed. Shape the body via formatError, like other errors.\n      return Promise.resolve(\n        new Response(\n          request.method === \"HEAD\" ? null : JSON.stringify(formatError(\"Method Not Allowed\")),\n          {\n            status: 405,\n            headers: {\n              allow: descriptor.methods.join(\", \"),\n              \"content-type\": \"application/json\",\n              \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n            },\n          },\n        ),\n      );\n    }\n\n    let requestInit: ProxyRequestInit;\n    try {\n      requestInit = createProxyRequestInit(descriptor, options, url);\n    } catch (error) {\n      log.error(\"request failed\", { error });\n      return Promise.resolve(\n        createProxyErrorResponse(error, \"setup\", descriptor.mapError, formatError, request.method),\n      );\n    }\n\n    return fetch(requestInit.upstreamUrl, requestInit.init)\n      .then((upstreamResponse) =>\n        buildProxyResponse(upstreamResponse, descriptor, options, url, log),\n      )\n      .catch((error) => {\n        log.error(\"request failed\", { error });\n        return createProxyErrorResponse(\n          error,\n          \"fetch\",\n          descriptor.mapError,\n          formatError,\n          request.method,\n        );\n      });\n  };\n}\n\nfunction createProxyRequestInit(\n  descriptor: ProxyDescriptor,\n  options: HydrogenRoutesOptions,\n  url: URL,\n): ProxyRequestInit {\n  const { request, storefrontClient } = options;\n  const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;\n  const search = descriptor.forwardSearch === false ? \"\" : url.search;\n  const upstreamUrl = new URL(upstreamPathname + search, storefrontClient.storeUrl);\n  const init: RequestInit & { duplex?: \"half\" } = {\n    method: request.method,\n    body: request.body,\n    headers: createProxyRequestHeaders(descriptor, { ...options, url }),\n    signal: AbortSignal.timeout(descriptor.timeoutMs ?? PROXY_TIMEOUT_MS),\n    redirect: descriptor.redirect ?? \"manual\",\n  };\n\n  // Node's fetch requires this when forwarding a streaming request body.\n  if (request.body) init.duplex = \"half\";\n  return { upstreamUrl, init };\n}\n\nfunction buildProxyResponse(\n  upstreamResponse: Response,\n  descriptor: ProxyDescriptor,\n  options: HydrogenRoutesOptions,\n  url: URL,\n  log: ScopedLogger,\n): Response {\n  const upstream: ProxyUpstreamInfo = {\n    ok: upstreamResponse.ok,\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers: upstreamResponse.headers,\n  };\n\n  const rejection = descriptor.responseValidation?.(upstream, options, url);\n  if (rejection) {\n    // Centralized drain: response hooks receive only a body-less view, so the factory\n    // owns the sole cancellation and no validator can leak the upstream connection.\n    upstreamResponse.body?.cancel().catch(() => {});\n    if (rejection.logMessage) log.error(rejection.logMessage, rejection.log ?? {});\n    return createProxyRejectionResponse(rejection, options.request.method);\n  }\n\n  const headers = buildProxyResponseHeaders(\n    upstreamResponse.headers,\n    descriptor.responseHeaders?.allow,\n  );\n  descriptor.responseHeaders?.prepare?.(headers, { ...options, url, response: upstream });\n  options.requestContext.consumeStorefrontResponseHeaders(headers);\n\n  return new Response(upstreamResponse.body, {\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers,\n  });\n}\n\nfunction defaultFormatError(message: string): { error: string } {\n  return { error: message };\n}\n\nfunction createProxyErrorResponse(\n  error: unknown,\n  phase: ProxyErrorPhase,\n  mapError: MapProxyError | undefined,\n  formatError: (message: string) => unknown,\n  method: string,\n): Response {\n  const message = error instanceof Error ? error.message : \"Internal proxy error\";\n  const mapping = mapError?.(error, phase);\n  const status = mapping?.status ?? (phase === \"setup\" ? 500 : 502);\n  const body = mapping?.body === undefined ? formatError(message) : mapping.body;\n  return createProxyRejectionResponse({ status, body }, method);\n}\n\nfunction createProxyRejectionResponse(rejection: ProxyResponseRejection, method: string): Response {\n  return new Response(method === \"HEAD\" ? null : JSON.stringify(rejection.body), {\n    status: rejection.status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n    },\n  });\n}\n\nfunction createProxyRequestHeaders(\n  descriptor: ProxyDescriptor,\n  options: ProxyHeaderContext,\n): Headers {\n  const { request, requestContext } = options;\n  const { allow, deny, prepare } = descriptor.requestHeaders;\n  const headers = allow\n    ? new Headers(extractHeaders((key) => request.headers.get(key), allow))\n    : new Headers(request.headers);\n\n  if (descriptor.requestHeaders.applyStorefrontHeaders !== false) {\n    requestContext.applyStorefrontRequestHeaders(headers);\n  }\n\n  for (const header of deny ?? []) headers.delete(header);\n  prepare?.(headers, options);\n\n  return headers;\n}\n\nfunction buildProxyResponseHeaders(upstreamHeaders: Headers, allow?: readonly string[]): Headers {\n  if (allow) {\n    const headers = new Headers();\n    for (const name of allow) {\n      const value = upstreamHeaders.get(name);\n      if (value !== null) headers.set(name, value);\n    }\n    return headers;\n  }\n  return createProxyResponseHeaders(upstreamHeaders);\n}\n\nexport function createProxyResponseHeaders(upstreamHeaders: Headers): Headers {\n  const headers = new Headers(upstreamHeaders);\n  headers.delete(\"content-encoding\");\n  headers.delete(\"content-length\");\n  headers.delete(\"server-timing\");\n  return headers;\n}\n"],"mappings":"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"}
+{"version":3,"file":"proxy.mjs","names":[],"sources":["../../../../../src/core/request-routing/interceptors/proxy.ts"],"sourcesContent":["import { extractHeaders } from \"../../headers\";\nimport { getLogger } from \"../../logging\";\nimport type { HydrogenRouteInterceptor, HydrogenRouteInterceptorOptions } from \"../route-types\";\n\nconst PROXY_TIMEOUT_MS = 30_000;\n\n// Proxy errors are transient and may be buyer-specific: never cache them.\nconst PROXY_ERROR_CACHE_CONTROL = \"no-store\";\n\ntype ScopedLogger = ReturnType<typeof getLogger>;\n\ntype ProxyHeaderContext = HydrogenRouteInterceptorOptions & { url: URL };\n\ntype PrepareHeaders<ExtraContext extends object = object> = (\n  headers: Headers,\n  context: ProxyHeaderContext & ExtraContext,\n) => void;\n\ntype ProxyRequestHeaderOptions = (\n  | { allow: readonly string[]; deny?: never }\n  | { allow?: never; deny: readonly string[] }\n) & {\n  prepare?: PrepareHeaders;\n  applyStorefrontHeaders?: boolean;\n};\n\ntype ProxyUpstreamInfo = {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: Headers;\n};\n\ntype ProxyResponseHeaderOptions = {\n  allow?: readonly string[];\n  prepare?: PrepareHeaders<{ response: ProxyUpstreamInfo }>;\n};\n\ntype ProxyResponseRejection = {\n  status: number;\n  body: unknown;\n  logMessage?: string;\n  log?: Record<string, unknown>;\n};\n\ntype ProxyResponseValidation = (\n  upstream: ProxyUpstreamInfo,\n  options: HydrogenRouteInterceptorOptions,\n  url: URL,\n) => ProxyResponseRejection | null;\n\ntype ProxyErrorPhase = \"setup\" | \"fetch\";\n\ntype ProxyErrorMapping = { status?: number; body?: unknown };\n\ntype MapProxyError = (error: unknown, phase: ProxyErrorPhase) => ProxyErrorMapping;\n\ntype ProxyDescriptor = {\n  match: RegExp;\n  methods?: readonly string[];\n  formatError?: (message: string) => unknown;\n  redirect?: RequestRedirect;\n  scope: string;\n  timeoutMs?: number;\n  forwardSearch?: boolean;\n  rewritePathname?: (pathname: string) => string;\n  requestHeaders: ProxyRequestHeaderOptions;\n  responseHeaders?: ProxyResponseHeaderOptions;\n  responseValidation?: ProxyResponseValidation;\n  mapError?: MapProxyError;\n};\n\ntype ProxyRequestInit = { upstreamUrl: URL; init: RequestInit & { duplex?: \"half\" } };\n\nexport function createProxyInterceptor(descriptor: ProxyDescriptor): HydrogenRouteInterceptor {\n  const log = getLogger(descriptor.scope);\n  const formatError = descriptor.formatError ?? defaultFormatError;\n\n  return (url, options) => {\n    const { request } = options;\n    if (!descriptor.match.test(url.pathname)) return null;\n\n    // Disable JSONP requests for security:\n    if (url.searchParams.has(\"callback\")) {\n      return Promise.resolve(\n        createProxyRejectionResponse(\n          {\n            status: 400,\n            body: formatError(\"JSONP requests are not supported\"),\n          },\n          request.method,\n        ),\n      );\n    }\n\n    if (descriptor.methods && !descriptor.methods.includes(request.method)) {\n      // Method not allowed. Shape the body via formatError, like other errors.\n      return Promise.resolve(\n        new Response(\n          request.method === \"HEAD\" ? null : JSON.stringify(formatError(\"Method Not Allowed\")),\n          {\n            status: 405,\n            headers: {\n              allow: descriptor.methods.join(\", \"),\n              \"content-type\": \"application/json\",\n              \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n            },\n          },\n        ),\n      );\n    }\n\n    let requestInit: ProxyRequestInit;\n    try {\n      requestInit = createProxyRequestInit(descriptor, options, url);\n    } catch (error) {\n      log.error(\"request failed\", { error });\n      return Promise.resolve(\n        createProxyErrorResponse(error, \"setup\", descriptor.mapError, formatError, request.method),\n      );\n    }\n\n    return fetch(requestInit.upstreamUrl, requestInit.init)\n      .then((upstreamResponse) =>\n        buildProxyResponse(upstreamResponse, descriptor, options, url, log),\n      )\n      .catch((error) => {\n        log.error(\"request failed\", { error });\n        return createProxyErrorResponse(\n          error,\n          \"fetch\",\n          descriptor.mapError,\n          formatError,\n          request.method,\n        );\n      });\n  };\n}\n\nfunction createProxyRequestInit(\n  descriptor: ProxyDescriptor,\n  options: HydrogenRouteInterceptorOptions,\n  url: URL,\n): ProxyRequestInit {\n  const { request, storefrontClient } = options;\n  const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;\n  const search = descriptor.forwardSearch === false ? \"\" : url.search;\n  const upstreamUrl = new URL(upstreamPathname + search, storefrontClient.storeUrl);\n  const init: RequestInit & { duplex?: \"half\" } = {\n    method: request.method,\n    body: request.body,\n    headers: createProxyRequestHeaders(descriptor, { ...options, url }),\n    signal: AbortSignal.timeout(descriptor.timeoutMs ?? PROXY_TIMEOUT_MS),\n    redirect: descriptor.redirect ?? \"manual\",\n  };\n\n  // Node's fetch requires this when forwarding a streaming request body.\n  if (request.body) init.duplex = \"half\";\n  return { upstreamUrl, init };\n}\n\nfunction buildProxyResponse(\n  upstreamResponse: Response,\n  descriptor: ProxyDescriptor,\n  options: HydrogenRouteInterceptorOptions,\n  url: URL,\n  log: ScopedLogger,\n): Response {\n  const upstream: ProxyUpstreamInfo = {\n    ok: upstreamResponse.ok,\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers: upstreamResponse.headers,\n  };\n\n  const rejection = descriptor.responseValidation?.(upstream, options, url);\n  if (rejection) {\n    // Centralized drain: response hooks receive only a body-less view, so the factory\n    // owns the sole cancellation and no validator can leak the upstream connection.\n    upstreamResponse.body?.cancel().catch(() => {});\n    if (rejection.logMessage) log.error(rejection.logMessage, rejection.log ?? {});\n    return createProxyRejectionResponse(rejection, options.request.method);\n  }\n\n  const headers = buildProxyResponseHeaders(\n    upstreamResponse.headers,\n    descriptor.responseHeaders?.allow,\n  );\n  descriptor.responseHeaders?.prepare?.(headers, { ...options, url, response: upstream });\n  options.requestContext.consumeStorefrontResponseHeaders(headers);\n\n  return new Response(upstreamResponse.body, {\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers,\n  });\n}\n\nfunction defaultFormatError(message: string): { error: string } {\n  return { error: message };\n}\n\nfunction createProxyErrorResponse(\n  error: unknown,\n  phase: ProxyErrorPhase,\n  mapError: MapProxyError | undefined,\n  formatError: (message: string) => unknown,\n  method: string,\n): Response {\n  const message = error instanceof Error ? error.message : \"Internal proxy error\";\n  const mapping = mapError?.(error, phase);\n  const status = mapping?.status ?? (phase === \"setup\" ? 500 : 502);\n  const body = mapping?.body === undefined ? formatError(message) : mapping.body;\n  return createProxyRejectionResponse({ status, body }, method);\n}\n\nfunction createProxyRejectionResponse(rejection: ProxyResponseRejection, method: string): Response {\n  return new Response(method === \"HEAD\" ? null : JSON.stringify(rejection.body), {\n    status: rejection.status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n    },\n  });\n}\n\nfunction createProxyRequestHeaders(\n  descriptor: ProxyDescriptor,\n  options: ProxyHeaderContext,\n): Headers {\n  const { request, requestContext } = options;\n  const { allow, deny, prepare } = descriptor.requestHeaders;\n  const headers = allow\n    ? new Headers(extractHeaders((key) => request.headers.get(key), allow))\n    : new Headers(request.headers);\n\n  if (descriptor.requestHeaders.applyStorefrontHeaders !== false) {\n    requestContext.applyStorefrontRequestHeaders(headers);\n  }\n\n  for (const header of deny ?? []) headers.delete(header);\n  prepare?.(headers, options);\n\n  return headers;\n}\n\nfunction buildProxyResponseHeaders(upstreamHeaders: Headers, allow?: readonly string[]): Headers {\n  if (allow) {\n    const headers = new Headers();\n    for (const name of allow) {\n      const value = upstreamHeaders.get(name);\n      if (value !== null) headers.set(name, value);\n    }\n    return headers;\n  }\n  return createProxyResponseHeaders(upstreamHeaders);\n}\n\nexport function createProxyResponseHeaders(upstreamHeaders: Headers): Headers {\n  const headers = new Headers(upstreamHeaders);\n  headers.delete(\"content-encoding\");\n  headers.delete(\"content-length\");\n  headers.delete(\"server-timing\");\n  return headers;\n}\n"],"mappings":"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"}

package/dist/development/core/request-routing/registered-routes.d.mts

@@ -7,13 +7,17 @@ import { CallableRouteHandler, ShopifyRedirectStatus, ShopifyRouteError, Shopify
  *
  * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.
  *
+ * Annotate the handler's context parameter with only the fields the handler reads, for example
+ * `Omit<ShopifyRouteHandlerContext, "sessionManager">`, so apps without a session manager can
+ * register it.
+ *
  * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.
  * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.
  * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.
  * @returns The handler to add to a handler object.
  * @publicDocs
  */
-declare function createShopifyRouteHandler<const TPathname extends string, const TMethod extends string>(pathname: TPathname, method: TMethod, handler: (context: ShopifyRouteHandlerContext) => Promise<ShopifyRouteHandlerResult>): ShopifyRouteHandler<TPathname, TMethod>;
+declare function createShopifyRouteHandler<const TPathname extends string, const TMethod extends string, TContext extends Partial<ShopifyRouteHandlerContext> = ShopifyRouteHandlerContext>(pathname: TPathname, method: TMethod, handler: (context: TContext) => Promise<ShopifyRouteHandlerResult>): CallableRouteHandler<TContext, ShopifyRouteHandlerResult, TPathname, TMethod>;
 //#endregion
 export { createShopifyRouteHandler };
 //# sourceMappingURL=registered-routes.d.mts.map

package/dist/development/core/request-routing/registered-routes.mjs

@@ -16,6 +16,10 @@ const VALID_REDIRECT_STATUSES = [
 *
 * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.
 *
+* Annotate the handler's context parameter with only the fields the handler reads, for example
+* `Omit<ShopifyRouteHandlerContext, "sessionManager">`, so apps without a session manager can
+* register it.
+*
 * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.
 * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.
 * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.
@@ -32,20 +36,30 @@ function createCallableRouteHandler(pathname, method, handler) {
 	});
 }
 const handleShopifyRouteHandlers = (url, { request, sessionManager, storefrontClient, requestContext, handlers = [] }) => {
-	const context = {
-		request,
-		sessionManager,
-		storefrontClient,
-		requestContext
-	};
 	const routeHandlers = handlers.flatMap((group) => Object.values(group));
 	if (routeHandlers.length === 0) return null;
 	const pathMatches = routeHandlers.filter((entry) => entry.pathname === url.pathname);
 	if (pathMatches.length === 0) return null;
 	const match = pathMatches.find((candidate) => candidate.method === request.method);
 	if (!match) return Promise.resolve(new Response("Method Not Allowed", { status: HTTP_METHOD_NOT_ALLOWED_STATUS }));
-	return match(context).then((result) => createShopifyRouteResponse(result, request));
+	return match({
+		request,
+		sessionManager: sessionManager ?? createMissingSessionManager(url.pathname),
+		storefrontClient,
+		requestContext
+	}).then((result) => createShopifyRouteResponse(result, request));
 };
+function createMissingSessionManager(pathname) {
+	const fail = () => {
+		throw new Error(`The ${pathname} handler needs a session. Pass sessionManager to handleShopifyRoutes.`);
+	};
+	return {
+		getSessionOrigin: fail,
+		getSessionItem: fail,
+		setSessionItem: fail,
+		removeSessionItem: fail
+	};
+}
 function createShopifyRouteResponse(result, request) {
 	if (result.type === "redirect") {
 		const headers = new Headers(result.headers);

package/dist/development/core/request-routing/registered-routes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"registered-routes.mjs","names":[],"sources":["../../../../src/core/request-routing/registered-routes.ts"],"sourcesContent":["import type {\n  CallableRouteHandler,\n  HydrogenRouteInterceptor,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerResult,\n  ShopifyRedirectStatus,\n} from \"./route-types\";\n\nexport type {\n  CallableRouteHandler,\n  ShopifyRouteError,\n  ShopifyRouteErrorResult,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerGroup,\n  ShopifyRouteHandlerResult,\n  ShopifyRouteJsonResult,\n  ShopifyRouteRedirectResult,\n  ShopifyRedirectStatus,\n  ShopifyRouteSessionManager,\n} from \"./route-types\";\n\nconst HTTP_OK_STATUS = 200;\nconst HTTP_SEE_OTHER_STATUS = 303;\nconst HTTP_METHOD_NOT_ALLOWED_STATUS = 405;\nconst HTTP_BAD_REQUEST_STATUS = 400;\nconst VALID_REDIRECT_STATUSES = [\n  301, 302, 303, 307, 308,\n] as const satisfies readonly ShopifyRedirectStatus[];\n\n/**\n * Creates a custom endpoint in your app for one pathname and HTTP method. Collect handlers in an\n * object, and pass an array of handler objects to `handleShopifyRoutes` in its `handlers` option.\n *\n * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.\n *\n * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.\n * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.\n * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.\n * @returns The handler to add to a handler object.\n * @publicDocs\n */\nexport function createShopifyRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: ShopifyRouteHandlerContext) => Promise<ShopifyRouteHandlerResult>,\n): ShopifyRouteHandler<TPathname, TMethod> {\n  return createCallableRouteHandler(pathname, method, handler);\n}\n\nexport function createCallableRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n  TContext,\n  TResult,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: TContext) => Promise<TResult>,\n): CallableRouteHandler<TContext, TResult, TPathname, TMethod> {\n  return Object.assign(handler, { pathname, method });\n}\n\nexport const handleShopifyRouteHandlers: HydrogenRouteInterceptor = (\n  url,\n  { request, sessionManager, storefrontClient, requestContext, handlers = [] },\n) => {\n  const context = { request, sessionManager, storefrontClient, requestContext };\n  const routeHandlers = handlers.flatMap((group) => Object.values(group));\n  if (routeHandlers.length === 0) return null;\n\n  const pathMatches = routeHandlers.filter((entry) => entry.pathname === url.pathname);\n  if (pathMatches.length === 0) return null;\n\n  const match = pathMatches.find((candidate) => candidate.method === request.method);\n  if (!match)\n    return Promise.resolve(\n      new Response(\"Method Not Allowed\", { status: HTTP_METHOD_NOT_ALLOWED_STATUS }),\n    );\n\n  return match(context).then((result) => createShopifyRouteResponse(result, request));\n};\n\nfunction createShopifyRouteResponse(result: ShopifyRouteHandlerResult, request: Request): Response {\n  if (result.type === \"redirect\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"location\", resolveRedirectLocation(result.location, request));\n    return new Response(null, {\n      status: getRedirectStatus(result.status),\n      headers,\n    });\n  }\n\n  if (result.type === \"error\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"content-type\", \"application/json\");\n    return new Response(JSON.stringify({ error: result.error }), {\n      status: result.status ?? HTTP_BAD_REQUEST_STATUS,\n      headers,\n    });\n  }\n\n  const headers = new Headers(result.headers);\n  headers.set(\"content-type\", \"application/json\");\n  return new Response(JSON.stringify(result.data), {\n    status: HTTP_OK_STATUS,\n    headers,\n  });\n}\n\nfunction getRedirectStatus(status: ShopifyRedirectStatus | undefined): ShopifyRedirectStatus {\n  const redirectStatus = status ?? HTTP_SEE_OTHER_STATUS;\n  if (VALID_REDIRECT_STATUSES.some((validStatus) => validStatus === redirectStatus)) {\n    return redirectStatus;\n  }\n\n  throw new Error(\n    `Invalid Shopify route redirect status ${redirectStatus}. Expected one of: ${VALID_REDIRECT_STATUSES.join(\", \")}.`,\n  );\n}\n\nfunction resolveRedirectLocation(location: string, request: Request): string {\n  // Absolute Location headers are the best common denominator: browsers accept\n  // relative redirects, but framework proxy runtimes like Next.js can require\n  // absolute URLs when returning a Response from middleware/proxy code.\n  return new URL(location, new URL(request.url).origin).toString();\n}\n"],"mappings":";AAuBA,MAAM,iBAAiB;AACvB,MAAM,wBAAwB;AAC9B,MAAM,iCAAiC;AACvC,MAAM,0BAA0B;AAChC,MAAM,0BAA0B;CAC9B;CAAK;CAAK;CAAK;CAAK;CACrB;;;;;;;;;;;;;AAcD,SAAgB,0BAId,UACA,QACA,SACyC;AACzC,QAAO,2BAA2B,UAAU,QAAQ,QAAQ;;AAG9D,SAAgB,2BAMd,UACA,QACA,SAC6D;AAC7D,QAAO,OAAO,OAAO,SAAS;EAAE;EAAU;EAAQ,CAAC;;AAGrD,MAAa,8BACX,KACA,EAAE,SAAS,gBAAgB,kBAAkB,gBAAgB,WAAW,EAAE,OACvE;CACH,MAAM,UAAU;EAAE;EAAS;EAAgB;EAAkB;EAAgB;CAC7E,MAAM,gBAAgB,SAAS,SAAS,UAAU,OAAO,OAAO,MAAM,CAAC;AACvE,KAAI,cAAc,WAAW,EAAG,QAAO;CAEvC,MAAM,cAAc,cAAc,QAAQ,UAAU,MAAM,aAAa,IAAI,SAAS;AACpF,KAAI,YAAY,WAAW,EAAG,QAAO;CAErC,MAAM,QAAQ,YAAY,MAAM,cAAc,UAAU,WAAW,QAAQ,OAAO;AAClF,KAAI,CAAC,MACH,QAAO,QAAQ,QACb,IAAI,SAAS,sBAAsB,EAAE,QAAQ,gCAAgC,CAAC,CAC/E;AAEH,QAAO,MAAM,QAAQ,CAAC,MAAM,WAAW,2BAA2B,QAAQ,QAAQ,CAAC;;AAGrF,SAAS,2BAA2B,QAAmC,SAA4B;AACjG,KAAI,OAAO,SAAS,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,YAAY,wBAAwB,OAAO,UAAU,QAAQ,CAAC;AAC1E,SAAO,IAAI,SAAS,MAAM;GACxB,QAAQ,kBAAkB,OAAO,OAAO;GACxC;GACD,CAAC;;AAGJ,KAAI,OAAO,SAAS,SAAS;EAC3B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,OAAO,OAAO,CAAC,EAAE;GAC3D,QAAQ,OAAO,UAAU;GACzB;GACD,CAAC;;CAGJ,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,SAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,QAAO,IAAI,SAAS,KAAK,UAAU,OAAO,KAAK,EAAE;EAC/C,QAAQ;EACR;EACD,CAAC;;AAGJ,SAAS,kBAAkB,QAAkE;CAC3F,MAAM,iBAAiB,UAAU;AACjC,KAAI,wBAAwB,MAAM,gBAAgB,gBAAgB,eAAe,CAC/E,QAAO;AAGT,OAAM,IAAI,MACR,yCAAyC,eAAe,qBAAqB,wBAAwB,KAAK,KAAK,CAAC,GACjH;;AAGH,SAAS,wBAAwB,UAAkB,SAA0B;AAI3E,QAAO,IAAI,IAAI,UAAU,IAAI,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU"}
+{"version":3,"file":"registered-routes.mjs","names":[],"sources":["../../../../src/core/request-routing/registered-routes.ts"],"sourcesContent":["import type {\n  CallableRouteHandler,\n  HydrogenRouteInterceptor,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerResult,\n  ShopifyRedirectStatus,\n  ShopifyRouteSessionManager,\n} from \"./route-types\";\n\nexport type {\n  CallableRouteHandler,\n  ShopifyRouteError,\n  ShopifyRouteErrorResult,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerGroup,\n  ShopifyRouteHandlerResult,\n  ShopifyRouteJsonResult,\n  ShopifyRouteRedirectResult,\n  ShopifyRedirectStatus,\n  ShopifyRouteSessionManager,\n} from \"./route-types\";\n\nconst HTTP_OK_STATUS = 200;\nconst HTTP_SEE_OTHER_STATUS = 303;\nconst HTTP_METHOD_NOT_ALLOWED_STATUS = 405;\nconst HTTP_BAD_REQUEST_STATUS = 400;\nconst VALID_REDIRECT_STATUSES = [\n  301, 302, 303, 307, 308,\n] as const satisfies readonly ShopifyRedirectStatus[];\n\n/**\n * Creates a custom endpoint in your app for one pathname and HTTP method. Collect handlers in an\n * object, and pass an array of handler objects to `handleShopifyRoutes` in its `handlers` option.\n *\n * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.\n *\n * Annotate the handler's context parameter with only the fields the handler reads, for example\n * `Omit<ShopifyRouteHandlerContext, \"sessionManager\">`, so apps without a session manager can\n * register it.\n *\n * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.\n * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.\n * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.\n * @returns The handler to add to a handler object.\n * @publicDocs\n */\nexport function createShopifyRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n  TContext extends Partial<ShopifyRouteHandlerContext> = ShopifyRouteHandlerContext,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: TContext) => Promise<ShopifyRouteHandlerResult>,\n): CallableRouteHandler<TContext, ShopifyRouteHandlerResult, TPathname, TMethod> {\n  return createCallableRouteHandler(pathname, method, handler);\n}\n\nexport function createCallableRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n  TContext,\n  TResult,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: TContext) => Promise<TResult>,\n): CallableRouteHandler<TContext, TResult, TPathname, TMethod> {\n  return Object.assign(handler, { pathname, method });\n}\n\nexport const handleShopifyRouteHandlers: HydrogenRouteInterceptor = (\n  url,\n  { request, sessionManager, storefrontClient, requestContext, handlers = [] },\n) => {\n  const routeHandlers = handlers.flatMap((group) => Object.values(group));\n  if (routeHandlers.length === 0) return null;\n\n  const pathMatches = routeHandlers.filter((entry) => entry.pathname === url.pathname);\n  if (pathMatches.length === 0) return null;\n\n  const match = pathMatches.find((candidate) => candidate.method === request.method);\n  if (!match)\n    return Promise.resolve(\n      new Response(\"Method Not Allowed\", { status: HTTP_METHOD_NOT_ALLOWED_STATUS }),\n    );\n\n  const context = {\n    request,\n    sessionManager: sessionManager ?? createMissingSessionManager(url.pathname),\n    storefrontClient,\n    requestContext,\n  };\n  return match(context).then((result) => createShopifyRouteResponse(result, request));\n};\n\n// The types already require `sessionManager` for handlers that read it; this\n// covers untyped callers, which would otherwise read `undefined` deep inside a handler.\nfunction createMissingSessionManager(pathname: string): ShopifyRouteSessionManager {\n  const fail = (): never => {\n    throw new Error(\n      `The ${pathname} handler needs a session. Pass sessionManager to handleShopifyRoutes.`,\n    );\n  };\n  return {\n    getSessionOrigin: fail,\n    getSessionItem: fail,\n    setSessionItem: fail,\n    removeSessionItem: fail,\n  };\n}\n\nfunction createShopifyRouteResponse(result: ShopifyRouteHandlerResult, request: Request): Response {\n  if (result.type === \"redirect\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"location\", resolveRedirectLocation(result.location, request));\n    return new Response(null, {\n      status: getRedirectStatus(result.status),\n      headers,\n    });\n  }\n\n  if (result.type === \"error\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"content-type\", \"application/json\");\n    return new Response(JSON.stringify({ error: result.error }), {\n      status: result.status ?? HTTP_BAD_REQUEST_STATUS,\n      headers,\n    });\n  }\n\n  const headers = new Headers(result.headers);\n  headers.set(\"content-type\", \"application/json\");\n  return new Response(JSON.stringify(result.data), {\n    status: HTTP_OK_STATUS,\n    headers,\n  });\n}\n\nfunction getRedirectStatus(status: ShopifyRedirectStatus | undefined): ShopifyRedirectStatus {\n  const redirectStatus = status ?? HTTP_SEE_OTHER_STATUS;\n  if (VALID_REDIRECT_STATUSES.some((validStatus) => validStatus === redirectStatus)) {\n    return redirectStatus;\n  }\n\n  throw new Error(\n    `Invalid Shopify route redirect status ${redirectStatus}. Expected one of: ${VALID_REDIRECT_STATUSES.join(\", \")}.`,\n  );\n}\n\nfunction resolveRedirectLocation(location: string, request: Request): string {\n  // Absolute Location headers are the best common denominator: browsers accept\n  // relative redirects, but framework proxy runtimes like Next.js can require\n  // absolute URLs when returning a Response from middleware/proxy code.\n  return new URL(location, new URL(request.url).origin).toString();\n}\n"],"mappings":";AAuBA,MAAM,iBAAiB;AACvB,MAAM,wBAAwB;AAC9B,MAAM,iCAAiC;AACvC,MAAM,0BAA0B;AAChC,MAAM,0BAA0B;CAC9B;CAAK;CAAK;CAAK;CAAK;CACrB;;;;;;;;;;;;;;;;;AAkBD,SAAgB,0BAKd,UACA,QACA,SAC+E;AAC/E,QAAO,2BAA2B,UAAU,QAAQ,QAAQ;;AAG9D,SAAgB,2BAMd,UACA,QACA,SAC6D;AAC7D,QAAO,OAAO,OAAO,SAAS;EAAE;EAAU;EAAQ,CAAC;;AAGrD,MAAa,8BACX,KACA,EAAE,SAAS,gBAAgB,kBAAkB,gBAAgB,WAAW,EAAE,OACvE;CACH,MAAM,gBAAgB,SAAS,SAAS,UAAU,OAAO,OAAO,MAAM,CAAC;AACvE,KAAI,cAAc,WAAW,EAAG,QAAO;CAEvC,MAAM,cAAc,cAAc,QAAQ,UAAU,MAAM,aAAa,IAAI,SAAS;AACpF,KAAI,YAAY,WAAW,EAAG,QAAO;CAErC,MAAM,QAAQ,YAAY,MAAM,cAAc,UAAU,WAAW,QAAQ,OAAO;AAClF,KAAI,CAAC,MACH,QAAO,QAAQ,QACb,IAAI,SAAS,sBAAsB,EAAE,QAAQ,gCAAgC,CAAC,CAC/E;AAQH,QAAO,MAAM;EALX;EACA,gBAAgB,kBAAkB,4BAA4B,IAAI,SAAS;EAC3E;EACA;EAEkB,CAAC,CAAC,MAAM,WAAW,2BAA2B,QAAQ,QAAQ,CAAC;;AAKrF,SAAS,4BAA4B,UAA8C;CACjF,MAAM,aAAoB;AACxB,QAAM,IAAI,MACR,OAAO,SAAS,uEACjB;;AAEH,QAAO;EACL,kBAAkB;EAClB,gBAAgB;EAChB,gBAAgB;EAChB,mBAAmB;EACpB;;AAGH,SAAS,2BAA2B,QAAmC,SAA4B;AACjG,KAAI,OAAO,SAAS,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,YAAY,wBAAwB,OAAO,UAAU,QAAQ,CAAC;AAC1E,SAAO,IAAI,SAAS,MAAM;GACxB,QAAQ,kBAAkB,OAAO,OAAO;GACxC;GACD,CAAC;;AAGJ,KAAI,OAAO,SAAS,SAAS;EAC3B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,OAAO,OAAO,CAAC,EAAE;GAC3D,QAAQ,OAAO,UAAU;GACzB;GACD,CAAC;;CAGJ,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,SAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,QAAO,IAAI,SAAS,KAAK,UAAU,OAAO,KAAK,EAAE;EAC/C,QAAQ;EACR;EACD,CAAC;;AAGJ,SAAS,kBAAkB,QAAkE;CAC3F,MAAM,iBAAiB,UAAU;AACjC,KAAI,wBAAwB,MAAM,gBAAgB,gBAAgB,eAAe,CAC/E,QAAO;AAGT,OAAM,IAAI,MACR,yCAAyC,eAAe,qBAAqB,wBAAwB,KAAK,KAAK,CAAC,GACjH;;AAGH,SAAS,wBAAwB,UAAkB,SAA0B;AAI3E,QAAO,IAAI,IAAI,UAAU,IAAI,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU"}

package/dist/development/core/request-routing/route-types.d.mts

@@ -66,16 +66,26 @@ type ShopifyRouteHandler<TPathname extends string = string, TMethod extends stri
  * @publicDocs
  */
 type ShopifyRouteHandlerGroup = Record<string, ShopifyRouteHandler>;
-/** The request, its context and session, the Storefront API client, your route templates, and your handler groups. */
-interface HydrogenRoutesOptions extends ShopifyRouteHandlerContext {
+type ShopifyRouteHandlerGroups = readonly ShopifyRouteHandlerGroup[];
+type HandlerContext<THandler> = THandler extends ((context: infer TContext) => unknown) ? TContext : never;
+type RouteHandlerContext<TGroup> = TGroup extends unknown ? HandlerContext<TGroup[Extract<keyof TGroup, string | number>]> : never;
+type RequiresSessionManager<TContext> = TContext extends unknown ? "sessionManager" extends keyof TContext ? true : false : never;
+type SessionManagerOption<THandlers extends ShopifyRouteHandlerGroups | undefined> = true extends RequiresSessionManager<RouteHandlerContext<NonNullable<THandlers>[number]>> ? {
+  sessionManager: ShopifyRouteSessionManager;
+} : {
+  sessionManager?: ShopifyRouteSessionManager;
+};
+type HydrogenRoutesBaseOptions = Omit<ShopifyRouteHandlerContext, "sessionManager"> & {
   /**
    * Your app's route templates. Hydrogen redirects Liquid-style `?variant=` URLs on your product paths and on Shopify's default product paths.
    */
   routeTemplates?: ShopifyRouteTemplates;
-  /** The handler groups for your app's custom endpoints. */
-  handlers?: readonly ShopifyRouteHandlerGroup[];
-}
-type HydrogenRouteHandler<TExtraOptions extends object = object> = (options: HydrogenRoutesOptions & TExtraOptions) => null | Promise<Response>;
+};
+/** The request, its context, the Storefront API client, your route templates, your handler groups, and the session when a handler needs it. */
+type HydrogenRoutesOptions<THandlers extends ShopifyRouteHandlerGroups | undefined = ShopifyRouteHandlerGroups> = HydrogenRoutesBaseOptions & {
+  /** The handler groups for your app's custom endpoints. */handlers?: THandlers;
+} & SessionManagerOption<THandlers>;
+type HydrogenRouteHandler<TExtraOptions extends object = object> = <THandlers extends ShopifyRouteHandlerGroups | undefined = readonly []>(options: HydrogenRoutesOptions<THandlers> & TExtraOptions) => null | Promise<Response>;
 //#endregion
 export { CallableRouteHandler, HydrogenRouteHandler, ShopifyRedirectStatus, ShopifyRouteError, ShopifyRouteErrorResult, ShopifyRouteHandler, ShopifyRouteHandlerContext, ShopifyRouteHandlerGroup, ShopifyRouteHandlerResult, ShopifyRouteJsonResult, ShopifyRouteRedirectResult, ShopifyRouteSessionManager };
 //# sourceMappingURL=route-types.d.mts.map

package/dist/development/core/shopify-scripts/perfkit.mjs

@@ -1,8 +1,10 @@
+import { SHOPIFY_API_PROXY_PREFIX } from "../url.mjs";
 import { SHOPIFY_PERF_KIT_SCRIPT, SHOPIFY_PERF_KIT_SCRIPT_ID } from "./constants.mjs";
 
 //#region src/core/shopify-scripts/perfkit.ts
 const SHOPIFY_SHOP_ID_PATTERN = /^\d+$/;
-function getPerfKitScript(shop, extraAttributes) {
+const SHS_BEACON_ENDPOINT = `${SHOPIFY_API_PROXY_PREFIX}/api/collect`;
+function getPerfKitScript(shop, extraAttributes, { shs = false } = {}) {
 	if (!shop.storefrontId) return;
 	const shopId = parseNumericShopId(shop.shopId);
 	if (!shopId) return;
@@ -18,7 +20,11 @@ function getPerfKitScript(shop, extraAttributes) {
 			"data-storefront-id": shop.storefrontId,
 			"data-monorail-region": "global",
 			"data-spa-mode": "true",
-			"data-resource-timing-sampling-rate": "10"
+			"data-resource-timing-sampling-rate": "10",
+			...shs ? {
+				"data-shs": "true",
+				"data-shs-beacon-endpoint": SHS_BEACON_ENDPOINT
+			} : {}
 		}
 	};
 }

package/dist/development/core/shopify-scripts/perfkit.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"perfkit.mjs","names":[],"sources":["../../../../src/core/shopify-scripts/perfkit.ts"],"sourcesContent":["import { SHOPIFY_PERF_KIT_SCRIPT, SHOPIFY_PERF_KIT_SCRIPT_ID } from \"./constants\";\nimport type {\n  ShopifyScriptDescriptor,\n  ShopifyScriptsShop,\n  ShopifyScriptTagAttributes,\n} from \"./types\";\n\nconst SHOPIFY_SHOP_ID_PATTERN = /^\\d+$/;\n\nexport function getPerfKitScript(\n  shop: ShopifyScriptsShop,\n  extraAttributes?: Pick<ShopifyScriptTagAttributes, \"nonce\">,\n): ShopifyScriptDescriptor | undefined {\n  if (!shop.storefrontId) return;\n\n  const shopId = parseNumericShopId(shop.shopId);\n  if (!shopId) return;\n\n  return {\n    tagName: \"script\",\n    attributes: {\n      id: SHOPIFY_PERF_KIT_SCRIPT_ID,\n      ...extraAttributes,\n      async: true,\n      src: SHOPIFY_PERF_KIT_SCRIPT,\n      \"data-application\": \"hydrogen\",\n      \"data-shop-id\": shopId,\n      \"data-storefront-id\": shop.storefrontId,\n      \"data-monorail-region\": \"global\",\n      \"data-spa-mode\": \"true\",\n      \"data-resource-timing-sampling-rate\": \"10\",\n    },\n  };\n}\n\nfunction parseNumericShopId(shopId: ShopifyScriptsShop[\"shopId\"]): string | undefined {\n  const parsedShopId = shopId.split(\"/\").pop();\n  if (!parsedShopId) return;\n\n  return SHOPIFY_SHOP_ID_PATTERN.test(parsedShopId) ? parsedShopId : undefined;\n}\n"],"mappings":";;;AAOA,MAAM,0BAA0B;AAEhC,SAAgB,iBACd,MACA,iBACqC;AACrC,KAAI,CAAC,KAAK,aAAc;CAExB,MAAM,SAAS,mBAAmB,KAAK,OAAO;AAC9C,KAAI,CAAC,OAAQ;AAEb,QAAO;EACL,SAAS;EACT,YAAY;GACV,IAAI;GACJ,GAAG;GACH,OAAO;GACP,KAAK;GACL,oBAAoB;GACpB,gBAAgB;GAChB,sBAAsB,KAAK;GAC3B,wBAAwB;GACxB,iBAAiB;GACjB,sCAAsC;GACvC;EACF;;AAGH,SAAS,mBAAmB,QAA0D;CACpF,MAAM,eAAe,OAAO,MAAM,IAAI,CAAC,KAAK;AAC5C,KAAI,CAAC,aAAc;AAEnB,QAAO,wBAAwB,KAAK,aAAa,GAAG,eAAe"}
+{"version":3,"file":"perfkit.mjs","names":[],"sources":["../../../../src/core/shopify-scripts/perfkit.ts"],"sourcesContent":["import { SHOPIFY_API_PROXY_PREFIX } from \"../url\";\nimport { SHOPIFY_PERF_KIT_SCRIPT, SHOPIFY_PERF_KIT_SCRIPT_ID } from \"./constants\";\nimport type {\n  ShopifyScriptDescriptor,\n  ShopifyScriptsShop,\n  ShopifyScriptTagAttributes,\n} from \"./types\";\n\nconst SHOPIFY_SHOP_ID_PATTERN = /^\\d+$/;\nconst SHS_BEACON_ENDPOINT = `${SHOPIFY_API_PROXY_PREFIX}/api/collect`;\n\ntype PerfKitScriptOptions = {\n  shs?: boolean;\n};\n\nexport function getPerfKitScript(\n  shop: ShopifyScriptsShop,\n  extraAttributes?: Pick<ShopifyScriptTagAttributes, \"nonce\">,\n  { shs = !__DEV__ }: PerfKitScriptOptions = {},\n): ShopifyScriptDescriptor | undefined {\n  if (!shop.storefrontId) return;\n\n  const shopId = parseNumericShopId(shop.shopId);\n  if (!shopId) return;\n\n  return {\n    tagName: \"script\",\n    attributes: {\n      id: SHOPIFY_PERF_KIT_SCRIPT_ID,\n      ...extraAttributes,\n      async: true,\n      src: SHOPIFY_PERF_KIT_SCRIPT,\n      \"data-application\": \"hydrogen\",\n      \"data-shop-id\": shopId,\n      \"data-storefront-id\": shop.storefrontId,\n      \"data-monorail-region\": \"global\",\n      \"data-spa-mode\": \"true\",\n      \"data-resource-timing-sampling-rate\": \"10\",\n      ...(shs\n        ? {\n            \"data-shs\": \"true\",\n            \"data-shs-beacon-endpoint\": SHS_BEACON_ENDPOINT,\n          }\n        : {}),\n    },\n  };\n}\n\nfunction parseNumericShopId(shopId: ShopifyScriptsShop[\"shopId\"]): string | undefined {\n  const parsedShopId = shopId.split(\"/\").pop();\n  if (!parsedShopId) return;\n\n  return SHOPIFY_SHOP_ID_PATTERN.test(parsedShopId) ? parsedShopId : undefined;\n}\n"],"mappings":";;;;AAQA,MAAM,0BAA0B;AAChC,MAAM,sBAAsB,GAAG,yBAAyB;AAMxD,SAAgB,iBACd,MACA,iBACA,EAAE,MAAM,UAAmC,EAAE,EACR;AACrC,KAAI,CAAC,KAAK,aAAc;CAExB,MAAM,SAAS,mBAAmB,KAAK,OAAO;AAC9C,KAAI,CAAC,OAAQ;AAEb,QAAO;EACL,SAAS;EACT,YAAY;GACV,IAAI;GACJ,GAAG;GACH,OAAO;GACP,KAAK;GACL,oBAAoB;GACpB,gBAAgB;GAChB,sBAAsB,KAAK;GAC3B,wBAAwB;GACxB,iBAAiB;GACjB,sCAAsC;GACtC,GAAI,MACA;IACE,YAAY;IACZ,4BAA4B;IAC7B,GACD,EAAE;GACP;EACF;;AAGH,SAAS,mBAAmB,QAA0D;CACpF,MAAM,eAAe,OAAO,MAAM,IAAI,CAAC,KAAK;AAC5C,KAAI,CAAC,aAAc;AAEnB,QAAO,wBAAwB,KAAK,aAAa,GAAG,eAAe"}

package/dist/development/core/utils/load-script.mjs

@@ -10,6 +10,12 @@ function loadScript(src, options) {
 	const promise = new Promise((resolve, reject) => {
 		const script = document.createElement("script");
 		script.type = options?.module ? "module" : "text/javascript";
+		if (options?.attributes) {
+			const { attributes } = options;
+			Object.keys(attributes).forEach((key) => {
+				script.setAttribute(key, attributes[key]);
+			});
+		}
 		script.src = src;
 		script.addEventListener("load", () => resolve(true));
 		script.addEventListener("error", () => {
@@ -18,12 +24,6 @@ function loadScript(src, options) {
 		});
 		if (options?.in === "head") document.head.appendChild(script);
 		else document.body.appendChild(script);
-		if (options?.attributes) {
-			const { attributes } = options;
-			Object.keys(attributes).forEach((key) => {
-				script.setAttribute(key, attributes[key]);
-			});
-		}
 	});
 	SCRIPTS_LOADED[src] = promise;
 	return promise;

package/dist/development/core/utils/load-script.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-script.mjs","names":[],"sources":["../../../../src/core/utils/load-script.ts"],"sourcesContent":["/**\n * Inlined from @shopify/hydrogen-react/load-script.\n * Pure DOM script loader with no framework dependency.\n */\n\nconst SCRIPTS_LOADED: Record<string, Promise<boolean>> = {};\n\ntype LoadScriptOptions = {\n  module?: boolean;\n  in?: \"head\" | \"body\";\n  attributes?: Record<string, string>;\n};\n\nexport function loadScript(src: string, options?: LoadScriptOptions): Promise<boolean> {\n  const isScriptLoaded = SCRIPTS_LOADED[src];\n  if (isScriptLoaded) return isScriptLoaded;\n\n  const promise = new Promise<boolean>((resolve, reject) => {\n    const script = document.createElement(\"script\");\n    script.type = options?.module ? \"module\" : \"text/javascript\";\n    script.src = src;\n    script.addEventListener(\"load\", () => resolve(true));\n    script.addEventListener(\"error\", () => {\n      delete SCRIPTS_LOADED[src];\n      reject(false);\n    });\n\n    if (options?.in === \"head\") {\n      document.head.appendChild(script);\n    } else {\n      document.body.appendChild(script);\n    }\n\n    if (options?.attributes) {\n      const { attributes } = options;\n      Object.keys(attributes).forEach((key) => {\n        script.setAttribute(key, attributes[key]);\n      });\n    }\n  });\n\n  SCRIPTS_LOADED[src] = promise;\n  return promise;\n}\n"],"mappings":";;;;;AAKA,MAAM,iBAAmD,EAAE;AAQ3D,SAAgB,WAAW,KAAa,SAA+C;CACrF,MAAM,iBAAiB,eAAe;AACtC,KAAI,eAAgB,QAAO;CAE3B,MAAM,UAAU,IAAI,SAAkB,SAAS,WAAW;EACxD,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,SAAO,OAAO,SAAS,SAAS,WAAW;AAC3C,SAAO,MAAM;AACb,SAAO,iBAAiB,cAAc,QAAQ,KAAK,CAAC;AACpD,SAAO,iBAAiB,eAAe;AACrC,UAAO,eAAe;AACtB,UAAO,MAAM;IACb;AAEF,MAAI,SAAS,OAAO,OAClB,UAAS,KAAK,YAAY,OAAO;MAEjC,UAAS,KAAK,YAAY,OAAO;AAGnC,MAAI,SAAS,YAAY;GACvB,MAAM,EAAE,eAAe;AACvB,UAAO,KAAK,WAAW,CAAC,SAAS,QAAQ;AACvC,WAAO,aAAa,KAAK,WAAW,KAAK;KACzC;;GAEJ;AAEF,gBAAe,OAAO;AACtB,QAAO"}
+{"version":3,"file":"load-script.mjs","names":[],"sources":["../../../../src/core/utils/load-script.ts"],"sourcesContent":["/**\n * Inlined from @shopify/hydrogen-react/load-script.\n * Pure DOM script loader with no framework dependency.\n */\n\nconst SCRIPTS_LOADED: Record<string, Promise<boolean>> = {};\n\ntype LoadScriptOptions = {\n  module?: boolean;\n  in?: \"head\" | \"body\";\n  attributes?: Record<string, string>;\n};\n\nexport function loadScript(src: string, options?: LoadScriptOptions): Promise<boolean> {\n  const isScriptLoaded = SCRIPTS_LOADED[src];\n  if (isScriptLoaded) return isScriptLoaded;\n\n  const promise = new Promise<boolean>((resolve, reject) => {\n    const script = document.createElement(\"script\");\n    script.type = options?.module ? \"module\" : \"text/javascript\";\n\n    if (options?.attributes) {\n      const { attributes } = options;\n      Object.keys(attributes).forEach((key) => {\n        script.setAttribute(key, attributes[key]);\n      });\n    }\n\n    script.src = src;\n    script.addEventListener(\"load\", () => resolve(true));\n    script.addEventListener(\"error\", () => {\n      delete SCRIPTS_LOADED[src];\n      reject(false);\n    });\n\n    if (options?.in === \"head\") {\n      document.head.appendChild(script);\n    } else {\n      document.body.appendChild(script);\n    }\n  });\n\n  SCRIPTS_LOADED[src] = promise;\n  return promise;\n}\n"],"mappings":";;;;;AAKA,MAAM,iBAAmD,EAAE;AAQ3D,SAAgB,WAAW,KAAa,SAA+C;CACrF,MAAM,iBAAiB,eAAe;AACtC,KAAI,eAAgB,QAAO;CAE3B,MAAM,UAAU,IAAI,SAAkB,SAAS,WAAW;EACxD,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,SAAO,OAAO,SAAS,SAAS,WAAW;AAE3C,MAAI,SAAS,YAAY;GACvB,MAAM,EAAE,eAAe;AACvB,UAAO,KAAK,WAAW,CAAC,SAAS,QAAQ;AACvC,WAAO,aAAa,KAAK,WAAW,KAAK;KACzC;;AAGJ,SAAO,MAAM;AACb,SAAO,iBAAiB,cAAc,QAAQ,KAAK,CAAC;AACpD,SAAO,iBAAiB,eAAe;AACrC,UAAO,eAAe;AACtB,UAAO,MAAM;IACb;AAEF,MAAI,SAAS,OAAO,OAClB,UAAS,KAAK,YAAY,OAAO;MAEjC,UAAS,KAAK,YAAY,OAAO;GAEnC;AAEF,gBAAe,OAAO;AACtB,QAAO"}

package/dist/development/graphql/type-resolver.d.mts

@@ -245,6 +245,32 @@ type InferResult<T extends string> = InferResultForSchema<T, StorefrontSchema>;
 type InferVariables<T extends string> = InferVariablesForSchema<T, StorefrontSchema>;
 /** The operation kind of a query string, such as `query`. Resolves to `unknown` unless the query text has exactly one operation. */
 type InferOperationKind<T extends string> = parseDocument<T> extends infer Doc ? [Doc] extends [never] ? "unknown" : OperationKindType<Doc> : "unknown";
+type DeclaredNameOfType<Definition, Types> = Definition extends {
+  variable: {
+    name: {
+      value: infer Name extends keyof Types;
+    };
+  };
+  type: infer Type;
+} ? (Type extends {
+  kind: "NonNullType";
+  type: infer Inner;
+} ? Inner : Type) extends {
+  kind: "NamedType";
+  name: {
+    value: Types[Name];
+  };
+} ? Name : never : never;
+/**
+ * Names of the first operation's variables that are declared with the named
+ * type `Types` maps them to, nullable or non-null. List types never match.
+ */
+type InferVariableNamesDeclaredAs<T extends string, Types extends Record<string, string>> = parseDocument<T> extends infer Doc ? Doc extends {
+  kind: "Document";
+  definitions: infer Defs extends readonly unknown[];
+} ? FirstOperation<Defs> extends {
+  variableDefinitions: infer Vars extends readonly unknown[];
+} ? DeclaredNameOfType<Vars[number], Types> : never : never : never;
 //#endregion
-export { InferOperationKind, InferResult, InferVariables };
+export { InferOperationKind, InferResult, InferVariableNamesDeclaredAs, InferVariables };
 //# sourceMappingURL=type-resolver.d.mts.map

package/dist/development/react/cart.mjs

@@ -50,9 +50,7 @@ function createCartComponents() {
 		return useOptionalCart((state) => selector(state), isEqual);
 	}
 	function useSuspenseCart(selector, isEqual) {
-		const readyPromise = useCart((state) => state.readyPromise);
-		if (readyPromise) throw readyPromise;
-		return useCart(selector, isEqual);
+		return useSuspenseCartSelector(selector, isEqual);
 	}
 	return {
 		CartProvider: TypedCartProvider,
@@ -64,11 +62,14 @@ function createCartComponents() {
 	};
 }
 function useCartStore(hookName = "useCart") {
-	const store = useContext(CartContext);
-	if (!store) throw new Error(`${hookName} must be used inside <CartProvider>.`);
-	return store;
+	return useCartContext(hookName).store;
 }
-function useOptionalCartStore() {
+function useCartContext(hookName = "useCart") {
+	const context = useContext(CartContext);
+	if (!context) throw new Error(`${hookName} must be used inside <CartProvider>.`);
+	return context;
+}
+function useOptionalCartContext() {
 	return useContext(CartContext);
 }
 /**
@@ -88,7 +89,14 @@ function useOptionalCartStore() {
 * @publicDocs
 */
 function CartProvider({ initialData, children }) {
-	const store = useMemo(() => createCartStore({ initialData }), []);
+	const context = useMemo(() => {
+		const store = createCartStore({ initialData });
+		return {
+			store,
+			hydrationSnapshot: store.getState()
+		};
+	}, []);
+	const { store } = context;
 	useEffect(() => {
 		configureCartEndpoint(cartEndpoint);
 		store.connect();
@@ -97,7 +105,7 @@ function CartProvider({ initialData, children }) {
 		};
 	}, [store]);
 	return /* @__PURE__ */ jsx(CartContext.Provider, {
-		value: store,
+		value: context,
 		children
 	});
 }
@@ -127,7 +135,8 @@ function CartProvider({ initialData, children }) {
 * @publicDocs
 */
 function useCart(selector, isEqual) {
-	return useCartSelector(useCartStore(), selector, isEqual);
+	const { store, hydrationSnapshot } = useCartContext();
+	return useCartSelector(store, hydrationSnapshot, selector, isEqual);
 }
 /**
 * Returns the cart action that reloads the cart after a cart change outside cart forms.
@@ -194,32 +203,77 @@ function useCartAnalytics() {
 * @publicDocs
 */
 function useOptionalCart(selector, isEqual) {
-	const store = useOptionalCartStore();
-	if (!store) return void 0;
-	return useCartSelector(store, selector, isEqual);
+	const context = useOptionalCartContext();
+	if (!context) return void 0;
+	return useCartSelector(context.store, context.hydrationSnapshot, selector, isEqual);
 }
-function useCartSelector(store, selector, isEqual) {
-	const cachedRef = useRef(null);
+function useCartSelector(store, hydrationSnapshot, selector, isEqual) {
+	const liveCacheRef = useRef(null);
+	const hydrationCacheRef = useRef(null);
+	const getSnapshot = () => selectCartSnapshot(store.getState(), selector, isEqual, liveCacheRef);
+	const getServerSnapshot = () => selectCartSnapshot(hydrationSnapshot, selector, isEqual, hydrationCacheRef);
+	return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+function selectCartSnapshot(state, selector, isEqual, cacheRef) {
+	if (cacheRef.current?.state === state && cacheRef.current.selector === selector) return cacheRef.current.value;
+	const next = selector(state);
+	if (cacheRef.current && isEqual?.(cacheRef.current.value, next)) {
+		cacheRef.current = {
+			state,
+			selector,
+			value: cacheRef.current.value
+		};
+		return cacheRef.current.value;
+	}
+	cacheRef.current = {
+		state,
+		selector,
+		value: next
+	};
+	return next;
+}
+function useSuspenseCartSelector(selector, isEqual) {
+	const { store } = useCartContext();
+	const cacheRef = useRef(null);
 	const getSnapshot = () => {
 		const state = store.getState();
-		if (cachedRef.current && cachedRef.current.state === state && cachedRef.current.selector === selector) return cachedRef.current.value;
-		const next = selector(state);
-		if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {
-			cachedRef.current = {
+		if (cacheRef.current?.state === state && cacheRef.current.selector === selector) return cacheRef.current.snapshot;
+		if (state.readyPromise) {
+			const snapshot = {
+				status: "pending",
+				promise: state.readyPromise
+			};
+			cacheRef.current = {
 				state,
 				selector,
-				value: cachedRef.current.value
+				snapshot
 			};
-			return cachedRef.current.value;
+			return snapshot;
 		}
-		cachedRef.current = {
+		const value = selector(state);
+		const previous = cacheRef.current?.snapshot;
+		if (previous?.status === "ready" && isEqual?.(previous.value, value)) {
+			cacheRef.current = {
+				state,
+				selector,
+				snapshot: previous
+			};
+			return previous;
+		}
+		const snapshot = {
+			status: "ready",
+			value
+		};
+		cacheRef.current = {
 			state,
 			selector,
-			value: next
+			snapshot
 		};
-		return next;
+		return snapshot;
 	};
-	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+	const snapshot = useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+	if (snapshot.status === "pending") throw snapshot.promise;
+	return snapshot.value;
 }
 /**
 * Returns form props and a field register function for building cart forms.

package/dist/development/react/cart.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cart.mjs","names":[],"sources":["../../../src/react/cart.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type RefCallback,\n  type SubmitEvent,\n} from \"react\";\n\nimport { trackCartAnalytics } from \"../core/analytics/cart-tracker\";\nimport { attachQuantityInput } from \"../core/cart/attach-quantity-input\";\nimport {\n  configureCartEndpoint as configureCoreCartEndpoint,\n  createCartStore,\n  type CreateCartStoreOptions,\n  type CartActions,\n  type CartStore,\n} from \"../core/cart/cart\";\nimport { createCartFormRegister, type CartFormRegister } from \"../core/cart/form\";\nimport type { CartDataFromHandlers } from \"../core/cart/server-handlers\";\nimport { type CartData, type CartState } from \"../core/cart/state\";\n\nconst DEFAULT_CART_ENDPOINT = \"/api/cart\";\n\nlet cartEndpoint = DEFAULT_CART_ENDPOINT;\n\nconst CartContext = createContext<CartStore | null>(null);\n\nexport function configureCartEndpoint(endpoint: string): void {\n  cartEndpoint = endpoint;\n  configureCoreCartEndpoint(endpoint);\n}\n\nexport function getCartEndpoint(): string {\n  return cartEndpoint;\n}\n\n/**\n * Props for the cart provider that `createCartComponents` returns.\n */\ntype TypedCartProviderProps<TData extends CartData> = {\n  /**\n   * The `data` property of the cart GET handler's result, or a promise of that data. Without initial data, the store loads the cart from `/api/cart` after the provider mounts, and the server-rendered page shows an empty cart. The provider creates its store from the first value and ignores later changes.\n   */\n  initialData?: CartInitialData<TData>;\n  /** Content that can read the cart through the cart hooks. */\n  children?: ReactNode;\n};\n\ntype CartInitialData<TData extends CartData = CartData> =\n  CreateCartStoreOptions<TData>[\"initialData\"];\n\nexport type { CartActions };\n\n/** A hook that returns the slice of cart state that your selector picks. */\ntype CartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;\n\n/** A hook that returns the slice of cart state that your selector picks, or `undefined` outside the cart provider. */\ntype OptionalCartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value, or `undefined` outside the cart provider.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S | undefined;\n\n/** Callbacks that run around a cart form submission. */\ninterface CartFormPropsOptions {\n  /** Runs before the cart store handles the submission. Call `event.preventDefault()` to skip the cart submission. */\n  beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  /** Runs as soon as the cart change starts, before the server responds. */\n  afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n}\n\n/** The form props function and the register function for a cart form. */\ninterface CartFormBindings {\n  /** Returns the `method`, `action`, and `onSubmit` props to spread on the form. The form posts to the cart endpoint, and the cart store handles each submission. */\n  formProps: (opts?: CartFormPropsOptions) => FormHTMLAttributes<HTMLFormElement>;\n  /** Returns the attributes for a cart field or action button. Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled. */\n  register: CartFormRegister;\n}\n\n/**\n * The cart provider and hooks that `createCartComponents` returns, typed with the custom cart fields from your cart server handlers.\n */\ntype TypedCartComponents<TData extends CartData> = {\n  /** Creates the cart store and shares the store with the cart hooks inside the provider. The provider connects the store on mount and destroys the store on unmount. */\n  CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;\n  /**\n   * Returns the slice of cart state that the selector picks. The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n   */\n  useCart: CartStateHook<TData>;\n  /** Suspends while the full cart loads, then returns the slice of cart state that the selector picks. Wrap the component in a `Suspense` boundary. */\n  useSuspenseCart: CartStateHook<TData>;\n  /**\n   * Returns the slice of cart state that the selector picks, or `undefined` outside the provider. Use the hook in a component that also renders above the provider, such as a cart badge on an error page.\n   */\n  useOptionalCart: OptionalCartStateHook<TData>;\n  /** Returns the `refresh()` action. Call `refresh()` after a server-side cart change that skips cart forms. */\n  useCartActions: typeof useCartActions;\n  /** Returns form props and a register function for cart forms. */\n  useCartForm: typeof useCartForm;\n};\n\n/**\n * Returns a cart provider and cart hooks typed to the cart fragment in your cart server handlers.\n * Pass `typeof cartServerHandlers` as the `THandlers` type argument. Every hook's cart state then includes your custom cart fields.\n *\n * On mount, the provider sends cart requests to `/api/cart` and connects the store. Every hook except `useOptionalCart` throws when you call it outside the provider.\n *\n * @returns The cart provider, the cart state hooks, and the cart actions and form hooks.\n *\n * @example\n * ```tsx\n * import type { cartServerHandlers } from \"./server/cart.server\";\n *\n * const {\n *   CartProvider,\n *   useCart,\n *   useSuspenseCart,\n *   useOptionalCart,\n *   useCartActions,\n *   useCartForm,\n * } = createCartComponents<typeof cartServerHandlers>();\n * ```\n * @publicDocs\n */\nexport function createCartComponents<THandlers>(): TypedCartComponents<\n  CartDataFromHandlers<THandlers>\n> {\n  type TData = CartDataFromHandlers<THandlers>;\n\n  function TypedCartProvider({ initialData, children }: TypedCartProviderProps<TData>) {\n    return (\n      <CartProvider initialData={initialData as CartInitialData | undefined}>\n        {children}\n      </CartProvider>\n    );\n  }\n\n  function useTypedCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useTypedOptionalCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S | undefined {\n    return useOptionalCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useSuspenseCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    const readyPromise = useCart((state) => state.readyPromise);\n    if (readyPromise) throw readyPromise;\n    return useCart(selector, isEqual);\n  }\n\n  return {\n    CartProvider: TypedCartProvider,\n    useCart: useTypedCart,\n    useSuspenseCart,\n    useOptionalCart: useTypedOptionalCart,\n    useCartActions,\n    useCartForm,\n  } as const;\n}\n\nexport function useCartStore(hookName = \"useCart\"): CartStore {\n  const store = useContext(CartContext);\n  if (!store) throw new Error(`${hookName} must be used inside <CartProvider>.`);\n  return store;\n}\n\nfunction useOptionalCartStore(): CartStore | null {\n  return useContext(CartContext);\n}\n\n/**\n * Creates a cart store and shares the store with the cart hooks inside the provider.\n *\n * Render every cart hook inside the provider. On mount, the provider sends cart requests to `/api/cart` and connects the store. On unmount, the provider destroys the store. The provider creates its store from the first initial data and ignores later changes.\n *\n * @example\n * ```tsx\n * // In your root layout\n * <CartProvider initialData={{ cart: loaderData.cart }}>\n *   <App />\n * </CartProvider>\n * ```\n * @param props - The initial cart data and the content that uses the cart hooks.\n * @returns A context provider that shares the cart store with its children.\n * @publicDocs\n */\nexport function CartProvider({\n  initialData,\n  children,\n}: {\n  initialData?: CartInitialData;\n  children?: ReactNode;\n}) {\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is created once with the initial server data\n  const store = useMemo(() => createCartStore({ initialData }), []);\n\n  useEffect(() => {\n    configureCoreCartEndpoint(cartEndpoint);\n    store.connect();\n    return () => {\n      store.destroy();\n    };\n  }, [store]);\n\n  return <CartContext.Provider value={store}>{children}</CartContext.Provider>;\n}\n\n/**\n * Returns the slice of cart state that the selector picks.\n *\n * The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value.\n *\n * @example\n * ```tsx\n * // Select cart lines\n * const lines = useCart((state) => state.data.lines.nodes);\n *\n * // Select pending state for a specific line\n * const isPending = useCart((state) => state.pending.lines.has(lineId));\n *\n * // Custom equality to avoid re-renders on unchanged totals\n * const total = useCart(\n *   (state) => state.data.cost.totalAmount,\n *   (a, b) => a.amount === b.amount,\n * );\n * ```\n * @publicDocs\n */\nexport function useCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const store = useCartStore();\n  return useCartSelector(store, selector, isEqual) as S;\n}\n\n/**\n * Returns the cart action that reloads the cart after a cart change outside cart forms.\n *\n * Call `refresh()` after a server-side cart change that skips cart forms, such as a server action that creates the cart.\n *\n * @returns The `refresh()` action.\n *\n * @example\n * ```tsx\n * const { refresh } = useCartActions();\n *\n * async function handleServerAction() {\n *   await createCartOnServer();\n *   refresh(); // re-fetch the cart\n * }\n * ```\n * @publicDocs\n */\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\n/**\n * Publishes cart analytics events when the customer's cart changes.\n *\n * Call the hook once near the root of your app, inside `CartProvider`. The hook starts tracking on mount and stops on unmount. The hook publishes `cart_updated`, `product_added_to_cart`, and `product_removed_from_cart` events.\n *\n * The hook throws outside `CartProvider`, and when the Shopify analytics bus isn't available. Render `ShopifyScripts` before the hook runs.\n *\n * @returns Nothing. The hook tracks cart analytics for the lifetime of the calling component.\n *\n * @example\n * ```tsx\n * function App() {\n *   useCartAnalytics();\n *   return <Layout />;\n * }\n * ```\n * @publicDocs\n */\nexport function useCartAnalytics(): void {\n  const store = useCartStore(\"useCartAnalytics\");\n\n  useEffect(() => trackCartAnalytics(store), [store]);\n}\n\n/**\n * Returns a selected slice of cart state, or `undefined` when the component renders outside the cart provider.\n *\n * Use the hook in a component that also renders above the provider, such as a header cart badge on an error page.\n * Wherever the provider always exists, use `useCart`, which throws when the provider is missing.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value, or `undefined` outside the provider.\n *\n * @example\n * ```tsx\n * function CartBadge() {\n *   const count = useOptionalCart((state) => state.data.totalQuantity);\n *   if (count === undefined) return null;\n *   return <span>Cart ({count})</span>;\n * }\n * ```\n * @publicDocs\n */\nexport function useOptionalCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S | undefined {\n  const store = useOptionalCartStore();\n  if (!store) return undefined;\n  return useCartSelector(store, selector, isEqual);\n}\n\nfunction useCartSelector<TData extends CartData = CartData, S = unknown>(\n  store: CartStore,\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const cachedRef = useRef<{ state: unknown; selector: typeof selector; value: S } | null>(null);\n\n  const getSnapshot = () => {\n    const state = store.getState() as CartState<TData>;\n\n    if (\n      cachedRef.current &&\n      cachedRef.current.state === state &&\n      cachedRef.current.selector === selector\n    ) {\n      return cachedRef.current.value;\n    }\n\n    const next = selector(state);\n\n    if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {\n      cachedRef.current = { state, selector, value: cachedRef.current.value };\n      return cachedRef.current.value;\n    }\n\n    cachedRef.current = { state, selector, value: next };\n    return next;\n  };\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Returns form props and a field register function for building cart forms.\n *\n * Spread `formProps()` on the form. The form posts to the cart endpoint. On submit, the form props stop the browser's navigation and send the form through the cart store.\n * The submit handler ignores a failed cart change. Read failures from the cart state's `errors`.\n * To skip the cart submission, call `event.preventDefault()` in a `beforeSubmit` callback. The `afterSubmit` callback runs as soon as the cart change starts, before the server responds.\n * The register function returns the HTML attributes for each cart field and action.\n *\n * Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled.\n *\n * @returns The form props function and the register function.\n *\n * @example\n * ```tsx\n * function LineItem({ line }) {\n *   const { formProps, register } = useCartForm();\n *\n *   return (\n *     <form {...formProps()}>\n *       <input {...register(\"lineId\", { value: line.id })} />\n *       <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *       <button {...register(\"set\")} />\n *       <button {...register(\"increase\")}>+</button>\n *       <button {...register(\"decrease\")}>−</button>\n *       <button {...register(\"remove\")}>Remove</button>\n *     </form>\n *   );\n * }\n * ```\n * @publicDocs\n */\nexport function useCartForm(): CartFormBindings {\n  const store = useCartStore(\"useCartForm\");\n  const coreRegister = useMemo(() => createCartFormRegister(), []);\n\n  const register = useMemo(() => {\n    type Register = typeof coreRegister;\n    const wrapped = ((...args: Parameters<Register>) => {\n      const result = (coreRegister as Function)(...args);\n      const [field, opts] = args as [string, { interactive?: boolean }?];\n\n      if (field === \"quantity\" && opts?.interactive) {\n        let cleanup: (() => void) | null = null;\n        const ref: RefCallback<HTMLInputElement> = (el) => {\n          cleanup?.();\n          cleanup = null;\n          if (el) {\n            const form = el.closest(\"form\");\n            if (form) cleanup = attachQuantityInput(el, form);\n          }\n        };\n        const { value: _, ...rest } = result;\n        return { ...rest, defaultValue: result.value, ref };\n      }\n\n      return result;\n    }) as Register;\n    return wrapped;\n  }, [coreRegister]);\n\n  const formProps = (opts?: CartFormPropsOptions): FormHTMLAttributes<HTMLFormElement> => ({\n    onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n      opts?.beforeSubmit?.(e);\n      if (e.defaultPrevented) return;\n      e.preventDefault();\n      store.handleFormSubmit(e.nativeEvent).catch(() => {});\n      opts?.afterSubmit?.(e);\n    },\n    method: \"post\",\n    action: cartEndpoint,\n  });\n\n  return { formProps, register };\n}\n"],"mappings":"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"}
+{"version":3,"file":"cart.mjs","names":[],"sources":["../../../src/react/cart.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type RefCallback,\n  type SubmitEvent,\n} from \"react\";\n\nimport { trackCartAnalytics } from \"../core/analytics/cart-tracker\";\nimport { attachQuantityInput } from \"../core/cart/attach-quantity-input\";\nimport {\n  configureCartEndpoint as configureCoreCartEndpoint,\n  createCartStore,\n  type CreateCartStoreOptions,\n  type CartActions,\n  type CartStore,\n} from \"../core/cart/cart\";\nimport { createCartFormRegister, type CartFormRegister } from \"../core/cart/form\";\nimport type { CartDataFromHandlers } from \"../core/cart/server-handlers\";\nimport { type CartData, type CartState } from \"../core/cart/state\";\n\nconst DEFAULT_CART_ENDPOINT = \"/api/cart\";\n\nlet cartEndpoint = DEFAULT_CART_ENDPOINT;\n\ninterface CartContextValue {\n  store: CartStore;\n  hydrationSnapshot: CartState;\n}\n\nconst CartContext = createContext<CartContextValue | null>(null);\n\nexport function configureCartEndpoint(endpoint: string): void {\n  cartEndpoint = endpoint;\n  configureCoreCartEndpoint(endpoint);\n}\n\nexport function getCartEndpoint(): string {\n  return cartEndpoint;\n}\n\n/**\n * Props for the cart provider that `createCartComponents` returns.\n */\ntype TypedCartProviderProps<TData extends CartData> = {\n  /**\n   * The `data` property of the cart GET handler's result, or a promise of that data. Without initial data, the store loads the cart from `/api/cart` after the provider mounts, and the server-rendered page shows an empty cart. The provider creates its store from the first value and ignores later changes.\n   */\n  initialData?: CartInitialData<TData>;\n  /** Content that can read the cart through the cart hooks. */\n  children?: ReactNode;\n};\n\ntype CartInitialData<TData extends CartData = CartData> =\n  CreateCartStoreOptions<TData>[\"initialData\"];\n\nexport type { CartActions };\n\n/** A hook that returns the slice of cart state that your selector picks. */\ntype CartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;\n\n/** A hook that returns the slice of cart state that your selector picks, or `undefined` outside the cart provider. */\ntype OptionalCartStateHook<TData extends CartData> =\n  /**\n   * @param selector - Picks the value to return from the cart state.\n   * @param isEqual - Compares the previous and next selected values. Return `true` to skip the re-render. Without the function, the hook compares the values by reference.\n   * @returns The selected value, or `undefined` outside the cart provider.\n   */\n  <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S | undefined;\n\n/** Callbacks that run around a cart form submission. */\ninterface CartFormPropsOptions {\n  /** Runs before the cart store handles the submission. Call `event.preventDefault()` to skip the cart submission. */\n  beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  /** Runs as soon as the cart change starts, before the server responds. */\n  afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n}\n\n/** The form props function and the register function for a cart form. */\ninterface CartFormBindings {\n  /** Returns the `method`, `action`, and `onSubmit` props to spread on the form. The form posts to the cart endpoint, and the cart store handles each submission. */\n  formProps: (opts?: CartFormPropsOptions) => FormHTMLAttributes<HTMLFormElement>;\n  /** Returns the attributes for a cart field or action button. Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled. */\n  register: CartFormRegister;\n}\n\n/**\n * The cart provider and hooks that `createCartComponents` returns, typed with the custom cart fields from your cart server handlers.\n */\ntype TypedCartComponents<TData extends CartData> = {\n  /** Creates the cart store and shares the store with the cart hooks inside the provider. The provider connects the store on mount and destroys the store on unmount. */\n  CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;\n  /**\n   * Returns the slice of cart state that the selector picks. The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n   */\n  useCart: CartStateHook<TData>;\n  /** Suspends while the full cart loads, then returns the slice of cart state that the selector picks. Wrap the component in a `Suspense` boundary. */\n  useSuspenseCart: CartStateHook<TData>;\n  /**\n   * Returns the slice of cart state that the selector picks, or `undefined` outside the provider. Use the hook in a component that also renders above the provider, such as a cart badge on an error page.\n   */\n  useOptionalCart: OptionalCartStateHook<TData>;\n  /** Returns the `refresh()` action. Call `refresh()` after a server-side cart change that skips cart forms. */\n  useCartActions: typeof useCartActions;\n  /** Returns form props and a register function for cart forms. */\n  useCartForm: typeof useCartForm;\n};\n\n/**\n * Returns a cart provider and cart hooks typed to the cart fragment in your cart server handlers.\n * Pass `typeof cartServerHandlers` as the `THandlers` type argument. Every hook's cart state then includes your custom cart fields.\n *\n * On mount, the provider sends cart requests to `/api/cart` and connects the store. Every hook except `useOptionalCart` throws when you call it outside the provider.\n *\n * @returns The cart provider, the cart state hooks, and the cart actions and form hooks.\n *\n * @example\n * ```tsx\n * import type { cartServerHandlers } from \"./server/cart.server\";\n *\n * const {\n *   CartProvider,\n *   useCart,\n *   useSuspenseCart,\n *   useOptionalCart,\n *   useCartActions,\n *   useCartForm,\n * } = createCartComponents<typeof cartServerHandlers>();\n * ```\n * @publicDocs\n */\nexport function createCartComponents<THandlers>(): TypedCartComponents<\n  CartDataFromHandlers<THandlers>\n> {\n  type TData = CartDataFromHandlers<THandlers>;\n\n  function TypedCartProvider({ initialData, children }: TypedCartProviderProps<TData>) {\n    return (\n      <CartProvider initialData={initialData as CartInitialData | undefined}>\n        {children}\n      </CartProvider>\n    );\n  }\n\n  function useTypedCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useTypedOptionalCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S | undefined {\n    return useOptionalCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useSuspenseCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useSuspenseCartSelector(selector, isEqual);\n  }\n\n  return {\n    CartProvider: TypedCartProvider,\n    useCart: useTypedCart,\n    useSuspenseCart,\n    useOptionalCart: useTypedOptionalCart,\n    useCartActions,\n    useCartForm,\n  } as const;\n}\n\nexport function useCartStore(hookName = \"useCart\"): CartStore {\n  return useCartContext(hookName).store;\n}\n\nfunction useCartContext(hookName = \"useCart\"): CartContextValue {\n  const context = useContext(CartContext);\n  if (!context) throw new Error(`${hookName} must be used inside <CartProvider>.`);\n  return context;\n}\n\nfunction useOptionalCartContext(): CartContextValue | null {\n  return useContext(CartContext);\n}\n\n/**\n * Creates a cart store and shares the store with the cart hooks inside the provider.\n *\n * Render every cart hook inside the provider. On mount, the provider sends cart requests to `/api/cart` and connects the store. On unmount, the provider destroys the store. The provider creates its store from the first initial data and ignores later changes.\n *\n * @example\n * ```tsx\n * // In your root layout\n * <CartProvider initialData={{ cart: loaderData.cart }}>\n *   <App />\n * </CartProvider>\n * ```\n * @param props - The initial cart data and the content that uses the cart hooks.\n * @returns A context provider that shares the cart store with its children.\n * @publicDocs\n */\nexport function CartProvider({\n  initialData,\n  children,\n}: {\n  initialData?: CartInitialData;\n  children?: ReactNode;\n}) {\n  const context = useMemo(() => {\n    const store = createCartStore({ initialData });\n    // Plain consumers must hydrate from the state used for SSR, even if the live store settles first.\n    return { store, hydrationSnapshot: store.getState() };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- provider initialData seeds one store for its lifetime\n  }, []);\n  const { store } = context;\n\n  useEffect(() => {\n    configureCoreCartEndpoint(cartEndpoint);\n    store.connect();\n    return () => {\n      store.destroy();\n    };\n  }, [store]);\n\n  return <CartContext.Provider value={context}>{children}</CartContext.Provider>;\n}\n\n/**\n * Returns the slice of cart state that the selector picks.\n *\n * The component re-renders when the selected value changes by reference, or when your `isEqual` function reports a change. A selector that returns the full state re-renders on every cart update.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value.\n *\n * @example\n * ```tsx\n * // Select cart lines\n * const lines = useCart((state) => state.data.lines.nodes);\n *\n * // Select pending state for a specific line\n * const isPending = useCart((state) => state.pending.lines.has(lineId));\n *\n * // Custom equality to avoid re-renders on unchanged totals\n * const total = useCart(\n *   (state) => state.data.cost.totalAmount,\n *   (a, b) => a.amount === b.amount,\n * );\n * ```\n * @publicDocs\n */\nexport function useCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const { store, hydrationSnapshot } = useCartContext();\n  return useCartSelector(store, hydrationSnapshot, selector, isEqual) as S;\n}\n\n/**\n * Returns the cart action that reloads the cart after a cart change outside cart forms.\n *\n * Call `refresh()` after a server-side cart change that skips cart forms, such as a server action that creates the cart.\n *\n * @returns The `refresh()` action.\n *\n * @example\n * ```tsx\n * const { refresh } = useCartActions();\n *\n * async function handleServerAction() {\n *   await createCartOnServer();\n *   refresh(); // re-fetch the cart\n * }\n * ```\n * @publicDocs\n */\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\n/**\n * Publishes cart analytics events when the customer's cart changes.\n *\n * Call the hook once near the root of your app, inside `CartProvider`. The hook starts tracking on mount and stops on unmount. The hook publishes `cart_updated`, `product_added_to_cart`, and `product_removed_from_cart` events.\n *\n * The hook throws outside `CartProvider`, and when the Shopify analytics bus isn't available. Render `ShopifyScripts` before the hook runs.\n *\n * @returns Nothing. The hook tracks cart analytics for the lifetime of the calling component.\n *\n * @example\n * ```tsx\n * function App() {\n *   useCartAnalytics();\n *   return <Layout />;\n * }\n * ```\n * @publicDocs\n */\nexport function useCartAnalytics(): void {\n  const store = useCartStore(\"useCartAnalytics\");\n\n  useEffect(() => trackCartAnalytics(store), [store]);\n}\n\n/**\n * Returns a selected slice of cart state, or `undefined` when the component renders outside the cart provider.\n *\n * Use the hook in a component that also renders above the provider, such as a header cart badge on an error page.\n * Wherever the provider always exists, use `useCart`, which throws when the provider is missing.\n *\n * @param selector The function that picks a value from the cart state.\n * @param isEqual The function that compares the previous and next selected values. Return `true` to skip the re-render.\n * @returns The selected value, or `undefined` outside the provider.\n *\n * @example\n * ```tsx\n * function CartBadge() {\n *   const count = useOptionalCart((state) => state.data.totalQuantity);\n *   if (count === undefined) return null;\n *   return <span>Cart ({count})</span>;\n * }\n * ```\n * @publicDocs\n */\nexport function useOptionalCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S | undefined {\n  const context = useOptionalCartContext();\n  if (!context) return undefined;\n  return useCartSelector(context.store, context.hydrationSnapshot, selector, isEqual);\n}\n\nfunction useCartSelector<TData extends CartData = CartData, S = unknown>(\n  store: CartStore,\n  hydrationSnapshot: CartState,\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const liveCacheRef = useRef<SelectorCache<S> | null>(null);\n  const hydrationCacheRef = useRef<SelectorCache<S> | null>(null);\n\n  const getSnapshot = () =>\n    selectCartSnapshot(store.getState() as CartState<TData>, selector, isEqual, liveCacheRef);\n  const getServerSnapshot = () =>\n    selectCartSnapshot(hydrationSnapshot as CartState<TData>, selector, isEqual, hydrationCacheRef);\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);\n}\n\ninterface SelectorCache<S> {\n  state: unknown;\n  selector: unknown;\n  value: S;\n}\n\nfunction selectCartSnapshot<TData extends CartData, S>(\n  state: CartState<TData>,\n  selector: (state: CartState<TData>) => S,\n  isEqual: ((a: S, b: S) => boolean) | undefined,\n  cacheRef: { current: SelectorCache<S> | null },\n): S {\n  if (cacheRef.current?.state === state && cacheRef.current.selector === selector) {\n    return cacheRef.current.value;\n  }\n\n  const next = selector(state);\n\n  if (cacheRef.current && isEqual?.(cacheRef.current.value, next)) {\n    cacheRef.current = { state, selector, value: cacheRef.current.value };\n    return cacheRef.current.value;\n  }\n\n  cacheRef.current = { state, selector, value: next };\n  return next;\n}\n\ntype SuspenseSnapshot<S> =\n  | { status: \"pending\"; promise: PromiseLike<void> }\n  | { status: \"ready\"; value: S };\n\ninterface SuspenseSelectorCache<S> {\n  state: unknown;\n  selector: unknown;\n  snapshot: SuspenseSnapshot<S>;\n}\n\nfunction useSuspenseCartSelector<TData extends CartData, S>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const { store } = useCartContext();\n  const cacheRef = useRef<SuspenseSelectorCache<S> | null>(null);\n\n  // Suspense retries must read live readiness and data; the hydration snapshot would freeze the fallback.\n  const getSnapshot = () => {\n    const state = store.getState() as CartState<TData>;\n\n    if (cacheRef.current?.state === state && cacheRef.current.selector === selector) {\n      return cacheRef.current.snapshot;\n    }\n\n    if (state.readyPromise) {\n      const snapshot: SuspenseSnapshot<S> = { status: \"pending\", promise: state.readyPromise };\n      cacheRef.current = { state, selector, snapshot };\n      return snapshot;\n    }\n\n    const value = selector(state);\n    const previous = cacheRef.current?.snapshot;\n\n    if (previous?.status === \"ready\" && isEqual?.(previous.value, value)) {\n      cacheRef.current = { state, selector, snapshot: previous };\n      return previous;\n    }\n\n    const snapshot: SuspenseSnapshot<S> = { status: \"ready\", value };\n    cacheRef.current = { state, selector, snapshot };\n    return snapshot;\n  };\n\n  const snapshot = useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n  if (snapshot.status === \"pending\") throw snapshot.promise;\n  return snapshot.value;\n}\n\n/**\n * Returns form props and a field register function for building cart forms.\n *\n * Spread `formProps()` on the form. The form posts to the cart endpoint. On submit, the form props stop the browser's navigation and send the form through the cart store.\n * The submit handler ignores a failed cart change. Read failures from the cart state's `errors`.\n * To skip the cart submission, call `event.preventDefault()` in a `beforeSubmit` callback. The `afterSubmit` callback runs as soon as the cart change starts, before the server responds.\n * The register function returns the HTML attributes for each cart field and action.\n *\n * Register the quantity field with `interactive: true` to submit the form when the quantity changes. The interactive input takes the quantity as a default value and stays uncontrolled.\n *\n * @returns The form props function and the register function.\n *\n * @example\n * ```tsx\n * function LineItem({ line }) {\n *   const { formProps, register } = useCartForm();\n *\n *   return (\n *     <form {...formProps()}>\n *       <input {...register(\"lineId\", { value: line.id })} />\n *       <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *       <button {...register(\"set\")} />\n *       <button {...register(\"increase\")}>+</button>\n *       <button {...register(\"decrease\")}>−</button>\n *       <button {...register(\"remove\")}>Remove</button>\n *     </form>\n *   );\n * }\n * ```\n * @publicDocs\n */\nexport function useCartForm(): CartFormBindings {\n  const store = useCartStore(\"useCartForm\");\n  const coreRegister = useMemo(() => createCartFormRegister(), []);\n\n  const register = useMemo(() => {\n    type Register = typeof coreRegister;\n    const wrapped = ((...args: Parameters<Register>) => {\n      const result = (coreRegister as Function)(...args);\n      const [field, opts] = args as [string, { interactive?: boolean }?];\n\n      if (field === \"quantity\" && opts?.interactive) {\n        let cleanup: (() => void) | null = null;\n        const ref: RefCallback<HTMLInputElement> = (el) => {\n          cleanup?.();\n          cleanup = null;\n          if (el) {\n            const form = el.closest(\"form\");\n            if (form) cleanup = attachQuantityInput(el, form);\n          }\n        };\n        const { value: _, ...rest } = result;\n        return { ...rest, defaultValue: result.value, ref };\n      }\n\n      return result;\n    }) as Register;\n    return wrapped;\n  }, [coreRegister]);\n\n  const formProps = (opts?: CartFormPropsOptions): FormHTMLAttributes<HTMLFormElement> => ({\n    onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n      opts?.beforeSubmit?.(e);\n      if (e.defaultPrevented) return;\n      e.preventDefault();\n      store.handleFormSubmit(e.nativeEvent).catch(() => {});\n      opts?.afterSubmit?.(e);\n    },\n    method: \"post\",\n    action: cartEndpoint,\n  });\n\n  return { formProps, register };\n}\n"],"mappings":";;;;;;;;;;AA8BA,IAAI,eAAe;AAOnB,MAAM,cAAc,cAAuC,KAAK;AAOhE,SAAgB,kBAA0B;AACxC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;AAmGT,SAAgB,uBAEd;CAGA,SAAS,kBAAkB,EAAE,aAAa,YAA2C;AACnF,SACE,oBAAC,cAAD;GAA2B;GACxB;GACY;;CAInB,SAAS,aACP,UACA,SACG;AACH,SAAO,SAAsB,UAAU,SAAS,MAA0B,EAAE,QAAQ;;CAGtF,SAAS,qBACP,UACA,SACe;AACf,SAAO,iBAA8B,UAAU,SAAS,MAA0B,EAAE,QAAQ;;CAG9F,SAAS,gBACP,UACA,SACG;AACH,SAAO,wBAAwB,UAAU,QAAQ;;AAGnD,QAAO;EACL,cAAc;EACd,SAAS;EACT;EACA,iBAAiB;EACjB;EACA;EACD;;AAGH,SAAgB,aAAa,WAAW,WAAsB;AAC5D,QAAO,eAAe,SAAS,CAAC;;AAGlC,SAAS,eAAe,WAAW,WAA6B;CAC9D,MAAM,UAAU,WAAW,YAAY;AACvC,KAAI,CAAC,QAAS,OAAM,IAAI,MAAM,GAAG,SAAS,sCAAsC;AAChF,QAAO;;AAGT,SAAS,yBAAkD;AACzD,QAAO,WAAW,YAAY;;;;;;;;;;;;;;;;;;AAmBhC,SAAgB,aAAa,EAC3B,aACA,YAIC;CACD,MAAM,UAAU,cAAc;EAC5B,MAAM,QAAQ,gBAAgB,EAAE,aAAa,CAAC;AAE9C,SAAO;GAAE;GAAO,mBAAmB,MAAM,UAAU;GAAE;IAEpD,EAAE,CAAC;CACN,MAAM,EAAE,UAAU;AAElB,iBAAgB;AACd,wBAA0B,aAAa;AACvC,QAAM,SAAS;AACf,eAAa;AACX,SAAM,SAAS;;IAEhB,CAAC,MAAM,CAAC;AAEX,QAAO,oBAAC,YAAY,UAAb;EAAsB,OAAO;EAAU;EAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BhF,SAAgB,QACd,UACA,SACG;CACH,MAAM,EAAE,OAAO,sBAAsB,gBAAgB;AACrD,QAAO,gBAAgB,OAAO,mBAAmB,UAAU,QAAQ;;;;;;;;;;;;;;;;;;;;AAqBrE,SAAgB,iBAA8B;CAC5C,MAAM,QAAQ,aAAa,iBAAiB;AAE5C,QAAO,eAAe,EAAE,SAAS,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;AAqB7D,SAAgB,mBAAyB;CACvC,MAAM,QAAQ,aAAa,mBAAmB;AAE9C,iBAAgB,mBAAmB,MAAM,EAAE,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;AAuBrD,SAAgB,gBACd,UACA,SACe;CACf,MAAM,UAAU,wBAAwB;AACxC,KAAI,CAAC,QAAS,QAAO;AACrB,QAAO,gBAAgB,QAAQ,OAAO,QAAQ,mBAAmB,UAAU,QAAQ;;AAGrF,SAAS,gBACP,OACA,mBACA,UACA,SACG;CACH,MAAM,eAAe,OAAgC,KAAK;CAC1D,MAAM,oBAAoB,OAAgC,KAAK;CAE/D,MAAM,oBACJ,mBAAmB,MAAM,UAAU,EAAsB,UAAU,SAAS,aAAa;CAC3F,MAAM,0BACJ,mBAAmB,mBAAuC,UAAU,SAAS,kBAAkB;AAEjG,QAAO,qBAAqB,MAAM,WAAW,aAAa,kBAAkB;;AAS9E,SAAS,mBACP,OACA,UACA,SACA,UACG;AACH,KAAI,SAAS,SAAS,UAAU,SAAS,SAAS,QAAQ,aAAa,SACrE,QAAO,SAAS,QAAQ;CAG1B,MAAM,OAAO,SAAS,MAAM;AAE5B,KAAI,SAAS,WAAW,UAAU,SAAS,QAAQ,OAAO,KAAK,EAAE;AAC/D,WAAS,UAAU;GAAE;GAAO;GAAU,OAAO,SAAS,QAAQ;GAAO;AACrE,SAAO,SAAS,QAAQ;;AAG1B,UAAS,UAAU;EAAE;EAAO;EAAU,OAAO;EAAM;AACnD,QAAO;;AAaT,SAAS,wBACP,UACA,SACG;CACH,MAAM,EAAE,UAAU,gBAAgB;CAClC,MAAM,WAAW,OAAwC,KAAK;CAG9D,MAAM,oBAAoB;EACxB,MAAM,QAAQ,MAAM,UAAU;AAE9B,MAAI,SAAS,SAAS,UAAU,SAAS,SAAS,QAAQ,aAAa,SACrE,QAAO,SAAS,QAAQ;AAG1B,MAAI,MAAM,cAAc;GACtB,MAAM,WAAgC;IAAE,QAAQ;IAAW,SAAS,MAAM;IAAc;AACxF,YAAS,UAAU;IAAE;IAAO;IAAU;IAAU;AAChD,UAAO;;EAGT,MAAM,QAAQ,SAAS,MAAM;EAC7B,MAAM,WAAW,SAAS,SAAS;AAEnC,MAAI,UAAU,WAAW,WAAW,UAAU,SAAS,OAAO,MAAM,EAAE;AACpE,YAAS,UAAU;IAAE;IAAO;IAAU,UAAU;IAAU;AAC1D,UAAO;;EAGT,MAAM,WAAgC;GAAE,QAAQ;GAAS;GAAO;AAChE,WAAS,UAAU;GAAE;GAAO;GAAU;GAAU;AAChD,SAAO;;CAGT,MAAM,WAAW,qBAAqB,MAAM,WAAW,aAAa,YAAY;AAChF,KAAI,SAAS,WAAW,UAAW,OAAM,SAAS;AAClD,QAAO,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkClB,SAAgB,cAAgC;CAC9C,MAAM,QAAQ,aAAa,cAAc;CACzC,MAAM,eAAe,cAAc,wBAAwB,EAAE,EAAE,CAAC;CAEhE,MAAM,WAAW,cAAc;EAE7B,MAAM,YAAY,GAAG,SAA+B;GAClD,MAAM,SAAU,aAA0B,GAAG,KAAK;GAClD,MAAM,CAAC,OAAO,QAAQ;AAEtB,OAAI,UAAU,cAAc,MAAM,aAAa;IAC7C,IAAI,UAA+B;IACnC,MAAM,OAAsC,OAAO;AACjD,gBAAW;AACX,eAAU;AACV,SAAI,IAAI;MACN,MAAM,OAAO,GAAG,QAAQ,OAAO;AAC/B,UAAI,KAAM,WAAU,oBAAoB,IAAI,KAAK;;;IAGrD,MAAM,EAAE,OAAO,GAAG,GAAG,SAAS;AAC9B,WAAO;KAAE,GAAG;KAAM,cAAc,OAAO;KAAO;KAAK;;AAGrD,UAAO;;AAET,SAAO;IACN,CAAC,aAAa,CAAC;CAElB,MAAM,aAAa,UAAsE;EACvF,WAAW,MAAoC;AAC7C,SAAM,eAAe,EAAE;AACvB,OAAI,EAAE,iBAAkB;AACxB,KAAE,gBAAgB;AAClB,SAAM,iBAAiB,EAAE,YAAY,CAAC,YAAY,GAAG;AACrD,SAAM,cAAc,EAAE;;EAExB,QAAQ;EACR,QAAQ;EACT;AAED,QAAO;EAAE;EAAW;EAAU"}