@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

package/dist/development/core/product/product-form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"product-form.mjs","names":[],"sources":["../../../../src/core/product/product-form.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type {\n  CartLine,\n  CartNetworkEntry,\n  CartState,\n  CartUserError,\n  CartWarning,\n} from \"../cart/state\";\nimport { createObservable } from \"../observable\";\nimport {\n  buildProductOptions,\n  type DecodedVariantCache,\n  selectedOptionsFromMap,\n  selectedOptionsToMap,\n} from \"./options\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductOptionValueInput,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n} from \"./state\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\nexport interface ProductFormErrors {\n  userErrors: CartUserError[];\n  warnings: CartWarning[];\n  networkErrors: CartNetworkEntry[];\n}\n\n/** Live state snapshot emitted by a {@link ProductFormStore}. */\nexport interface ProductFormStoreState<\n  TVariant extends ProductVariantInput = ProductVariantInput,\n  TOptionValue extends ProductOptionValueInput = ProductOptionValueInput,\n> {\n  options: VariantOptionState<TVariant, TOptionValue>[];\n  selectedOptions: SelectedOption[];\n  selectedVariant: TVariant | null;\n  errors: ProductFormErrors;\n  matchedLineItem: CartLine | null;\n}\n\nexport type ProductFormOptions<TProduct extends ProductInput = ProductInput> =\n  ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[\"options\"];\n\n/**\n * Result returned by {@link ProductFormStore.selectOption}.\n *\n * - `resolved` — a specific variant was matched for the full selection.\n * - `unresolved` — the selection is valid but not yet complete.\n * - `invalid` — the option name or value does not exist on the product.\n */\nexport type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVariantInput> =\n  | {\n      status: \"resolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: TVariant;\n    }\n  | {\n      status: \"unresolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n    }\n  | {\n      status: \"invalid\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n      reason: string;\n    };\n\n/** A selection result that is not invalid — either resolved or unresolved. */\nexport type ValidProductSelectionResult<TProduct extends ProductInput = ProductInput> = Exclude<\n  VariantSelectionResult<ProductVariantFrom<TProduct>>,\n  { status: \"invalid\" }\n>;\n\nexport type CreateProductFormStoreOptions = {\n  selectedOptions?: SelectedOption[];\n};\n\n/** Manages variant selection + cart integration for a product form. */\nexport interface ProductFormStore<\n  TProduct extends ProductInput = ProductInput,\n  TVariant extends ProductVariantInput = ProductVariantFrom<TProduct>,\n> {\n  getState(): ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>;\n  subscribe(\n    listener: (state: ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>) => void,\n  ): () => void;\n  selectOption(name: string, value: string): VariantSelectionResult<TVariant>;\n  hydrate(product: TProduct, opts?: { selectedOptions?: SelectedOption[] }): void;\n  reset(): void;\n  destroy(): void;\n  handleFormSubmit(event: SubmitEvent): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Utilities\n// ---------------------------------------------------------------------------\n\nexport function getSelectedVariant<TVariant extends ProductVariantInput>(\n  options: VariantOptionState<TVariant, ProductOptionValueInput>[],\n): TVariant | null {\n  return options[0]?.values.find((v) => v.selected)?.variant ?? null;\n}\n\nexport function canAddToCart<TProduct extends ProductInput>(\n  product: TProduct,\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[],\n): boolean {\n  if (product.requiresSellingPlan) return false;\n  const variant = getSelectedVariant(options);\n  return variant !== null && variant.availableForSale;\n}\n\n/**\n * Finds the first cart line whose merchandise ID matches.\n * When selling plans are used, the same merchandise ID can appear on multiple\n * cart lines — this returns the first match. Future attribute-based matching\n * will narrow to the exact line.\n */\nexport function findCartLineByMerchandiseId(\n  lines: CartLine[],\n  merchandiseId: string,\n): CartLine | null {\n  return lines.find((l) => l.merchandise?.id === merchandiseId) ?? null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal context\n// ---------------------------------------------------------------------------\n\ntype ProductFormStoreContext<TProduct extends ProductInput> = {\n  observable: ReturnType<\n    typeof createObservable<\n      ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>\n    >\n  >;\n  cartStore: CartStore;\n  currentProduct: TProduct;\n  initialProduct: TProduct;\n  initialSelectedOptions: SelectedOption[];\n  decodedVariantCache: DecodedVariantCache;\n  destroyed: boolean;\n  unsubCart: () => void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\nexport function createProductFormStore<TProduct extends ProductInput>(\n  product: TProduct,\n  cartStore: CartStore,\n  options: CreateProductFormStoreOptions = {},\n): ProductFormStore<TProduct, ProductVariantFrom<TProduct>> {\n  const decodedVariantCache: DecodedVariantCache = new Map();\n  const initialSelectedOptions = resolveSelectedOptions(product, options.selectedOptions);\n\n  const variantState = buildVariantState(product, initialSelectedOptions, decodedVariantCache);\n\n  const context: ProductFormStoreContext<TProduct> = {\n    observable: createObservable(deriveFullState(variantState, cartStore.getState())),\n    cartStore,\n    currentProduct: product,\n    initialProduct: product,\n    initialSelectedOptions,\n    decodedVariantCache,\n    destroyed: false,\n    unsubCart: () => {},\n  };\n\n  context.unsubCart = cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    selectOption: (name, value) => selectOption(context, name, value),\n    hydrate: (nextProduct, opts) => hydrate(context, nextProduct, opts),\n    reset: () => reset(context),\n    destroy: () => destroy(context),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// State builders\n// ---------------------------------------------------------------------------\n\ntype VariantOnlyState<TProduct extends ProductInput> = {\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[];\n  selectedOptions: SelectedOption[];\n};\n\nfunction buildVariantState<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache: DecodedVariantCache,\n): VariantOnlyState<TProduct> {\n  return {\n    options: buildProductOptions(product, selectedOptions, cache),\n    selectedOptions,\n  };\n}\n\nfunction deriveFullState<TProduct extends ProductInput>(\n  variant: VariantOnlyState<TProduct>,\n  cartState: CartState,\n): ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const selectedVariant = getSelectedVariant(variant.options);\n  const matchedLineItem = selectedVariant\n    ? findCartLineByMerchandiseId(cartState.data.lines.nodes, selectedVariant.id)\n    : null;\n\n  const lineErrors = matchedLineItem ? cartState.errors.lines.get(matchedLineItem.id) : undefined;\n\n  return {\n    options: variant.options,\n    selectedOptions: variant.selectedOptions,\n    selectedVariant,\n    errors: {\n      userErrors: [...cartState.errors.cart.userErrors, ...(lineErrors?.userErrors ?? [])],\n      warnings: [...cartState.errors.cart.warnings, ...(lineErrors?.warnings ?? [])],\n      networkErrors: cartState.errors.network,\n    },\n    matchedLineItem,\n  };\n}\n\nfunction resolveSelectedOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  requested?: SelectedOption[],\n): SelectedOption[] {\n  return product.selectedOrFirstAvailableVariant?.selectedOptions ?? requested ?? [];\n}\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\nfunction selectOption<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  name: string,\n  value: string,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const { options, selectedOptions } = context.observable.state;\n  const option = options.find((o) => o.name === name);\n  const optionValue = option?.values.find((v) => v.name === value);\n\n  if (!option || !optionValue) {\n    return invalid(selectedOptions, `Unknown option \"${name}\" value \"${value}\".`);\n  }\n\n  if (!optionValue.exists) {\n    return invalid(\n      selectedOptions,\n      `Option \"${name}\" value \"${value}\" does not resolve to a product variant.`,\n    );\n  }\n\n  const nextSelectedOptionMap = {\n    ...selectedOptionsToMap(selectedOptions),\n    [name]: value,\n  };\n  const nextSelectedOptions = selectedOptionsFromMap(context.currentProduct, nextSelectedOptionMap);\n\n  return applySelection(\n    context,\n    optionValue.variant\n      ? {\n          status: \"resolved\",\n          selectedOptions: optionValue.variant.selectedOptions,\n          selectedVariant: optionValue.variant as ProductVariantFrom<TProduct>,\n        }\n      : {\n          status: \"unresolved\",\n          selectedOptions: nextSelectedOptions,\n          selectedVariant: null,\n        },\n  );\n}\n\nfunction hydrate<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  product: TProduct,\n  opts: { selectedOptions?: SelectedOption[] } = {},\n): void {\n  context.currentProduct = product;\n  context.decodedVariantCache.clear();\n  const selectedOptions =\n    product.selectedOrFirstAvailableVariant?.selectedOptions ??\n    opts.selectedOptions ??\n    context.observable.state.selectedOptions;\n  const variantState = buildVariantState(product, selectedOptions, context.decodedVariantCache);\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction reset<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.currentProduct = context.initialProduct;\n  context.decodedVariantCache.clear();\n  const variantState = buildVariantState(\n    context.initialProduct,\n    context.initialSelectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction destroy<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.destroyed = true;\n  context.unsubCart();\n  context.decodedVariantCache.clear();\n}\n\nfunction buildAddToCartDetail<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): Record<string, unknown> | undefined {\n  const { selectedVariant } = context.observable.state;\n  if (!selectedVariant) return undefined;\n\n  return {\n    products: [\n      {\n        id: selectedVariant.id,\n        title: selectedVariant.title,\n        product: selectedVariant.product\n          ? { title: selectedVariant.product.title, handle: selectedVariant.product.handle }\n          : undefined,\n        selectedOptions: selectedVariant.selectedOptions,\n        image: selectedVariant.image,\n        price: selectedVariant.price,\n      },\n    ],\n  };\n}\n\nasync function handleFormSubmit<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  event: SubmitEvent,\n): Promise<void> {\n  const eventDetail = buildAddToCartDetail(context);\n  await context.cartStore.handleFormSubmit(event, eventDetail);\n}\n\nfunction applySelection<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  result: Exclude<VariantSelectionResult<ProductVariantFrom<TProduct>>, { status: \"invalid\" }>,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const variantState = buildVariantState(\n    context.currentProduct,\n    result.selectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n  return result;\n}\n\nfunction hasCartDerivedFieldsChanged<TVariant extends ProductVariantInput>(\n  prev: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n  next: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n): boolean {\n  return (\n    prev.matchedLineItem !== next.matchedLineItem ||\n    prev.selectedVariant !== next.selectedVariant ||\n    prev.errors.userErrors !== next.errors.userErrors ||\n    prev.errors.warnings !== next.errors.warnings ||\n    prev.errors.networkErrors !== next.errors.networkErrors\n  );\n}\n\nfunction syncFromCart<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): void {\n  const prev = context.observable.state;\n  const next = deriveFullState(\n    { options: prev.options, selectedOptions: prev.selectedOptions },\n    context.cartStore.getState(),\n  );\n\n  if (hasCartDerivedFieldsChanged(prev, next)) {\n    context.observable.setState(next);\n  }\n}\n\nfunction invalid<TVariant extends ProductVariantInput>(\n  selectedOptions: SelectedOption[],\n  reason: string,\n): VariantSelectionResult<TVariant> {\n  return {\n    status: \"invalid\",\n    selectedOptions,\n    selectedVariant: null,\n    reason,\n  };\n}\n"],"mappings":";;;;AAyGA,SAAgB,mBACd,SACiB;AACjB,QAAO,QAAQ,IAAI,OAAO,MAAM,MAAM,EAAE,SAAS,EAAE,WAAW;;AAGhE,SAAgB,aACd,SACA,SACS;AACT,KAAI,QAAQ,oBAAqB,QAAO;CACxC,MAAM,UAAU,mBAAmB,QAAQ;AAC3C,QAAO,YAAY,QAAQ,QAAQ;;;;;;;;AASrC,SAAgB,4BACd,OACA,eACiB;AACjB,QAAO,MAAM,MAAM,MAAM,EAAE,aAAa,OAAO,cAAc,IAAI;;AA0BnE,SAAgB,uBACd,SACA,WACA,UAAyC,EAAE,EACe;CAC1D,MAAM,sCAA2C,IAAI,KAAK;CAC1D,MAAM,yBAAyB,uBAAuB,SAAS,QAAQ,gBAAgB;CAIvF,MAAM,UAA6C;EACjD,YAAY,iBAAiB,gBAHV,kBAAkB,SAAS,wBAAwB,oBAGb,EAAE,UAAU,UAAU,CAAC,CAAC;EACjF;EACA,gBAAgB;EAChB,gBAAgB;EAChB;EACA;EACA,WAAW;EACX,iBAAiB;EAClB;AAED,SAAQ,YAAY,UAAU,gBAAgB;AAC5C,MAAI,QAAQ,UAAW;AACvB,eAAa,QAAQ;GACrB;AAEF,QAAO;EACL,gBAAgB,QAAQ,WAAW;EACnC,YAAY,aAAa,QAAQ,WAAW,UAAU,SAAS;EAC/D,eAAe,MAAM,UAAU,aAAa,SAAS,MAAM,MAAM;EACjE,UAAU,aAAa,SAAS,QAAQ,SAAS,aAAa,KAAK;EACnE,aAAa,MAAM,QAAQ;EAC3B,eAAe,QAAQ,QAAQ;EAC/B,mBAAmB,UAAU,iBAAiB,SAAS,MAAM;EAC9D;;AAYH,SAAS,kBACP,SACA,iBACA,OAC4B;AAC5B,QAAO;EACL,SAAS,oBAAoB,SAAS,iBAAiB,MAAM;EAC7D;EACD;;AAGH,SAAS,gBACP,SACA,WACuF;CACvF,MAAM,kBAAkB,mBAAmB,QAAQ,QAAQ;CAC3D,MAAM,kBAAkB,kBACpB,4BAA4B,UAAU,KAAK,MAAM,OAAO,gBAAgB,GAAG,GAC3E;CAEJ,MAAM,aAAa,kBAAkB,UAAU,OAAO,MAAM,IAAI,gBAAgB,GAAG,GAAG;AAEtF,QAAO;EACL,SAAS,QAAQ;EACjB,iBAAiB,QAAQ;EACzB;EACA,QAAQ;GACN,YAAY,CAAC,GAAG,UAAU,OAAO,KAAK,YAAY,GAAI,YAAY,cAAc,EAAE,CAAE;GACpF,UAAU,CAAC,GAAG,UAAU,OAAO,KAAK,UAAU,GAAI,YAAY,YAAY,EAAE,CAAE;GAC9E,eAAe,UAAU,OAAO;GACjC;EACD;EACD;;AAGH,SAAS,uBACP,SACA,WACkB;AAClB,QAAO,QAAQ,iCAAiC,mBAAmB,aAAa,EAAE;;AAOpF,SAAS,aACP,SACA,MACA,OACsD;CACtD,MAAM,EAAE,SAAS,oBAAoB,QAAQ,WAAW;CACxD,MAAM,SAAS,QAAQ,MAAM,MAAM,EAAE,SAAS,KAAK;CACnD,MAAM,cAAc,QAAQ,OAAO,MAAM,MAAM,EAAE,SAAS,MAAM;AAEhE,KAAI,CAAC,UAAU,CAAC,YACd,QAAO,QAAQ,iBAAiB,mBAAmB,KAAK,WAAW,MAAM,IAAI;AAG/E,KAAI,CAAC,YAAY,OACf,QAAO,QACL,iBACA,WAAW,KAAK,WAAW,MAAM,0CAClC;CAGH,MAAM,wBAAwB;EAC5B,GAAG,qBAAqB,gBAAgB;GACvC,OAAO;EACT;CACD,MAAM,sBAAsB,uBAAuB,QAAQ,gBAAgB,sBAAsB;AAEjG,QAAO,eACL,SACA,YAAY,UACR;EACE,QAAQ;EACR,iBAAiB,YAAY,QAAQ;EACrC,iBAAiB,YAAY;EAC9B,GACD;EACE,QAAQ;EACR,iBAAiB;EACjB,iBAAiB;EAClB,CACN;;AAGH,SAAS,QACP,SACA,SACA,OAA+C,EAAE,EAC3C;AACN,SAAQ,iBAAiB;AACzB,SAAQ,oBAAoB,OAAO;CAKnC,MAAM,eAAe,kBAAkB,SAHrC,QAAQ,iCAAiC,mBACzC,KAAK,mBACL,QAAQ,WAAW,MAAM,iBACsC,QAAQ,oBAAoB;AAC7F,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;;AAG1F,SAAS,MAAqC,SAAkD;AAC9F,SAAQ,iBAAiB,QAAQ;AACjC,SAAQ,oBAAoB,OAAO;CACnC,MAAM,eAAe,kBACnB,QAAQ,gBACR,QAAQ,wBACR,QAAQ,oBACT;AACD,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;;AAG1F,SAAS,QAAuC,SAAkD;AAChG,SAAQ,YAAY;AACpB,SAAQ,WAAW;AACnB,SAAQ,oBAAoB,OAAO;;AAGrC,SAAS,qBACP,SACqC;CACrC,MAAM,EAAE,oBAAoB,QAAQ,WAAW;AAC/C,KAAI,CAAC,gBAAiB,QAAO;AAE7B,QAAO,EACL,UAAU,CACR;EACE,IAAI,gBAAgB;EACpB,OAAO,gBAAgB;EACvB,SAAS,gBAAgB,UACrB;GAAE,OAAO,gBAAgB,QAAQ;GAAO,QAAQ,gBAAgB,QAAQ;GAAQ,GAChF;EACJ,iBAAiB,gBAAgB;EACjC,OAAO,gBAAgB;EACvB,OAAO,gBAAgB;EACxB,CACF,EACF;;AAGH,eAAe,iBACb,SACA,OACe;CACf,MAAM,cAAc,qBAAqB,QAAQ;AACjD,OAAM,QAAQ,UAAU,iBAAiB,OAAO,YAAY;;AAG9D,SAAS,eACP,SACA,QACsD;CACtD,MAAM,eAAe,kBACnB,QAAQ,gBACR,OAAO,iBACP,QAAQ,oBACT;AACD,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;AACxF,QAAO;;AAGT,SAAS,4BACP,MACA,MACS;AACT,QACE,KAAK,oBAAoB,KAAK,mBAC9B,KAAK,oBAAoB,KAAK,mBAC9B,KAAK,OAAO,eAAe,KAAK,OAAO,cACvC,KAAK,OAAO,aAAa,KAAK,OAAO,YACrC,KAAK,OAAO,kBAAkB,KAAK,OAAO;;AAI9C,SAAS,aACP,SACM;CACN,MAAM,OAAO,QAAQ,WAAW;CAChC,MAAM,OAAO,gBACX;EAAE,SAAS,KAAK;EAAS,iBAAiB,KAAK;EAAiB,EAChE,QAAQ,UAAU,UAAU,CAC7B;AAED,KAAI,4BAA4B,MAAM,KAAK,CACzC,SAAQ,WAAW,SAAS,KAAK;;AAIrC,SAAS,QACP,iBACA,QACkC;AAClC,QAAO;EACL,QAAQ;EACR;EACA,iBAAiB;EACjB;EACD"}
+{"version":3,"file":"product-form.mjs","names":[],"sources":["../../../../src/core/product/product-form.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type {\n  CartLine,\n  CartNetworkEntry,\n  CartState,\n  CartUserError,\n  CartWarning,\n} from \"../cart/state\";\nimport { createObservable } from \"../observable\";\nimport {\n  buildProductOptions,\n  type DecodedVariantCache,\n  selectedOptionsFromMap,\n  selectedOptionsToMap,\n} from \"./options\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductOptionValueInput,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n} from \"./state\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/** Cart and line-item errors surfaced by a {@link ProductFormStore}. */\nexport interface ProductFormErrors {\n  userErrors: CartUserError[];\n  warnings: CartWarning[];\n  networkErrors: CartNetworkEntry[];\n}\n\n/** Live state snapshot emitted by a {@link ProductFormStore}. */\nexport interface ProductFormStoreState<\n  TVariant extends ProductVariantInput = ProductVariantInput,\n  TOptionValue extends ProductOptionValueInput = ProductOptionValueInput,\n> {\n  options: VariantOptionState<TVariant, TOptionValue>[];\n  selectedOptions: SelectedOption[];\n  selectedVariant: TVariant | null;\n  errors: ProductFormErrors;\n  matchedLineItem: CartLine | null;\n}\n\n/** The reactive options array from a {@link ProductFormStoreState}, typed to a specific product. */\nexport type ProductFormOptions<TProduct extends ProductInput = ProductInput> =\n  ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[\"options\"];\n\n/**\n * Result returned by {@link ProductFormStore.selectOption}.\n *\n * - `resolved` — a specific variant was matched for the full selection.\n * - `unresolved` — the selection is valid but not yet complete.\n * - `invalid` — the option name or value does not exist on the product.\n */\nexport type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVariantInput> =\n  | {\n      status: \"resolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: TVariant;\n    }\n  | {\n      status: \"unresolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n    }\n  | {\n      status: \"invalid\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n      reason: string;\n    };\n\n/** A selection result that is not invalid — either resolved or unresolved. */\nexport type ValidProductSelectionResult<TProduct extends ProductInput = ProductInput> = Exclude<\n  VariantSelectionResult<ProductVariantFrom<TProduct>>,\n  { status: \"invalid\" }\n>;\n\n/** Options for {@link createProductFormStore}. */\nexport type CreateProductFormStoreOptions = {\n  /** Fallback selection used when the product has no `selectedOrFirstAvailableVariant`. */\n  selectedOptions?: SelectedOption[];\n};\n\n/** Manages variant selection + cart integration for a product form. */\nexport interface ProductFormStore<\n  TProduct extends ProductInput = ProductInput,\n  TVariant extends ProductVariantInput = ProductVariantFrom<TProduct>,\n> {\n  /** Returns the current state snapshot. */\n  getState(): ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>;\n  /** Registers a listener invoked on every state change. Returns an unsubscribe function. */\n  subscribe(\n    listener: (state: ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>) => void,\n  ): () => void;\n  /** Selects an option value and resolves the new variant. */\n  selectOption(name: string, value: string): VariantSelectionResult<TVariant>;\n  /** Replaces the product data and re-derives state — use after a server-side product reload. */\n  hydrate(product: TProduct, opts?: { selectedOptions?: SelectedOption[] }): void;\n  /** Restores the store to its initial product and selection state. */\n  reset(): void;\n  /** Re-subscribes to the cart store and resyncs cart-derived state. Only needed to reuse the store after `destroy()` (e.g. React StrictMode effects). */\n  connect(): void;\n  /** Tears down the store — removes cart subscription and releases resources. */\n  destroy(): void;\n  /** Forwards a native `SubmitEvent` to the cart store's form handler (routed by the submitter's `value`, typically `add`), attaching selected variant data as event detail. */\n  handleFormSubmit(event: SubmitEvent): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Utilities\n// ---------------------------------------------------------------------------\n\n/** Returns the selected variant, or `null` when the selection is partial or the variant wasn't part of the query result. */\nexport function getSelectedVariant<TVariant extends ProductVariantInput>(\n  options: VariantOptionState<TVariant, ProductOptionValueInput>[],\n): TVariant | null {\n  return options[0]?.values.find((v) => v.selected)?.variant ?? null;\n}\n\n/** Guards whether the current selection can be added to cart — a variant must be resolved and available, and the product must not require a selling plan. */\nexport function canAddToCart<TProduct extends ProductInput>(\n  product: TProduct,\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[],\n): boolean {\n  if (product.requiresSellingPlan) return false;\n  const variant = getSelectedVariant(options);\n  return variant !== null && variant.availableForSale;\n}\n\n/**\n * Finds the first cart line whose merchandise ID matches.\n * When selling plans are used, the same merchandise ID can appear on multiple\n * cart lines — this returns the first match. Future attribute-based matching\n * will narrow to the exact line.\n */\nexport function findCartLineByMerchandiseId(\n  lines: CartLine[],\n  merchandiseId: string,\n): CartLine | null {\n  return lines.find((l) => l.merchandise?.id === merchandiseId) ?? null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal context\n// ---------------------------------------------------------------------------\n\ntype ProductFormStoreContext<TProduct extends ProductInput> = {\n  observable: ReturnType<\n    typeof createObservable<\n      ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>\n    >\n  >;\n  cartStore: CartStore;\n  currentProduct: TProduct;\n  initialProduct: TProduct;\n  initialSelectedOptions: SelectedOption[];\n  decodedVariantCache: DecodedVariantCache;\n  destroyed: boolean;\n  unsubCart: () => void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a reactive store that manages variant selection and cart integration for a product form.\n *\n * The store subscribes to the {@link CartStore} to keep error and line-item\n * state in sync. Call `destroy()` when the form unmounts to clean up the\n * subscription.\n *\n * @example\n * ```ts\n * const store = createProductFormStore(product, cartStore);\n *\n * store.subscribe((state) => {\n *   console.log(\"selected variant:\", state.selectedVariant);\n * });\n *\n * store.selectOption(\"Color\", \"Red\");\n * ```\n */\nexport function createProductFormStore<TProduct extends ProductInput>(\n  product: TProduct,\n  cartStore: CartStore,\n  options: CreateProductFormStoreOptions = {},\n): ProductFormStore<TProduct, ProductVariantFrom<TProduct>> {\n  const decodedVariantCache: DecodedVariantCache = new Map();\n  const initialSelectedOptions = resolveSelectedOptions(product, options.selectedOptions);\n\n  const variantState = buildVariantState(product, initialSelectedOptions, decodedVariantCache);\n\n  const context: ProductFormStoreContext<TProduct> = {\n    observable: createObservable(deriveFullState(variantState, cartStore.getState())),\n    cartStore,\n    currentProduct: product,\n    initialProduct: product,\n    initialSelectedOptions,\n    decodedVariantCache,\n    destroyed: false,\n    unsubCart: () => {},\n  };\n\n  context.unsubCart = cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    selectOption: (name, value) => selectOption(context, name, value),\n    hydrate: (nextProduct, opts) => hydrate(context, nextProduct, opts),\n    reset: () => reset(context),\n    connect: () => connect(context),\n    destroy: () => destroy(context),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// State builders\n// ---------------------------------------------------------------------------\n\ntype VariantOnlyState<TProduct extends ProductInput> = {\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[];\n  selectedOptions: SelectedOption[];\n};\n\nfunction buildVariantState<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache: DecodedVariantCache,\n): VariantOnlyState<TProduct> {\n  return {\n    options: buildProductOptions(product, selectedOptions, cache),\n    selectedOptions,\n  };\n}\n\nfunction deriveFullState<TProduct extends ProductInput>(\n  variant: VariantOnlyState<TProduct>,\n  cartState: CartState,\n): ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const selectedVariant = getSelectedVariant(variant.options);\n  const matchedLineItem = selectedVariant\n    ? findCartLineByMerchandiseId(cartState.data.lines.nodes, selectedVariant.id)\n    : null;\n\n  const lineErrors = matchedLineItem ? cartState.errors.lines.get(matchedLineItem.id) : undefined;\n\n  return {\n    options: variant.options,\n    selectedOptions: variant.selectedOptions,\n    selectedVariant,\n    errors: {\n      userErrors: [...cartState.errors.cart.userErrors, ...(lineErrors?.userErrors ?? [])],\n      warnings: [...cartState.errors.cart.warnings, ...(lineErrors?.warnings ?? [])],\n      networkErrors: cartState.errors.network,\n    },\n    matchedLineItem,\n  };\n}\n\nfunction resolveSelectedOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  requested?: SelectedOption[],\n): SelectedOption[] {\n  return product.selectedOrFirstAvailableVariant?.selectedOptions ?? requested ?? [];\n}\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\nfunction selectOption<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  name: string,\n  value: string,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const { options, selectedOptions } = context.observable.state;\n  const option = options.find((o) => o.name === name);\n  const optionValue = option?.values.find((v) => v.name === value);\n\n  if (!option || !optionValue) {\n    return invalid(selectedOptions, `Unknown option \"${name}\" value \"${value}\".`);\n  }\n\n  if (!optionValue.exists) {\n    return invalid(\n      selectedOptions,\n      `Option \"${name}\" value \"${value}\" does not resolve to a product variant.`,\n    );\n  }\n\n  const nextSelectedOptionMap = {\n    ...selectedOptionsToMap(selectedOptions),\n    [name]: value,\n  };\n  const nextSelectedOptions = selectedOptionsFromMap(context.currentProduct, nextSelectedOptionMap);\n\n  return applySelection(\n    context,\n    optionValue.variant\n      ? {\n          status: \"resolved\",\n          selectedOptions: optionValue.variant.selectedOptions,\n          selectedVariant: optionValue.variant as ProductVariantFrom<TProduct>,\n        }\n      : {\n          status: \"unresolved\",\n          selectedOptions: nextSelectedOptions,\n          selectedVariant: null,\n        },\n  );\n}\n\nfunction hydrate<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  product: TProduct,\n  opts: { selectedOptions?: SelectedOption[] } = {},\n): void {\n  context.currentProduct = product;\n  context.decodedVariantCache.clear();\n  const selectedOptions =\n    product.selectedOrFirstAvailableVariant?.selectedOptions ??\n    opts.selectedOptions ??\n    context.observable.state.selectedOptions;\n  const variantState = buildVariantState(product, selectedOptions, context.decodedVariantCache);\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction reset<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.currentProduct = context.initialProduct;\n  context.decodedVariantCache.clear();\n  const variantState = buildVariantState(\n    context.initialProduct,\n    context.initialSelectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction connect<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.unsubCart();\n  context.destroyed = false;\n  context.unsubCart = context.cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n  syncFromCart(context);\n}\n\nfunction destroy<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.destroyed = true;\n  context.unsubCart();\n  context.decodedVariantCache.clear();\n}\n\nfunction buildAddToCartDetail<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): Record<string, unknown> | undefined {\n  const { selectedVariant } = context.observable.state;\n  if (!selectedVariant) return undefined;\n\n  return {\n    products: [\n      {\n        id: selectedVariant.id,\n        title: selectedVariant.title,\n        product: selectedVariant.product\n          ? { title: selectedVariant.product.title, handle: selectedVariant.product.handle }\n          : undefined,\n        selectedOptions: selectedVariant.selectedOptions,\n        image: selectedVariant.image,\n        price: selectedVariant.price,\n      },\n    ],\n  };\n}\n\nasync function handleFormSubmit<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  event: SubmitEvent,\n): Promise<void> {\n  const eventDetail = buildAddToCartDetail(context);\n  await context.cartStore.handleFormSubmit(event, eventDetail);\n}\n\nfunction applySelection<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  result: Exclude<VariantSelectionResult<ProductVariantFrom<TProduct>>, { status: \"invalid\" }>,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const variantState = buildVariantState(\n    context.currentProduct,\n    result.selectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n  return result;\n}\n\nfunction hasCartDerivedFieldsChanged<TVariant extends ProductVariantInput>(\n  prev: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n  next: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n): boolean {\n  return (\n    prev.matchedLineItem !== next.matchedLineItem ||\n    prev.selectedVariant !== next.selectedVariant ||\n    prev.errors.userErrors !== next.errors.userErrors ||\n    prev.errors.warnings !== next.errors.warnings ||\n    prev.errors.networkErrors !== next.errors.networkErrors\n  );\n}\n\nfunction syncFromCart<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): void {\n  const prev = context.observable.state;\n  const next = deriveFullState(\n    { options: prev.options, selectedOptions: prev.selectedOptions },\n    context.cartStore.getState(),\n  );\n\n  if (hasCartDerivedFieldsChanged(prev, next)) {\n    context.observable.setState(next);\n  }\n}\n\nfunction invalid<TVariant extends ProductVariantInput>(\n  selectedOptions: SelectedOption[],\n  reason: string,\n): VariantSelectionResult<TVariant> {\n  return {\n    status: \"invalid\",\n    selectedOptions,\n    selectedVariant: null,\n    reason,\n  };\n}\n"],"mappings":";;;;;AAuHA,SAAgB,mBACd,SACiB;AACjB,QAAO,QAAQ,IAAI,OAAO,MAAM,MAAM,EAAE,SAAS,EAAE,WAAW;;;AAIhE,SAAgB,aACd,SACA,SACS;AACT,KAAI,QAAQ,oBAAqB,QAAO;CACxC,MAAM,UAAU,mBAAmB,QAAQ;AAC3C,QAAO,YAAY,QAAQ,QAAQ;;;;;;;;AASrC,SAAgB,4BACd,OACA,eACiB;AACjB,QAAO,MAAM,MAAM,MAAM,EAAE,aAAa,OAAO,cAAc,IAAI;;;;;;;;;;;;;;;;;;;;AA4CnE,SAAgB,uBACd,SACA,WACA,UAAyC,EAAE,EACe;CAC1D,MAAM,sCAA2C,IAAI,KAAK;CAC1D,MAAM,yBAAyB,uBAAuB,SAAS,QAAQ,gBAAgB;CAIvF,MAAM,UAA6C;EACjD,YAAY,iBAAiB,gBAHV,kBAAkB,SAAS,wBAAwB,oBAGb,EAAE,UAAU,UAAU,CAAC,CAAC;EACjF;EACA,gBAAgB;EAChB,gBAAgB;EAChB;EACA;EACA,WAAW;EACX,iBAAiB;EAClB;AAED,SAAQ,YAAY,UAAU,gBAAgB;AAC5C,MAAI,QAAQ,UAAW;AACvB,eAAa,QAAQ;GACrB;AAEF,QAAO;EACL,gBAAgB,QAAQ,WAAW;EACnC,YAAY,aAAa,QAAQ,WAAW,UAAU,SAAS;EAC/D,eAAe,MAAM,UAAU,aAAa,SAAS,MAAM,MAAM;EACjE,UAAU,aAAa,SAAS,QAAQ,SAAS,aAAa,KAAK;EACnE,aAAa,MAAM,QAAQ;EAC3B,eAAe,QAAQ,QAAQ;EAC/B,eAAe,QAAQ,QAAQ;EAC/B,mBAAmB,UAAU,iBAAiB,SAAS,MAAM;EAC9D;;AAYH,SAAS,kBACP,SACA,iBACA,OAC4B;AAC5B,QAAO;EACL,SAAS,oBAAoB,SAAS,iBAAiB,MAAM;EAC7D;EACD;;AAGH,SAAS,gBACP,SACA,WACuF;CACvF,MAAM,kBAAkB,mBAAmB,QAAQ,QAAQ;CAC3D,MAAM,kBAAkB,kBACpB,4BAA4B,UAAU,KAAK,MAAM,OAAO,gBAAgB,GAAG,GAC3E;CAEJ,MAAM,aAAa,kBAAkB,UAAU,OAAO,MAAM,IAAI,gBAAgB,GAAG,GAAG;AAEtF,QAAO;EACL,SAAS,QAAQ;EACjB,iBAAiB,QAAQ;EACzB;EACA,QAAQ;GACN,YAAY,CAAC,GAAG,UAAU,OAAO,KAAK,YAAY,GAAI,YAAY,cAAc,EAAE,CAAE;GACpF,UAAU,CAAC,GAAG,UAAU,OAAO,KAAK,UAAU,GAAI,YAAY,YAAY,EAAE,CAAE;GAC9E,eAAe,UAAU,OAAO;GACjC;EACD;EACD;;AAGH,SAAS,uBACP,SACA,WACkB;AAClB,QAAO,QAAQ,iCAAiC,mBAAmB,aAAa,EAAE;;AAOpF,SAAS,aACP,SACA,MACA,OACsD;CACtD,MAAM,EAAE,SAAS,oBAAoB,QAAQ,WAAW;CACxD,MAAM,SAAS,QAAQ,MAAM,MAAM,EAAE,SAAS,KAAK;CACnD,MAAM,cAAc,QAAQ,OAAO,MAAM,MAAM,EAAE,SAAS,MAAM;AAEhE,KAAI,CAAC,UAAU,CAAC,YACd,QAAO,QAAQ,iBAAiB,mBAAmB,KAAK,WAAW,MAAM,IAAI;AAG/E,KAAI,CAAC,YAAY,OACf,QAAO,QACL,iBACA,WAAW,KAAK,WAAW,MAAM,0CAClC;CAGH,MAAM,wBAAwB;EAC5B,GAAG,qBAAqB,gBAAgB;GACvC,OAAO;EACT;CACD,MAAM,sBAAsB,uBAAuB,QAAQ,gBAAgB,sBAAsB;AAEjG,QAAO,eACL,SACA,YAAY,UACR;EACE,QAAQ;EACR,iBAAiB,YAAY,QAAQ;EACrC,iBAAiB,YAAY;EAC9B,GACD;EACE,QAAQ;EACR,iBAAiB;EACjB,iBAAiB;EAClB,CACN;;AAGH,SAAS,QACP,SACA,SACA,OAA+C,EAAE,EAC3C;AACN,SAAQ,iBAAiB;AACzB,SAAQ,oBAAoB,OAAO;CAKnC,MAAM,eAAe,kBAAkB,SAHrC,QAAQ,iCAAiC,mBACzC,KAAK,mBACL,QAAQ,WAAW,MAAM,iBACsC,QAAQ,oBAAoB;AAC7F,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;;AAG1F,SAAS,MAAqC,SAAkD;AAC9F,SAAQ,iBAAiB,QAAQ;AACjC,SAAQ,oBAAoB,OAAO;CACnC,MAAM,eAAe,kBACnB,QAAQ,gBACR,QAAQ,wBACR,QAAQ,oBACT;AACD,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;;AAG1F,SAAS,QAAuC,SAAkD;AAChG,SAAQ,WAAW;AACnB,SAAQ,YAAY;AACpB,SAAQ,YAAY,QAAQ,UAAU,gBAAgB;AACpD,MAAI,QAAQ,UAAW;AACvB,eAAa,QAAQ;GACrB;AACF,cAAa,QAAQ;;AAGvB,SAAS,QAAuC,SAAkD;AAChG,SAAQ,YAAY;AACpB,SAAQ,WAAW;AACnB,SAAQ,oBAAoB,OAAO;;AAGrC,SAAS,qBACP,SACqC;CACrC,MAAM,EAAE,oBAAoB,QAAQ,WAAW;AAC/C,KAAI,CAAC,gBAAiB,QAAO;AAE7B,QAAO,EACL,UAAU,CACR;EACE,IAAI,gBAAgB;EACpB,OAAO,gBAAgB;EACvB,SAAS,gBAAgB,UACrB;GAAE,OAAO,gBAAgB,QAAQ;GAAO,QAAQ,gBAAgB,QAAQ;GAAQ,GAChF;EACJ,iBAAiB,gBAAgB;EACjC,OAAO,gBAAgB;EACvB,OAAO,gBAAgB;EACxB,CACF,EACF;;AAGH,eAAe,iBACb,SACA,OACe;CACf,MAAM,cAAc,qBAAqB,QAAQ;AACjD,OAAM,QAAQ,UAAU,iBAAiB,OAAO,YAAY;;AAG9D,SAAS,eACP,SACA,QACsD;CACtD,MAAM,eAAe,kBACnB,QAAQ,gBACR,OAAO,iBACP,QAAQ,oBACT;AACD,SAAQ,WAAW,SAAS,gBAAgB,cAAc,QAAQ,UAAU,UAAU,CAAC,CAAC;AACxF,QAAO;;AAGT,SAAS,4BACP,MACA,MACS;AACT,QACE,KAAK,oBAAoB,KAAK,mBAC9B,KAAK,oBAAoB,KAAK,mBAC9B,KAAK,OAAO,eAAe,KAAK,OAAO,cACvC,KAAK,OAAO,aAAa,KAAK,OAAO,YACrC,KAAK,OAAO,kBAAkB,KAAK,OAAO;;AAI9C,SAAS,aACP,SACM;CACN,MAAM,OAAO,QAAQ,WAAW;CAChC,MAAM,OAAO,gBACX;EAAE,SAAS,KAAK;EAAS,iBAAiB,KAAK;EAAiB,EAChE,QAAQ,UAAU,UAAU,CAC7B;AAED,KAAI,4BAA4B,MAAM,KAAK,CACzC,SAAQ,WAAW,SAAS,KAAK;;AAIrC,SAAS,QACP,iBACA,QACkC;AAClC,QAAO;EACL,QAAQ;EACR;EACA,iBAAiB;EACjB;EACD"}

package/dist/development/core/product/state.d.mts

@@ -1,22 +1,33 @@
 //#region src/core/product/state.d.ts
+/** Monetary amount in a specific currency, mirroring the Storefront API `MoneyV2` type. */
 interface Money {
   amount: string;
   currencyCode: string;
 }
+/** Minimum and maximum variant prices for a product, mirroring the Storefront API `ProductPriceRange` type. */
 interface ProductPriceRange {
   minVariantPrice: Money;
+  /** Optional so queries that only select `minVariantPrice` still type-check. */
   maxVariantPrice?: Money;
 }
+/** A single selected product option, e.g. `{ name: "Color", value: "Red" }`. */
 interface SelectedOption {
   name: string;
   value: string;
 }
+/**
+ * Minimum variant shape that the product form system requires.
+ *
+ * Consumers typically pass a wider type from their Storefront API query —
+ * `ProductVariantInput` declares only the fields the form logic reads.
+ */
 interface ProductVariantInput {
   id: string;
   title: string;
   availableForSale: boolean;
   selectedOptions: SelectedOption[];
   price: Money;
+  /** Merchant-set compare-at price, typically shown struck-through when higher than `price`. `null` when unset; `undefined` when not queried. */
   compareAtPrice?: Money | null;
   image?: unknown;
   product?: {
@@ -25,40 +36,70 @@ interface ProductVariantInput {
   } | null;
   sku?: string | null;
 }
+/** A product option (e.g. "Size" or "Color") and its available values. */
 interface ProductOptionInput<TVariant extends ProductVariantInput = ProductVariantInput> {
   name: string;
   optionValues: Array<ProductOptionValueInput<TVariant>>;
 }
+/** A single option value (e.g. "Small", "Red") within a {@link ProductOptionInput}. */
 interface ProductOptionValueInput<TVariant extends ProductVariantInput = ProductVariantInput> {
   name: string;
+  /** The variant combining this value with the lowest-position values of every other option (SFAPI). Strongly recommended: it seeds the variant cache used for `exists`/`selectedOptions` and combined-listing detection. */
   firstSelectableVariant?: TVariant | null;
   swatch?: unknown;
 }
+/**
+ * Minimum product shape that `createProductFormStore` requires.
+ *
+ * Fields mirror the Storefront API `Product` object. Consumers typically
+ * pass a wider query result — this interface declares only what the
+ * product form logic reads.
+ */
 interface ProductInput<TVariant extends ProductVariantInput = ProductVariantInput> {
   id: string;
   title: string;
   handle: string;
   vendor?: string | null;
   priceRange?: ProductPriceRange;
+  /** When `true`, the product cannot be added to cart without a selling plan. */
   requiresSellingPlan?: boolean | null;
+  /** Encoded representation of which option-value combinations map to real variants. Consumers should treat this as opaque. */
   encodedVariantExistence?: string | null;
+  /** Encoded representation of which existing variants are currently available for sale. Consumers should treat this as opaque. */
   encodedVariantAvailability?: string | null;
   options: ProductOptionInput<TVariant>[];
+  /** SFAPI `selectedOrFirstAvailableVariant`: the variant matching the query's `selectedOptions` argument, else the first available variant, else the first variant (which may be unavailable). */
   selectedOrFirstAvailableVariant: TVariant | null;
+  /** Variants adjacent to the selected variant — used to resolve option values without a full variant list. */
   adjacentVariants: TVariant[];
 }
+/** Extracts the concrete variant type from a {@link ProductInput} subtype. */
 type ProductVariantFrom<TProduct extends ProductInput> = TProduct extends ProductInput<infer TVariant> ? TVariant : ProductVariantInput;
+/** Extracts the concrete option-value type from a {@link ProductInput} subtype. */
 type ProductOptionValueFrom<TProduct extends ProductInput> = TProduct["options"][number]["optionValues"][number];
+/**
+ * Computed state for a single option value (e.g. "Red" under "Color").
+ *
+ * Derived each time the selection changes — fields reflect the current
+ * selection context, not static product data.
+ */
 interface VariantOptionValueState<TVariant extends ProductVariantInput = ProductVariantInput, TOptionValue extends ProductOptionValueInput = ProductOptionValueInput> {
   name: string;
   swatch?: TOptionValue["swatch"];
+  /** Whether this value is the current selection for its option. */
   selected: boolean;
+  /** Whether a variant exists for the target selection. Falls back to `true` when `encodedVariantExistence` wasn't queried. */
   exists: boolean;
+  /** Whether the target selection is available for sale. Uses `encodedVariantAvailability` when queried, otherwise the loaded variant's `availableForSale` (`false` if not loaded). */
   available: boolean;
+  /** The loaded variant for the target selection, or `null` if the selection is partial or that variant wasn't part of the query result. */
   variant: TVariant | null;
+  /** The selection this value targets. Use for link building; `selectOption()` is the source of truth for the resulting selection. */
   selectedOptions: SelectedOption[];
+  /** Product handle, useful for building navigation links to combined-listing child products. */
   handle: string;
 }
+/** Computed state for a product option (e.g. "Color"), grouping its {@link VariantOptionValueState} entries. */
 interface VariantOptionState<TVariant extends ProductVariantInput = ProductVariantInput, TOptionValue extends ProductOptionValueInput = ProductOptionValueInput> {
   name: string;
   values: VariantOptionValueState<TVariant, TOptionValue>[];

package/dist/development/core/product/url.d.mts

@@ -1,6 +1,12 @@
 import { SelectedOption } from "./state.mjs";
 
 //#region src/core/product/url.d.ts
+/**
+ * Controls how variant selection is encoded in URL search params.
+ *
+ * - `"options"` — one param per option, e.g. `?Color=Red&Size=M`.
+ * - `"variant"` — a single `?variant=<numeric id>` param (Liquid parity).
+ */
 type ProductSelectionLinkStyle = "options" | "variant";
 /**
  * Builds the search params for a product-page link representing a variant selection.

package/dist/development/core/product/url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"url.mjs","names":[],"sources":["../../../../src/core/product/url.ts"],"sourcesContent":["import type { SelectedOption } from \"./state\";\n\nconst VARIANT_GID_PREFIX = \"gid://shopify/ProductVariant/\";\n\n/**\n * Reserved product-page search param carrying a numeric variant id (`?variant=41820371452004`),\n * matching Liquid storefront URLs. Never treated as a product option name.\n */\nexport const VARIANT_SEARCH_PARAM = \"variant\";\n\n/**\n * Converts a `?variant=` search param value into a variant id (gid).\n *\n * Anything that is not a plain positive integer of a plausible length is treated as absent\n * (`null`) so malformed links degrade to the default variant instead of producing invalid\n * API lookups or log spam.\n */\nexport function parseVariantSearchParam(value: string | null): string | null {\n  if (!value || !/^\\d{1,30}$/.test(value)) return null;\n  return `${VARIANT_GID_PREFIX}${value}`;\n}\n\n/**\n * Extracts the numeric `?variant=` search param value from a variant id (gid).\n * Returns `null` for ids that are not canonical `gid://shopify/ProductVariant/<numeric>` ids.\n */\nexport function getVariantSearchParamValue(variantId: string): string | null {\n  if (!variantId.startsWith(VARIANT_GID_PREFIX)) return null;\n\n  const numericId = variantId.slice(VARIANT_GID_PREFIX.length);\n  return /^\\d+$/.test(numericId) ? numericId : null;\n}\n\nexport type ProductSelectionLinkStyle = \"options\" | \"variant\";\n\n/**\n * Builds the search params for a product-page link representing a variant selection.\n *\n * Existing `base` params are preserved (`?ref=campaign` survives navigation), except the\n * reserved `variant` param and every param named in `optionNames` or `selectedOptions`,\n * which are always removed before the new selection is written. This keeps stale selection\n * state from leaking between navigations, including across combined-listing products.\n *\n * Two link styles:\n * - `\"options\"` (default): one param per selected option, e.g. `?Color=Red&Size=M`.\n * - `\"variant\"`: a single `?variant=<numeric id>` param (Liquid parity), for shareable\n *   links. Falls back to option params when `variant` is absent — a partial selection has\n *   no matching variant, so a variant link is not constructible.\n *\n * @example\n * ```ts\n * const searchParams = buildProductSelectionSearchParams({\n *   selectedOptions: result.selectedOptions,\n *   variant: result.selectedVariant,\n *   optionNames: product.options.map((option) => option.name),\n *   base: new URLSearchParams(location.search),\n * });\n * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : \"\"}`;\n * ```\n */\nexport function buildProductSelectionSearchParams({\n  style = \"options\",\n  selectedOptions,\n  variant,\n  optionNames,\n  base,\n}: {\n  style?: ProductSelectionLinkStyle;\n  selectedOptions: readonly SelectedOption[];\n  variant?: { id: string } | null;\n  optionNames: readonly string[];\n  base?: URLSearchParams;\n}): URLSearchParams {\n  const searchParams = new URLSearchParams(base);\n\n  searchParams.delete(VARIANT_SEARCH_PARAM);\n  for (const name of optionNames) searchParams.delete(name);\n  for (const option of selectedOptions) searchParams.delete(option.name);\n\n  const variantSearchParamValue =\n    style === \"variant\" && variant ? getVariantSearchParamValue(variant.id) : null;\n\n  if (variantSearchParamValue) {\n    searchParams.set(VARIANT_SEARCH_PARAM, variantSearchParamValue);\n    return searchParams;\n  }\n\n  for (const option of selectedOptions) {\n    searchParams.set(option.name, option.value);\n  }\n\n  return searchParams;\n}\n"],"mappings":";AAEA,MAAM,qBAAqB;;;;;AAM3B,MAAa,uBAAuB;;;;;;;;AASpC,SAAgB,wBAAwB,OAAqC;AAC3E,KAAI,CAAC,SAAS,CAAC,aAAa,KAAK,MAAM,CAAE,QAAO;AAChD,QAAO,GAAG,qBAAqB;;;;;;AAOjC,SAAgB,2BAA2B,WAAkC;AAC3E,KAAI,CAAC,UAAU,WAAW,mBAAmB,CAAE,QAAO;CAEtD,MAAM,YAAY,UAAU,MAAM,GAA0B;AAC5D,QAAO,QAAQ,KAAK,UAAU,GAAG,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8B/C,SAAgB,kCAAkC,EAChD,QAAQ,WACR,iBACA,SACA,aACA,QAOkB;CAClB,MAAM,eAAe,IAAI,gBAAgB,KAAK;AAE9C,cAAa,OAAO,qBAAqB;AACzC,MAAK,MAAM,QAAQ,YAAa,cAAa,OAAO,KAAK;AACzD,MAAK,MAAM,UAAU,gBAAiB,cAAa,OAAO,OAAO,KAAK;CAEtE,MAAM,0BACJ,UAAU,aAAa,UAAU,2BAA2B,QAAQ,GAAG,GAAG;AAE5E,KAAI,yBAAyB;AAC3B,eAAa,IAAI,sBAAsB,wBAAwB;AAC/D,SAAO;;AAGT,MAAK,MAAM,UAAU,gBACnB,cAAa,IAAI,OAAO,MAAM,OAAO,MAAM;AAG7C,QAAO"}
+{"version":3,"file":"url.mjs","names":[],"sources":["../../../../src/core/product/url.ts"],"sourcesContent":["import type { SelectedOption } from \"./state\";\n\nconst VARIANT_GID_PREFIX = \"gid://shopify/ProductVariant/\";\n\n/**\n * Reserved product-page search param carrying a numeric variant id (`?variant=41820371452004`),\n * matching Liquid storefront URLs. Never treated as a product option name.\n */\nexport const VARIANT_SEARCH_PARAM = \"variant\";\n\n/**\n * Converts a `?variant=` search param value into a variant id (gid).\n *\n * Anything that is not a plain positive integer of a plausible length is treated as absent\n * (`null`) so malformed links degrade to the default variant instead of producing invalid\n * API lookups or log spam.\n */\nexport function parseVariantSearchParam(value: string | null): string | null {\n  if (!value || !/^\\d{1,30}$/.test(value)) return null;\n  return `${VARIANT_GID_PREFIX}${value}`;\n}\n\n/**\n * Extracts the numeric `?variant=` search param value from a variant id (gid).\n * Returns `null` for ids that are not canonical `gid://shopify/ProductVariant/<numeric>` ids.\n */\nexport function getVariantSearchParamValue(variantId: string): string | null {\n  if (!variantId.startsWith(VARIANT_GID_PREFIX)) return null;\n\n  const numericId = variantId.slice(VARIANT_GID_PREFIX.length);\n  return /^\\d+$/.test(numericId) ? numericId : null;\n}\n\n/**\n * Controls how variant selection is encoded in URL search params.\n *\n * - `\"options\"` — one param per option, e.g. `?Color=Red&Size=M`.\n * - `\"variant\"` — a single `?variant=<numeric id>` param (Liquid parity).\n */\nexport type ProductSelectionLinkStyle = \"options\" | \"variant\";\n\n/**\n * Builds the search params for a product-page link representing a variant selection.\n *\n * Existing `base` params are preserved (`?ref=campaign` survives navigation), except the\n * reserved `variant` param and every param named in `optionNames` or `selectedOptions`,\n * which are always removed before the new selection is written. This keeps stale selection\n * state from leaking between navigations, including across combined-listing products.\n *\n * Two link styles:\n * - `\"options\"` (default): one param per selected option, e.g. `?Color=Red&Size=M`.\n * - `\"variant\"`: a single `?variant=<numeric id>` param (Liquid parity), for shareable\n *   links. Falls back to option params when `variant` is absent — a partial selection has\n *   no matching variant, so a variant link is not constructible.\n *\n * @example\n * ```ts\n * const searchParams = buildProductSelectionSearchParams({\n *   selectedOptions: result.selectedOptions,\n *   variant: result.selectedVariant,\n *   optionNames: product.options.map((option) => option.name),\n *   base: new URLSearchParams(location.search),\n * });\n * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : \"\"}`;\n * ```\n */\nexport function buildProductSelectionSearchParams({\n  style = \"options\",\n  selectedOptions,\n  variant,\n  optionNames,\n  base,\n}: {\n  style?: ProductSelectionLinkStyle;\n  selectedOptions: readonly SelectedOption[];\n  variant?: { id: string } | null;\n  optionNames: readonly string[];\n  base?: URLSearchParams;\n}): URLSearchParams {\n  const searchParams = new URLSearchParams(base);\n\n  searchParams.delete(VARIANT_SEARCH_PARAM);\n  for (const name of optionNames) searchParams.delete(name);\n  for (const option of selectedOptions) searchParams.delete(option.name);\n\n  const variantSearchParamValue =\n    style === \"variant\" && variant ? getVariantSearchParamValue(variant.id) : null;\n\n  if (variantSearchParamValue) {\n    searchParams.set(VARIANT_SEARCH_PARAM, variantSearchParamValue);\n    return searchParams;\n  }\n\n  for (const option of selectedOptions) {\n    searchParams.set(option.name, option.value);\n  }\n\n  return searchParams;\n}\n"],"mappings":";AAEA,MAAM,qBAAqB;;;;;AAM3B,MAAa,uBAAuB;;;;;;;;AASpC,SAAgB,wBAAwB,OAAqC;AAC3E,KAAI,CAAC,SAAS,CAAC,aAAa,KAAK,MAAM,CAAE,QAAO;AAChD,QAAO,GAAG,qBAAqB;;;;;;AAOjC,SAAgB,2BAA2B,WAAkC;AAC3E,KAAI,CAAC,UAAU,WAAW,mBAAmB,CAAE,QAAO;CAEtD,MAAM,YAAY,UAAU,MAAM,GAA0B;AAC5D,QAAO,QAAQ,KAAK,UAAU,GAAG,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC/C,SAAgB,kCAAkC,EAChD,QAAQ,WACR,iBACA,SACA,aACA,QAOkB;CAClB,MAAM,eAAe,IAAI,gBAAgB,KAAK;AAE9C,cAAa,OAAO,qBAAqB;AACzC,MAAK,MAAM,QAAQ,YAAa,cAAa,OAAO,KAAK;AACzD,MAAK,MAAM,UAAU,gBAAiB,cAAa,OAAO,OAAO,KAAK;CAEtE,MAAM,0BACJ,UAAU,aAAa,UAAU,2BAA2B,QAAQ,GAAG,GAAG;AAE5E,KAAI,yBAAyB;AAC3B,eAAa,IAAI,sBAAsB,wBAAwB;AAC/D,SAAO;;AAGT,MAAK,MAAM,UAAU,gBACnB,cAAa,IAAI,OAAO,MAAM,OAAO,MAAM;AAG7C,QAAO"}

package/dist/development/core/request-context.d.mts

@@ -30,9 +30,6 @@ type ShopifyRequestContextBase = {
    */
   readonly __hydrogenShopifyRequestContextBrand: never; /** @internal */
   cookie?: string; /** @internal */
-  uniqueToken?: string; /** @internal */
-  visitToken?: string; /** @internal */
-  legacyTokens?: boolean; /** @internal */
   readonly buyerIp?: string; /** @internal */
   requestGroupId: string; /** @internal */
   signal?: AbortSignal; /** @internal */
@@ -44,12 +41,12 @@ type ShopifyRequestContextBase = {
    */
   applyStorefrontRequestHeaders(headers: Headers): void;
   /**
-   * Capture the first fresh storefront response headers for replay onto the final app response.
+   * Capture cookies from the first fresh storefront response that sets them for replay.
    * @internal
    */
   captureSubrequestHeaders(headers: Headers): void;
   /**
-   * Consume storefront proxy response state for gated replay onto the final app response.
+   * Consume storefront proxy cookies for gated replay onto the final app response.
    * @internal
    */
   consumeStorefrontResponseHeaders(headers: Headers): void;
@@ -58,6 +55,12 @@ type ShopifyRequestContextBase = {
    * @internal
    */
   markResponseAsPersonalized(reason: string): void;
+  /**
+   * Mark this request as a sanctioned session-establishing endpoint (like the
+   * consent flow), permitting Shopify state to return even on a cold session.
+   * @internal
+   */
+  markResponseAsSessionEstablishing(reason: string): void;
   i18n: NormalizedI18nConfig; /** Return incoming request headers plus request lifecycle headers for proxy/origin handoff. */
   getForwardedRequestHeaders(): Headers; /** Apply important response headers for the correct functioning of Hydrogen storefronts. */
   applyResponseHeaders(headers: Headers): void;

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

@@ -1,11 +1,9 @@
 import { normalizePathPrefix } from "./standard-routes/path.mjs";
 import { STOREFRONT_API_VERSION } from "./constants.mjs";
-import { CONSENT_MANAGEMENT_HEADER, HYDROGEN_VERSION_HEADER, REQUEST_GROUP_ID_HEADER, SDK_VARIANT_HEADER, SDK_VARIANT_SOURCE_HEADER, SDK_VERSION_HEADER, SERVER_TIMING_HEADER, SHOPIFY_STOREFRONT_ORIGIN_HEADER, SHOPIFY_STOREFRONT_S_HEADER, SHOPIFY_STOREFRONT_Y_HEADER, SHOPIFY_UNIQUE_TOKEN_HEADER, SHOPIFY_VISIT_TOKEN_HEADER, STOREFRONT_URL_HEADER, applyPrivateResponseCacheHeaders } from "./headers.mjs";
+import { CONSENT_MANAGEMENT_HEADER, HYDROGEN_VERSION_HEADER, REQUEST_GROUP_ID_HEADER, SDK_VARIANT_HEADER, SDK_VARIANT_SOURCE_HEADER, SDK_VERSION_HEADER, SEC_GPC_HEADER, SHOPIFY_STOREFRONT_ORIGIN_HEADER, STOREFRONT_URL_HEADER, applyPrivateResponseCacheHeaders } from "./headers.mjs";
 
 //#region src/core/request-context.ts
 const SHOPIFY_ESSENTIAL_COOKIE = "_shopify_essential";
-const SHOPIFY_TRACKING_COOKIES = ["_shopify_analytics", "_shopify_marketing"];
-const SHOPIFY_COOKIES = new Set([SHOPIFY_ESSENTIAL_COOKIE, ...SHOPIFY_TRACKING_COOKIES]);
 function createShopifyRequestContext(input) {
 	const { request } = input;
 	if (!input.i18n?.country || !input.i18n?.language) throw new Error("i18n with country and language is required for Shopify request contexts.");
@@ -13,14 +11,13 @@ function createShopifyRequestContext(input) {
 	const requestMethod = request.method?.toUpperCase();
 	const i18n = normalizeI18n(input.i18n);
 	const cookieHeader = request.headers.get("cookie") || void 0;
-	const inboundCookies = parseCookieHeader(cookieHeader);
-	const hasEssentialCookie = inboundCookies.has(SHOPIFY_ESSENTIAL_COOKIE);
-	const hasTrackingCookie = SHOPIFY_TRACKING_COOKIES.some((name) => inboundCookies.has(name));
+	const hasEssentialCookie = parseCookieHeader(cookieHeader).has(SHOPIFY_ESSENTIAL_COOKIE);
 	const isConsentManagementRequest = request.headers.get(CONSENT_MANAGEMENT_HEADER) === "1";
 	const url = request.url ?? request.headers.get("x-storefront-url") ?? void 0;
 	const storefrontOrigin = getUrlOrigin(url);
 	const context = {
 		...cookieHeader && { cookie: cookieHeader },
+		globalPrivacyControl: request.headers.get("Sec-GPC") ?? void 0,
 		i18n,
 		...url && { url },
 		...storefrontOrigin && { storefrontOrigin },
@@ -29,23 +26,13 @@ function createShopifyRequestContext(input) {
 		...isDocumentRequest(request) && { documentRequest: true },
 		...request.signal && { signal: request.signal }
 	};
-	let capturedSubrequestHeaders;
+	let capturedCookies;
 	let personalizedResponseReason;
+	let sessionEstablishingReason;
 	const captureSubrequestHeaders = (headers) => {
-		capturedSubrequestHeaders ??= {
-			serverTiming: headers.get("Server-Timing") ?? "",
-			setCookie: headers.getSetCookie()
-		};
+		const cookies = headers.getSetCookie();
+		if (cookies.length > 0) capturedCookies ??= cookies;
 	};
-	if (!hasTrackingCookie) {
-		const legacyUniqueToken = inboundCookies.get("_shopify_y");
-		const legacyVisitToken = inboundCookies.get("_shopify_s");
-		const headerUniqueToken = request.headers.get("X-Shopify-UniqueToken") ?? void 0;
-		const headerVisitToken = request.headers.get("X-Shopify-VisitToken") ?? void 0;
-		if (legacyUniqueToken || legacyVisitToken) context.legacyTokens = true;
-		context.uniqueToken = legacyUniqueToken ?? headerUniqueToken;
-		context.visitToken = legacyVisitToken ?? headerVisitToken;
-	}
 	return {
 		...context,
 		getForwardedRequestHeaders() {
@@ -59,30 +46,27 @@ function createShopifyRequestContext(input) {
 		},
 		captureSubrequestHeaders,
 		consumeStorefrontResponseHeaders(headers) {
-			if (headers.has("Server-Timing") || headers.getSetCookie().length > 0) captureSubrequestHeaders(headers);
+			captureSubrequestHeaders(headers);
 			headers.delete("set-cookie");
-			headers.delete(SERVER_TIMING_HEADER);
 		},
 		markResponseAsPersonalized(reason) {
 			personalizedResponseReason ??= reason;
 		},
+		markResponseAsSessionEstablishing(reason) {
+			sessionEstablishingReason ??= reason;
+		},
 		applyResponseHeaders(headers) {
 			headers.set("powered-by", "Shopify, Hydrogen");
 			const isDocumentResponse = context.documentRequest || (headers.get("content-type")?.startsWith("text/html") ?? false);
-			const mayReturnShopifyState = requestMethod !== void 0 && requestMethod !== "GET" && requestMethod !== "HEAD" && !isDocumentResponse && (hasEssentialCookie || isConsentManagementRequest);
-			if (capturedSubrequestHeaders && mayReturnShopifyState) {
+			if (capturedCookies && requestMethod !== void 0 && requestMethod !== "GET" && requestMethod !== "HEAD" && !isDocumentResponse && (hasEssentialCookie || isConsentManagementRequest || sessionEstablishingReason !== void 0)) {
 				const existingSetCookies = new Set(headers.getSetCookie());
-				for (const value of capturedSubrequestHeaders.setCookie) {
+				for (const value of capturedCookies) {
 					if (existingSetCookies.has(value)) continue;
 					headers.append("set-cookie", value);
 					existingSetCookies.add(value);
 				}
-				const capturedServerTiming = capturedSubrequestHeaders.serverTiming;
-				const existingServerTiming = headers.get("Server-Timing") ?? "";
-				if (capturedServerTiming !== "" && existingServerTiming !== capturedServerTiming && !existingServerTiming.startsWith(`${capturedServerTiming}, `) && !existingServerTiming.endsWith(`, ${capturedServerTiming}`)) headers.set(SERVER_TIMING_HEADER, existingServerTiming ? `${existingServerTiming}, ${capturedServerTiming}` : capturedServerTiming);
 			}
-			const returnsCapturedState = mayReturnShopifyState && Boolean(capturedSubrequestHeaders?.serverTiming || capturedSubrequestHeaders?.setCookie.length);
-			if (personalizedResponseReason || returnsCapturedState || headers.getSetCookie().some(isShopifySetCookie)) applyPrivateResponseCacheHeaders(headers);
+			if (personalizedResponseReason || isConsentManagementRequest || sessionEstablishingReason !== void 0 || headers.has("set-cookie")) applyPrivateResponseCacheHeaders(headers);
 		}
 	};
 }
@@ -96,16 +80,14 @@ 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-preview.2");
+	headers.set(HYDROGEN_VERSION_HEADER, "2026.10.0-preview.4");
 	headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);
 	if (context.cookie) headers.set("cookie", context.cookie);
 	else headers.delete("cookie");
+	if (context.globalPrivacyControl !== void 0) headers.set(SEC_GPC_HEADER, context.globalPrivacyControl);
+	else headers.delete(SEC_GPC_HEADER);
 	if (context.storefrontOrigin) headers.set(SHOPIFY_STOREFRONT_ORIGIN_HEADER, context.storefrontOrigin);
 	else headers.delete(SHOPIFY_STOREFRONT_ORIGIN_HEADER);
-	if (context.uniqueToken) headers.set(SHOPIFY_UNIQUE_TOKEN_HEADER, context.uniqueToken);
-	if (context.visitToken) headers.set(SHOPIFY_VISIT_TOKEN_HEADER, context.visitToken);
-	if (context.legacyTokens && context.uniqueToken) headers.set(SHOPIFY_STOREFRONT_Y_HEADER, context.uniqueToken);
-	if (context.legacyTokens && context.visitToken) headers.set(SHOPIFY_STOREFRONT_S_HEADER, context.visitToken);
 }
 function getUrlOrigin(url) {
 	if (!url) return void 0;
@@ -131,10 +113,6 @@ function parseCookieHeader(cookieHeader) {
 	}
 	return cookies;
 }
-function isShopifySetCookie(value) {
-	const name = value.match(/^\s*([^=;\s]+)\s*=/)?.[1];
-	return name !== void 0 && SHOPIFY_COOKIES.has(name);
-}
 
 //#endregion
 export { createShopifyRequestContext };

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

@@ -1 +1 @@
-{"version":3,"file":"request-context.mjs","names":[],"sources":["../../../src/core/request-context.ts"],"sourcesContent":["import type {\n  CountryCode as CustomerAccountCountryCode,\n  LanguageCode as CustomerAccountLanguageCode,\n} from \"../graphql/generated/customer-account-api-types\";\nimport type {\n  CountryCode as StorefrontCountryCode,\n  LanguageCode as StorefrontLanguageCode,\n} from \"../graphql/generated/storefront-api-types\";\nimport { STOREFRONT_API_VERSION } from \"./constants\";\nimport {\n  applyPrivateResponseCacheHeaders,\n  CONSENT_MANAGEMENT_HEADER,\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SERVER_TIMING_HEADER,\n  SHOPIFY_STOREFRONT_ORIGIN_HEADER,\n  SHOPIFY_STOREFRONT_S_HEADER,\n  SHOPIFY_STOREFRONT_Y_HEADER,\n  SHOPIFY_UNIQUE_TOKEN_HEADER,\n  SHOPIFY_VISIT_TOKEN_HEADER,\n  STOREFRONT_URL_HEADER,\n} from \"./headers\";\nimport { normalizePathPrefix } from \"./standard-routes/path\";\n\nconst SHOPIFY_ESSENTIAL_COOKIE = \"_shopify_essential\";\nconst SHOPIFY_TRACKING_COOKIES = [\"_shopify_analytics\", \"_shopify_marketing\"];\nconst SHOPIFY_COOKIES = new Set([SHOPIFY_ESSENTIAL_COOKIE, ...SHOPIFY_TRACKING_COOKIES]);\n\ntype StorefrontRequest = Pick<Request, \"headers\"> &\n  Partial<Pick<Request, \"method\" | \"signal\" | \"url\">>;\n\nexport type ShopifyLanguageCode = Extract<StorefrontLanguageCode, CustomerAccountLanguageCode>;\nexport type ShopifyCountryCode = Extract<StorefrontCountryCode, CustomerAccountCountryCode>;\n\nexport type I18nConfig = {\n  language: ShopifyLanguageCode;\n  country: ShopifyCountryCode;\n  /** Optional app route prefix for localized paths, for example \"/es-es\". */\n  pathPrefix?: string;\n};\n\ntype NormalizedI18nConfig<I18n extends I18nConfig = I18nConfig> = Omit<I18n, \"pathPrefix\"> & {\n  pathPrefix: string;\n};\n\ntype ShopifyRequestContextInputBase<I18n extends I18nConfig = I18nConfig> = {\n  request: StorefrontRequest;\n  i18n: I18n;\n};\n\ntype ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp?: never };\n\ntype ShopifyRequestContextWithBuyerIpInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp: string };\n\ntype ShopifyRequestContextBase = {\n  // -- Private fields --\n  /**\n   * Compile-time brand so callers use createShopifyRequestContext().\n   * @internal\n   */\n  readonly __hydrogenShopifyRequestContextBrand: never;\n  /** @internal */\n  cookie?: string;\n  /** @internal */\n  uniqueToken?: string;\n  /** @internal */\n  visitToken?: string;\n  /** @internal */\n  legacyTokens?: boolean;\n  /** @internal */\n  readonly buyerIp?: string;\n  /** @internal */\n  requestGroupId: string;\n  /** @internal */\n  signal?: AbortSignal;\n  /** @internal */\n  url?: string;\n  /** @internal */\n  storefrontOrigin?: string;\n  /**\n   * Apply request-scoped headers required by every Shopify storefront subrequest.\n   * @internal\n   */\n  applyStorefrontRequestHeaders(headers: Headers): void;\n  /**\n   * Capture the first fresh storefront response headers for replay onto the final app response.\n   * @internal\n   */\n  captureSubrequestHeaders(headers: Headers): void;\n  /**\n   * Consume storefront proxy response state for gated replay onto the final app response.\n   * @internal\n   */\n  consumeStorefrontResponseHeaders(headers: Headers): void;\n  /**\n   * Mark the final app response as influenced by private customer state.\n   * @internal\n   */\n  markResponseAsPersonalized(reason: string): void;\n\n  // -- Public fields --\n  i18n: NormalizedI18nConfig;\n  /** Return incoming request headers plus request lifecycle headers for proxy/origin handoff. */\n  getForwardedRequestHeaders(): Headers;\n  /** Apply important response headers for the correct functioning of Hydrogen storefronts. */\n  applyResponseHeaders(headers: Headers): void;\n};\n\nexport type ShopifyRequestContext<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextBase & {\n    i18n: NormalizedI18nConfig<I18n>;\n  };\n\nexport type ShopifyRequestContextWithBuyerIp<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContext<I18n> & { readonly buyerIp: string };\n\ntype Context<I18n extends I18nConfig = I18nConfig> = {\n  cookie?: string;\n  uniqueToken?: string;\n  visitToken?: string;\n  legacyTokens?: boolean;\n  buyerIp?: string;\n  requestGroupId: string;\n  signal?: AbortSignal;\n  url?: string;\n  storefrontOrigin?: string;\n  i18n: NormalizedI18nConfig<I18n>;\n  documentRequest?: boolean;\n};\n\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextWithBuyerIpInput<I18n>,\n): ShopifyRequestContextWithBuyerIp<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInput<I18n>,\n): ShopifyRequestContext<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInputBase<I18n> & { buyerIp?: string },\n): ShopifyRequestContext<I18n> {\n  const { request } = input;\n\n  if (!input.i18n?.country || !input.i18n?.language) {\n    throw new Error(\"i18n with country and language is required for Shopify request contexts.\");\n  }\n\n  if (input.buyerIp !== undefined && !input.buyerIp) {\n    throw new Error(\"buyerIp must be non-empty when provided\");\n  }\n\n  const requestMethod = request.method?.toUpperCase();\n  const i18n = normalizeI18n(input.i18n);\n  const cookieHeader = request.headers.get(\"cookie\") || undefined;\n  const inboundCookies = parseCookieHeader(cookieHeader);\n  const hasEssentialCookie = inboundCookies.has(SHOPIFY_ESSENTIAL_COOKIE);\n  const hasTrackingCookie = SHOPIFY_TRACKING_COOKIES.some((name) => inboundCookies.has(name));\n  const isConsentManagementRequest = request.headers.get(CONSENT_MANAGEMENT_HEADER) === \"1\";\n  const url = request.url ?? request.headers.get(STOREFRONT_URL_HEADER) ?? undefined;\n  const storefrontOrigin = getUrlOrigin(url);\n  const context = {\n    ...(cookieHeader && { cookie: cookieHeader }),\n    i18n,\n    ...(url && { url }),\n    ...(storefrontOrigin && { storefrontOrigin }),\n    ...(input.buyerIp && { buyerIp: input.buyerIp }),\n    requestGroupId:\n      request.headers.get(REQUEST_GROUP_ID_HEADER) ??\n      request.headers.get(\"x-request-id\") ??\n      request.headers.get(\"request-id\") ??\n      crypto.randomUUID(),\n    ...(isDocumentRequest(request) && { documentRequest: true }),\n    ...(request.signal && { signal: request.signal }),\n  } as Context<I18n>;\n\n  let capturedSubrequestHeaders:\n    | {\n        serverTiming: string;\n        setCookie: string[];\n      }\n    | undefined;\n  let personalizedResponseReason: string | undefined;\n\n  const captureSubrequestHeaders = (headers: Headers): void => {\n    // Capture this the first time we get a fresh response to increase the\n    // chance of returning it from the main server response. The main response\n    // needs headers set at send time, while the body can stream later, so this\n    // may not be used if subrequests finish after the main response is sent.\n    capturedSubrequestHeaders ??= {\n      serverTiming: headers.get(SERVER_TIMING_HEADER) ?? \"\",\n      setCookie: headers.getSetCookie(),\n    };\n  };\n\n  if (!hasTrackingCookie) {\n    const legacyUniqueToken = inboundCookies.get(\"_shopify_y\");\n    const legacyVisitToken = inboundCookies.get(\"_shopify_s\");\n    const headerUniqueToken = request.headers.get(SHOPIFY_UNIQUE_TOKEN_HEADER) ?? undefined;\n    const headerVisitToken = request.headers.get(SHOPIFY_VISIT_TOKEN_HEADER) ?? undefined;\n\n    if (legacyUniqueToken || legacyVisitToken) context.legacyTokens = true;\n\n    context.uniqueToken = legacyUniqueToken ?? headerUniqueToken;\n    context.visitToken = legacyVisitToken ?? headerVisitToken;\n  }\n\n  return {\n    ...context,\n    getForwardedRequestHeaders() {\n      const headers = new Headers(request.headers);\n      applyStorefrontRequestHeaders(context, headers);\n      if (context.url) headers.set(STOREFRONT_URL_HEADER, context.url);\n      return headers;\n    },\n    applyStorefrontRequestHeaders(headers) {\n      applyStorefrontRequestHeaders(context, headers);\n    },\n    captureSubrequestHeaders,\n    consumeStorefrontResponseHeaders(headers) {\n      if (headers.has(SERVER_TIMING_HEADER) || headers.getSetCookie().length > 0) {\n        captureSubrequestHeaders(headers);\n      }\n      headers.delete(\"set-cookie\");\n      headers.delete(SERVER_TIMING_HEADER);\n    },\n    markResponseAsPersonalized(reason) {\n      personalizedResponseReason ??= reason;\n    },\n    applyResponseHeaders(headers) {\n      headers.set(\"powered-by\", \"Shopify, Hydrogen\");\n\n      // Documents may be shared or streamed, so they must not carry buyer-specific state.\n      const isDocumentResponse =\n        context.documentRequest || (headers.get(\"content-type\")?.startsWith(\"text/html\") ?? false);\n\n      // Keep GET and HEAD responses cacheable, and fail closed when the request method is unknown.\n      // Cold sessions may only be established by the explicitly marked consent request.\n      const mayReturnShopifyState =\n        requestMethod !== undefined &&\n        requestMethod !== \"GET\" &&\n        requestMethod !== \"HEAD\" &&\n        !isDocumentResponse &&\n        (hasEssentialCookie || isConsentManagementRequest);\n\n      // Replay state captured from fresh SFAPI and proxy responses when allowed.\n      if (capturedSubrequestHeaders && mayReturnShopifyState) {\n        const existingSetCookies = new Set(headers.getSetCookie());\n        for (const value of capturedSubrequestHeaders.setCookie) {\n          if (existingSetCookies.has(value)) continue;\n          headers.append(\"set-cookie\", value);\n          existingSetCookies.add(value);\n        }\n\n        const capturedServerTiming = capturedSubrequestHeaders.serverTiming;\n        const existingServerTiming = headers.get(SERVER_TIMING_HEADER) ?? \"\";\n        const shouldAppendServerTiming =\n          capturedServerTiming !== \"\" &&\n          existingServerTiming !== capturedServerTiming &&\n          !existingServerTiming.startsWith(`${capturedServerTiming}, `) &&\n          !existingServerTiming.endsWith(`, ${capturedServerTiming}`);\n        if (shouldAppendServerTiming) {\n          headers.set(\n            SERVER_TIMING_HEADER,\n            existingServerTiming\n              ? `${existingServerTiming}, ${capturedServerTiming}`\n              : capturedServerTiming,\n          );\n        }\n      }\n\n      // Responses containing buyer-specific or replayed state must not enter shared caches.\n      const returnsCapturedState =\n        mayReturnShopifyState &&\n        Boolean(\n          capturedSubrequestHeaders?.serverTiming || capturedSubrequestHeaders?.setCookie.length,\n        );\n\n      if (\n        personalizedResponseReason ||\n        returnsCapturedState ||\n        headers.getSetCookie().some(isShopifySetCookie)\n      ) {\n        applyPrivateResponseCacheHeaders(headers);\n      }\n    },\n  } as ShopifyRequestContext<I18n>;\n}\n\nfunction normalizeI18n<I18n extends I18nConfig>(i18n: I18n): NormalizedI18nConfig<I18n> {\n  return {\n    ...i18n,\n    pathPrefix: normalizePathPrefix(i18n.pathPrefix),\n  } as NormalizedI18nConfig<I18n>;\n}\n\nfunction applyStorefrontRequestHeaders(context: Context, headers: Headers): void {\n  headers.set(SDK_VARIANT_HEADER, \"hydrogen\");\n  headers.set(SDK_VARIANT_SOURCE_HEADER, \"kit\");\n  headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);\n  headers.set(HYDROGEN_VERSION_HEADER, __HYDROGEN_VERSION__);\n  headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);\n\n  if (context.cookie) headers.set(\"cookie\", context.cookie);\n  else headers.delete(\"cookie\");\n  if (context.storefrontOrigin) {\n    headers.set(SHOPIFY_STOREFRONT_ORIGIN_HEADER, context.storefrontOrigin);\n  } else headers.delete(SHOPIFY_STOREFRONT_ORIGIN_HEADER);\n\n  // Some Storefront API consumers still rely on these headers instead of cookies.\n  if (context.uniqueToken) headers.set(SHOPIFY_UNIQUE_TOKEN_HEADER, context.uniqueToken);\n  if (context.visitToken) headers.set(SHOPIFY_VISIT_TOKEN_HEADER, context.visitToken);\n  if (context.legacyTokens && context.uniqueToken) {\n    headers.set(SHOPIFY_STOREFRONT_Y_HEADER, context.uniqueToken);\n  }\n  if (context.legacyTokens && context.visitToken) {\n    headers.set(SHOPIFY_STOREFRONT_S_HEADER, context.visitToken);\n  }\n}\n\nfunction getUrlOrigin(url: string | undefined): string | undefined {\n  if (!url) return undefined;\n  try {\n    return new URL(url).origin;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction isDocumentRequest(request: StorefrontRequest): boolean {\n  if (request.method && request.method !== \"GET\" && request.method !== \"HEAD\") return false;\n\n  const destination = request.headers.get(\"sec-fetch-dest\");\n  if (destination === \"document\") return true;\n\n  return request.headers.get(\"accept\")?.includes(\"text/html\") ?? false;\n}\n\nfunction parseCookieHeader(cookieHeader: string | undefined): Map<string, string> {\n  const cookies = new Map<string, string>();\n  if (!cookieHeader) return cookies;\n\n  for (const cookie of cookieHeader.split(\";\")) {\n    const separator = cookie.indexOf(\"=\");\n    if (separator < 0) continue;\n\n    const name = cookie.slice(0, separator).trim();\n    if (!cookies.has(name)) cookies.set(name, cookie.slice(separator + 1));\n  }\n\n  return cookies;\n}\n\nfunction isShopifySetCookie(value: string): boolean {\n  const name = value.match(/^\\s*([^=;\\s]+)\\s*=/)?.[1];\n  return name !== undefined && SHOPIFY_COOKIES.has(name);\n}\n"],"mappings":"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"}
+{"version":3,"file":"request-context.mjs","names":[],"sources":["../../../src/core/request-context.ts"],"sourcesContent":["import type {\n  CountryCode as CustomerAccountCountryCode,\n  LanguageCode as CustomerAccountLanguageCode,\n} from \"../graphql/generated/customer-account-api-types\";\nimport type {\n  CountryCode as StorefrontCountryCode,\n  LanguageCode as StorefrontLanguageCode,\n} from \"../graphql/generated/storefront-api-types\";\nimport { STOREFRONT_API_VERSION } from \"./constants\";\nimport {\n  applyPrivateResponseCacheHeaders,\n  CONSENT_MANAGEMENT_HEADER,\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SEC_GPC_HEADER,\n  SHOPIFY_STOREFRONT_ORIGIN_HEADER,\n  STOREFRONT_URL_HEADER,\n} from \"./headers\";\nimport { normalizePathPrefix } from \"./standard-routes/path\";\n\nconst SHOPIFY_ESSENTIAL_COOKIE = \"_shopify_essential\";\n\ntype StorefrontRequest = Pick<Request, \"headers\"> &\n  Partial<Pick<Request, \"method\" | \"signal\" | \"url\">>;\n\nexport type ShopifyLanguageCode = Extract<StorefrontLanguageCode, CustomerAccountLanguageCode>;\nexport type ShopifyCountryCode = Extract<StorefrontCountryCode, CustomerAccountCountryCode>;\n\nexport type I18nConfig = {\n  language: ShopifyLanguageCode;\n  country: ShopifyCountryCode;\n  /** Optional app route prefix for localized paths, for example \"/es-es\". */\n  pathPrefix?: string;\n};\n\ntype NormalizedI18nConfig<I18n extends I18nConfig = I18nConfig> = Omit<I18n, \"pathPrefix\"> & {\n  pathPrefix: string;\n};\n\ntype ShopifyRequestContextInputBase<I18n extends I18nConfig = I18nConfig> = {\n  request: StorefrontRequest;\n  i18n: I18n;\n};\n\ntype ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp?: never };\n\ntype ShopifyRequestContextWithBuyerIpInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp: string };\n\ntype ShopifyRequestContextBase = {\n  // -- Private fields --\n  /**\n   * Compile-time brand so callers use createShopifyRequestContext().\n   * @internal\n   */\n  readonly __hydrogenShopifyRequestContextBrand: never;\n  /** @internal */\n  cookie?: string;\n  /** @internal */\n  readonly buyerIp?: string;\n  /** @internal */\n  requestGroupId: string;\n  /** @internal */\n  signal?: AbortSignal;\n  /** @internal */\n  url?: string;\n  /** @internal */\n  storefrontOrigin?: string;\n  /**\n   * Apply request-scoped headers required by every Shopify storefront subrequest.\n   * @internal\n   */\n  applyStorefrontRequestHeaders(headers: Headers): void;\n  /**\n   * Capture cookies from the first fresh storefront response that sets them for replay.\n   * @internal\n   */\n  captureSubrequestHeaders(headers: Headers): void;\n  /**\n   * Consume storefront proxy cookies for gated replay onto the final app response.\n   * @internal\n   */\n  consumeStorefrontResponseHeaders(headers: Headers): void;\n  /**\n   * Mark the final app response as influenced by private customer state.\n   * @internal\n   */\n  markResponseAsPersonalized(reason: string): void;\n  /**\n   * Mark this request as a sanctioned session-establishing endpoint (like the\n   * consent flow), permitting Shopify state to return even on a cold session.\n   * @internal\n   */\n  markResponseAsSessionEstablishing(reason: string): void;\n\n  // -- Public fields --\n  i18n: NormalizedI18nConfig;\n  /** Return incoming request headers plus request lifecycle headers for proxy/origin handoff. */\n  getForwardedRequestHeaders(): Headers;\n  /** Apply important response headers for the correct functioning of Hydrogen storefronts. */\n  applyResponseHeaders(headers: Headers): void;\n};\n\nexport type ShopifyRequestContext<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextBase & {\n    i18n: NormalizedI18nConfig<I18n>;\n  };\n\nexport type ShopifyRequestContextWithBuyerIp<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContext<I18n> & { readonly buyerIp: string };\n\ntype Context<I18n extends I18nConfig = I18nConfig> = {\n  cookie?: string;\n  globalPrivacyControl?: string;\n  buyerIp?: string;\n  requestGroupId: string;\n  signal?: AbortSignal;\n  url?: string;\n  storefrontOrigin?: string;\n  i18n: NormalizedI18nConfig<I18n>;\n  documentRequest?: boolean;\n};\n\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextWithBuyerIpInput<I18n>,\n): ShopifyRequestContextWithBuyerIp<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInput<I18n>,\n): ShopifyRequestContext<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInputBase<I18n> & { buyerIp?: string },\n): ShopifyRequestContext<I18n> {\n  const { request } = input;\n\n  if (!input.i18n?.country || !input.i18n?.language) {\n    throw new Error(\"i18n with country and language is required for Shopify request contexts.\");\n  }\n\n  if (input.buyerIp !== undefined && !input.buyerIp) {\n    throw new Error(\"buyerIp must be non-empty when provided\");\n  }\n\n  const requestMethod = request.method?.toUpperCase();\n  const i18n = normalizeI18n(input.i18n);\n  const cookieHeader = request.headers.get(\"cookie\") || undefined;\n  const inboundCookies = parseCookieHeader(cookieHeader);\n  const hasEssentialCookie = inboundCookies.has(SHOPIFY_ESSENTIAL_COOKIE);\n  const isConsentManagementRequest = request.headers.get(CONSENT_MANAGEMENT_HEADER) === \"1\";\n  const url = request.url ?? request.headers.get(STOREFRONT_URL_HEADER) ?? undefined;\n  const storefrontOrigin = getUrlOrigin(url);\n  const context = {\n    ...(cookieHeader && { cookie: cookieHeader }),\n    globalPrivacyControl: request.headers.get(SEC_GPC_HEADER) ?? undefined,\n    i18n,\n    ...(url && { url }),\n    ...(storefrontOrigin && { storefrontOrigin }),\n    ...(input.buyerIp && { buyerIp: input.buyerIp }),\n    requestGroupId:\n      request.headers.get(REQUEST_GROUP_ID_HEADER) ??\n      request.headers.get(\"x-request-id\") ??\n      request.headers.get(\"request-id\") ??\n      crypto.randomUUID(),\n    ...(isDocumentRequest(request) && { documentRequest: true }),\n    ...(request.signal && { signal: request.signal }),\n  } as Context<I18n>;\n\n  let capturedCookies: string[] | undefined;\n  let personalizedResponseReason: string | undefined;\n  let sessionEstablishingReason: string | undefined;\n\n  const captureSubrequestHeaders = (headers: Headers): void => {\n    // Capture the first fresh response cookies to increase the\n    // chance of returning them from the main server response. The main response\n    // needs headers set at send time, while the body can stream later, so this\n    // may not be used if subrequests finish after the main response is sent.\n    const cookies = headers.getSetCookie();\n    if (cookies.length > 0) capturedCookies ??= cookies;\n  };\n\n  return {\n    ...context,\n    getForwardedRequestHeaders() {\n      const headers = new Headers(request.headers);\n      applyStorefrontRequestHeaders(context, headers);\n      if (context.url) headers.set(STOREFRONT_URL_HEADER, context.url);\n      return headers;\n    },\n    applyStorefrontRequestHeaders(headers) {\n      applyStorefrontRequestHeaders(context, headers);\n    },\n    captureSubrequestHeaders,\n    consumeStorefrontResponseHeaders(headers) {\n      captureSubrequestHeaders(headers);\n      headers.delete(\"set-cookie\");\n    },\n    markResponseAsPersonalized(reason) {\n      personalizedResponseReason ??= reason;\n    },\n    markResponseAsSessionEstablishing(reason) {\n      sessionEstablishingReason ??= reason;\n    },\n    applyResponseHeaders(headers) {\n      headers.set(\"powered-by\", \"Shopify, Hydrogen\");\n\n      // Documents may be shared or streamed, so they must not carry buyer-specific state.\n      const isDocumentResponse =\n        context.documentRequest || (headers.get(\"content-type\")?.startsWith(\"text/html\") ?? false);\n\n      // Keep GET and HEAD responses cacheable, and fail closed when the request method is unknown.\n      // Cold sessions may only be established by the explicitly marked consent request.\n      const mayReturnShopifyState =\n        requestMethod !== undefined &&\n        requestMethod !== \"GET\" &&\n        requestMethod !== \"HEAD\" &&\n        !isDocumentResponse &&\n        (hasEssentialCookie ||\n          isConsentManagementRequest ||\n          sessionEstablishingReason !== undefined);\n\n      // Replay cookies captured from fresh SFAPI and proxy responses when allowed.\n      if (capturedCookies && mayReturnShopifyState) {\n        const existingSetCookies = new Set(headers.getSetCookie());\n        for (const value of capturedCookies) {\n          if (existingSetCookies.has(value)) continue;\n          headers.append(\"set-cookie\", value);\n          existingSetCookies.add(value);\n        }\n      }\n\n      // Consent/session responses can contain private state in the body without setting cookies.\n      if (\n        personalizedResponseReason ||\n        isConsentManagementRequest ||\n        sessionEstablishingReason !== undefined ||\n        headers.has(\"set-cookie\")\n      ) {\n        applyPrivateResponseCacheHeaders(headers);\n      }\n    },\n  } as ShopifyRequestContext<I18n>;\n}\n\nfunction normalizeI18n<I18n extends I18nConfig>(i18n: I18n): NormalizedI18nConfig<I18n> {\n  return {\n    ...i18n,\n    pathPrefix: normalizePathPrefix(i18n.pathPrefix),\n  } as NormalizedI18nConfig<I18n>;\n}\n\nfunction applyStorefrontRequestHeaders(context: Context, headers: Headers): void {\n  headers.set(SDK_VARIANT_HEADER, \"hydrogen\");\n  headers.set(SDK_VARIANT_SOURCE_HEADER, \"kit\");\n  headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);\n  headers.set(HYDROGEN_VERSION_HEADER, __HYDROGEN_VERSION__);\n  headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);\n\n  if (context.cookie) headers.set(\"cookie\", context.cookie);\n  else headers.delete(\"cookie\");\n  if (context.globalPrivacyControl !== undefined) {\n    headers.set(SEC_GPC_HEADER, context.globalPrivacyControl);\n  } else headers.delete(SEC_GPC_HEADER);\n  if (context.storefrontOrigin) {\n    headers.set(SHOPIFY_STOREFRONT_ORIGIN_HEADER, context.storefrontOrigin);\n  } else headers.delete(SHOPIFY_STOREFRONT_ORIGIN_HEADER);\n}\n\nfunction getUrlOrigin(url: string | undefined): string | undefined {\n  if (!url) return undefined;\n  try {\n    return new URL(url).origin;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction isDocumentRequest(request: StorefrontRequest): boolean {\n  if (request.method && request.method !== \"GET\" && request.method !== \"HEAD\") return false;\n\n  const destination = request.headers.get(\"sec-fetch-dest\");\n  if (destination === \"document\") return true;\n\n  return request.headers.get(\"accept\")?.includes(\"text/html\") ?? false;\n}\n\nfunction parseCookieHeader(cookieHeader: string | undefined): Map<string, string> {\n  const cookies = new Map<string, string>();\n  if (!cookieHeader) return cookies;\n\n  for (const cookie of cookieHeader.split(\";\")) {\n    const separator = cookie.indexOf(\"=\");\n    if (separator < 0) continue;\n\n    const name = cookie.slice(0, separator).trim();\n    if (!cookies.has(name)) cookies.set(name, cookie.slice(separator + 1));\n  }\n\n  return cookies;\n}\n"],"mappings":"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"}

package/dist/development/core/request-routing/handle-shopify-routes.mjs

@@ -2,9 +2,10 @@ import { safeApplyResponseHeaders } from "./safe-apply-response-headers.mjs";
 import { handleProductVariantId } from "../product/accept-variant-id.mjs";
 import { handleAjaxApi } from "./interceptors/ajax-api.mjs";
 import { handleShopifyApiProxy } from "./interceptors/api-proxy.mjs";
-import { handleCheckoutRedirect } from "./interceptors/checkout.mjs";
+import { handleBuyPermalinkRedirect, handleCheckoutRedirect } from "./interceptors/checkout.mjs";
 import { handleMcpProxy } from "./interceptors/mcp-proxy.mjs";
 import { handleSfapiProxy } from "./interceptors/sfapi-proxy.mjs";
+import { handleUcpMcpProxy } from "./interceptors/ucp-mcp-proxy.mjs";
 import { handleWellKnownProxy } from "./interceptors/well-known.mjs";
 import { handleShopifyRouteHandlers } from "./registered-routes.mjs";
 
@@ -14,8 +15,10 @@ const SHOPIFY_ROUTE_INTERCEPTORS = [
 	handleSfapiProxy,
 	handleProductVariantId,
 	handleShopifyRouteHandlers,
+	handleBuyPermalinkRedirect,
 	handleCheckoutRedirect,
 	handleWellKnownProxy,
+	handleUcpMcpProxy,
 	handleMcpProxy,
 	handleAjaxApi
 ];

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

@@ -1 +1 @@
-{"version":3,"file":"handle-shopify-routes.mjs","names":[],"sources":["../../../../src/core/request-routing/handle-shopify-routes.ts"],"sourcesContent":["import { handleProductVariantId } from \"../product/accept-variant-id\";\nimport { handleAjaxApi } from \"./interceptors/ajax-api\";\nimport { handleShopifyApiProxy } from \"./interceptors/api-proxy\";\nimport { handleCheckoutRedirect } from \"./interceptors/checkout\";\nimport { handleMcpProxy } from \"./interceptors/mcp-proxy\";\nimport { handleSfapiProxy } from \"./interceptors/sfapi-proxy\";\nimport { handleWellKnownProxy } from \"./interceptors/well-known\";\nimport { handleShopifyRouteHandlers } from \"./registered-routes\";\nimport type { HydrogenRouteHandler, HydrogenRouteInterceptor } from \"./route-types\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst SHOPIFY_ROUTE_INTERCEPTORS = [\n  handleShopifyApiProxy,\n  handleSfapiProxy,\n  handleProductVariantId,\n  handleShopifyRouteHandlers,\n  handleCheckoutRedirect,\n  handleWellKnownProxy,\n  handleMcpProxy,\n  handleAjaxApi,\n] satisfies readonly HydrogenRouteInterceptor[];\n\n/**\n * Matches a request against Shopify standard routes and any registered handler\n * groups, returning a raw `Response` (redirect or JSON) when one matches, or\n * `null` when none do. Use it as the first step of request handling, before\n * framework routing. Matched responses already include request-context\n * response headers.\n */\nexport const handleShopifyRoutes: HydrogenRouteHandler = (options) => {\n  if (options.requestContext !== options.storefrontClient.requestContext) {\n    throw new Error(\n      \"handleShopifyRoutes must receive the same requestContext used by storefrontClient.\",\n    );\n  }\n\n  const url = new URL(options.request.url);\n\n  for (const interceptor of SHOPIFY_ROUTE_INTERCEPTORS) {\n    const responsePromise = interceptor(url, options);\n    if (!responsePromise) continue;\n\n    return responsePromise.then((response) =>\n      safeApplyResponseHeaders(response, options.requestContext),\n    );\n  }\n\n  return null;\n};\n"],"mappings":";;;;;;;;;;;AAWA,MAAM,6BAA6B;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,uBAA6C,YAAY;AACpE,KAAI,QAAQ,mBAAmB,QAAQ,iBAAiB,eACtD,OAAM,IAAI,MACR,qFACD;CAGH,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,IAAI;AAExC,MAAK,MAAM,eAAe,4BAA4B;EACpD,MAAM,kBAAkB,YAAY,KAAK,QAAQ;AACjD,MAAI,CAAC,gBAAiB;AAEtB,SAAO,gBAAgB,MAAM,aAC3B,yBAAyB,UAAU,QAAQ,eAAe,CAC3D;;AAGH,QAAO"}
+{"version":3,"file":"handle-shopify-routes.mjs","names":[],"sources":["../../../../src/core/request-routing/handle-shopify-routes.ts"],"sourcesContent":["import { handleProductVariantId } from \"../product/accept-variant-id\";\nimport { handleAjaxApi } from \"./interceptors/ajax-api\";\nimport { handleShopifyApiProxy } from \"./interceptors/api-proxy\";\nimport { handleBuyPermalinkRedirect, handleCheckoutRedirect } from \"./interceptors/checkout\";\nimport { handleMcpProxy } from \"./interceptors/mcp-proxy\";\nimport { handleSfapiProxy } from \"./interceptors/sfapi-proxy\";\nimport { handleUcpMcpProxy } from \"./interceptors/ucp-mcp-proxy\";\nimport { handleWellKnownProxy } from \"./interceptors/well-known\";\nimport { handleShopifyRouteHandlers } from \"./registered-routes\";\nimport type { HydrogenRouteHandler, HydrogenRouteInterceptor } from \"./route-types\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst SHOPIFY_ROUTE_INTERCEPTORS = [\n  handleShopifyApiProxy,\n  handleSfapiProxy,\n  handleProductVariantId,\n  handleShopifyRouteHandlers,\n  handleBuyPermalinkRedirect,\n  handleCheckoutRedirect,\n  handleWellKnownProxy,\n  handleUcpMcpProxy,\n  handleMcpProxy,\n  handleAjaxApi,\n] satisfies readonly HydrogenRouteInterceptor[];\n\n/**\n * Matches a request against Shopify standard routes and any registered handler\n * groups, returning a raw `Response` (redirect or JSON) when one matches, or\n * `null` when none do. Use it as the first step of request handling, before\n * framework routing. Matched responses already include request-context\n * response headers.\n */\nexport const handleShopifyRoutes: HydrogenRouteHandler = (options) => {\n  if (options.requestContext !== options.storefrontClient.requestContext) {\n    throw new Error(\n      \"handleShopifyRoutes must receive the same requestContext used by storefrontClient.\",\n    );\n  }\n\n  const url = new URL(options.request.url);\n\n  for (const interceptor of SHOPIFY_ROUTE_INTERCEPTORS) {\n    const responsePromise = interceptor(url, options);\n    if (!responsePromise) continue;\n\n    return responsePromise.then((response) =>\n      safeApplyResponseHeaders(response, options.requestContext),\n    );\n  }\n\n  return null;\n};\n"],"mappings":";;;;;;;;;;;;AAYA,MAAM,6BAA6B;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,uBAA6C,YAAY;AACpE,KAAI,QAAQ,mBAAmB,QAAQ,iBAAiB,eACtD,OAAM,IAAI,MACR,qFACD;CAGH,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,IAAI;AAExC,MAAK,MAAM,eAAe,4BAA4B;EACpD,MAAM,kBAAkB,YAAY,KAAK,QAAQ;AACjD,MAAI,CAAC,gBAAiB;AAEtB,SAAO,gBAAgB,MAAM,aAC3B,yBAAyB,UAAU,QAAQ,eAAe,CAC3D;;AAGH,QAAO"}

package/dist/development/core/request-routing/interceptors/ajax-api.mjs

@@ -1,5 +1,5 @@
-import { AJAX_API_REQUEST_HEADER_ALLOWLIST } from "../../headers.mjs";
 import { AJAX_CART_RE } from "../../url.mjs";
+import { AJAX_API_REQUEST_HEADER_ALLOWLIST } from "../../headers.mjs";
 import { createProxyInterceptor } from "./proxy.mjs";
 
 //#region src/core/request-routing/interceptors/ajax-api.ts

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

@@ -1,5 +1,5 @@
-import { PROXY_REQUEST_HEADER_DENYLIST } from "../../headers.mjs";
 import { SHOPIFY_API_PROXY_PREFIX, SHOPIFY_API_PROXY_RE } from "../../url.mjs";
+import { PROXY_REQUEST_HEADER_DENYLIST } from "../../headers.mjs";
 import { createProxyInterceptor } from "./proxy.mjs";
 import { rewriteShopifyJsPathname } from "./ajax-api.mjs";
 

package/dist/development/core/request-routing/interceptors/checkout.mjs

@@ -1,10 +1,10 @@
 import { getLogger } from "../../logging/logging.mjs";
-import { CHECKOUT_RE, isHydrogenServerHandoffPath } from "../../url.mjs";
+import { BUY_PERMALINK_RE, CHECKOUT_RE, isHydrogenServerHandoffPath } from "../../url.mjs";
 import { getCart, getCartId } from "../../cart/get-cart.mjs";
 
 //#region src/core/request-routing/interceptors/checkout.ts
 const log = getLogger("checkout");
-const MOCK_SHOP_CART_PERMALINK_ORIGIN = "https://demostore.mock.shop";
+const MOCK_SHOP_PERMALINK_ORIGIN = "https://demostore.mock.shop";
 const handleCheckoutRedirect = (url, { request, storefrontClient }) => {
 	if (!isHydrogenServerHandoffPath(url.pathname)) return null;
 	if (request.method !== "GET" && request.method !== "HEAD") return Promise.resolve(new Response("Method Not Allowed", { status: 405 }));
@@ -26,6 +26,19 @@ const handleCheckoutRedirect = (url, { request, storefrontClient }) => {
 		});
 	});
 };
+const handleBuyPermalinkRedirect = (url, { request, storefrontClient }) => {
+	if (!BUY_PERMALINK_RE.test(url.pathname)) return null;
+	if (request.method !== "GET") return Promise.resolve(new Response("Method Not Allowed", { status: 405 }));
+	const location = `${getPermalinkOrigin(storefrontClient.storeUrl)}${url.pathname}${url.search}`;
+	return Promise.resolve(new Response(null, {
+		status: 303,
+		headers: {
+			location,
+			"cache-control": "no-store",
+			"referrer-policy": "no-referrer"
+		}
+	}));
+};
 async function getCheckoutRedirectUrl(request, storefrontClient) {
 	const cartId = getCartId(request);
 	if (!cartId) return new URL("/", request.url);
@@ -34,7 +47,7 @@ async function getCheckoutRedirectUrl(request, storefrontClient) {
 }
 async function getCartRedirectUrl(request, storefrontClient) {
 	const sourceUrl = new URL(request.url);
-	const redirectUrl = new URL(sourceUrl.pathname, getCartPermalinkOrigin(storefrontClient.storeUrl));
+	const redirectUrl = new URL(sourceUrl.pathname, getPermalinkOrigin(storefrontClient.storeUrl));
 	const cartId = getCartId(request);
 	if (!cartId) return redirectUrl;
 	try {
@@ -45,14 +58,17 @@ async function getCartRedirectUrl(request, storefrontClient) {
 	}
 	return redirectUrl;
 }
-function getCartPermalinkOrigin(storeUrl) {
+function getPermalinkOrigin(storeUrl) {
 	const url = new URL(storeUrl);
-	return url.hostname === "mock.shop" ? MOCK_SHOP_CART_PERMALINK_ORIGIN : url.origin;
+	return isMockShopHost(url.hostname) ? MOCK_SHOP_PERMALINK_ORIGIN : url.origin;
+}
+function isMockShopHost(hostname) {
+	return hostname === "mock.shop" || hostname.endsWith(".mock.shop");
 }
 function mergeSearchParams(target, source) {
 	for (const [key, value] of source) if (!target.searchParams.has(key)) target.searchParams.append(key, value);
 }
 
 //#endregion
-export { handleCheckoutRedirect };
+export { handleBuyPermalinkRedirect, handleCheckoutRedirect };
 //# sourceMappingURL=checkout.mjs.map