@vtex/faststore 0.0.7 → 0.0.10

package/dist/sdk/seo/page-alternates.d.ts

@@ -0,0 +1,57 @@
+import { CatalogRouteAlternatesQuery } from "../generated/graphql.js";
+//#region src/sdk/seo/page-alternates.d.ts
+export type AlternateBinding = {
+  bindingId: string;
+  locale: string;
+};
+export type RouteVariant = NonNullable<CatalogRouteAlternatesQuery['catalogRoute']>['variants'][number];
+/** Structurally assignable to Next.js `Metadata['alternates']`. */
+export type PageAlternates = {
+  canonical: string;
+  /** BCP 47 tag or `x-default` -> absolute URL. */
+  languages?: Record<string, string>;
+};
+export type RouteParams = Readonly<Record<string, string | string[] | undefined>>;
+export type BuildPageAlternatesOptions = {
+  bindingId: string;
+  defaultBindingId: string;
+  /** Every declared binding, in authoring order. */
+  bindings: readonly AlternateBinding[];
+  /** Decoded logical path of the request. */
+  selfPath: string;
+  /** Binding id -> decoded logical path, for the cluster members only. `null` means no cluster source. */
+  clusterPaths: Readonly<Record<string, string>> | null;
+  buildUrl: (bindingId: string, logicalPath: string) => string;
+};
+/**
+ * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the
+ * package tests validate it against the Storefront API schema.
+ */
+export declare const CATALOG_ROUTE_ALTERNATES_QUERY: import("@graphql-typed-document-node/core").TypedDocumentNode<CatalogRouteAlternatesQuery, {
+  path: string;
+}>;
+/**
+ * The canonical URL plus, when a reciprocal cluster exists, `languages`. A cluster needs two members
+ * and must include the rendered binding: search engines ignore a set that does not reference itself.
+ */
+export declare function buildPageAlternates({ bindingId, defaultBindingId, bindings, selfPath, clusterPaths, buildUrl }: BuildPageAlternatesOptions): PageAlternates;
+/**
+ * The logical path a route pattern names under these params, which arrive decoded
+ * (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;
+ * empty -> `'/'`.
+ * Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an
+ * encoded dot segment (`%2E%2E`) stays an inert literal segment.
+ */
+export declare function routeLogicalPath(route: string, params: RouteParams): string;
+/**
+ * Binding id -> variant path for the bindings whose locale a confirmed variant matches. Never
+ * rejects: a thrown loader, an `error`, a missing or `null` `catalogRoute`, or no matching variant
+ * all resolve to `null`, so a catalog lookup can never fail the page it describes. A thrown loader
+ * or an `error` is logged by code or error name only, never with the path or the upstream message.
+ */
+export declare function catalogClusterPaths(bindings: readonly AlternateBinding[], load: () => Promise<{
+  data: unknown;
+  error?: unknown;
+}>): Promise<Record<string, string> | null>;
+//#endregion
+//# sourceMappingURL=page-alternates.d.ts.map

package/dist/sdk/seo/page-alternates.js

@@ -0,0 +1,127 @@
+import { graphql } from "../generated/gql.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { CombinedGraphQLErrors } from "@apollo/client/errors";
+//#region src/sdk/seo/page-alternates.ts
+/**
+* The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the
+* package tests validate it against the Storefront API schema.
+*/
+const CATALOG_ROUTE_ALTERNATES_QUERY = graphql(`
+  query CatalogRouteAlternates($path: String!) {
+    catalogRoute(input: { path: $path }) {
+      variants {
+        locale
+        path
+      }
+    }
+  }
+`);
+/** Encodes each segment and keeps `/` literal, so a decoded path is encoded exactly once. */
+function encodePath(path) {
+	return path.split("/").map(encodeURIComponent).join("/");
+}
+/**
+* One binding per locale: `hreflang` maps a tag to a single URL. The default binding represents a
+* locale it declares; otherwise the first binding declaring it does.
+*/
+function representatives(bindings, defaultBindingId) {
+	const byLocale = /* @__PURE__ */ new Map();
+	for (const binding of bindings) {
+		const key = binding.locale.toLowerCase();
+		if (!byLocale.get(key) || binding.bindingId === defaultBindingId) byLocale.set(key, binding);
+	}
+	return bindings.filter((binding) => byLocale.get(binding.locale.toLowerCase()) === binding);
+}
+/**
+* The canonical URL plus, when a reciprocal cluster exists, `languages`. A cluster needs two members
+* and must include the rendered binding: search engines ignore a set that does not reference itself.
+*/
+function buildPageAlternates({ bindingId, defaultBindingId, bindings, selfPath, clusterPaths, buildUrl }) {
+	const url = (id, path) => buildUrl(id, encodePath(path));
+	const pathOf = (id) => clusterPaths && Object.hasOwn(clusterPaths, id) ? clusterPaths[id] : void 0;
+	const canonical = url(bindingId, pathOf(bindingId) ?? selfPath);
+	const members = representatives(bindings, defaultBindingId).flatMap((binding) => {
+		const path = pathOf(binding.bindingId);
+		return path === void 0 ? [] : [{
+			...binding,
+			href: url(binding.bindingId, path)
+		}];
+	});
+	if (members.length < 2 || !members.some((member) => member.bindingId === bindingId)) return { canonical };
+	const languages = {};
+	for (const member of members) languages[member.locale] = member.href;
+	const defaultMember = members.find((member) => member.bindingId === defaultBindingId);
+	if (defaultMember) languages["x-default"] = defaultMember.href;
+	return {
+		canonical,
+		languages
+	};
+}
+/** `.` and `..` would make the URL a crawler resolves differ from the page that states it. */
+function isPathSegment(segment) {
+	return segment !== "" && segment !== "." && segment !== "..";
+}
+/**
+* The logical path a route pattern names under these params, which arrive decoded
+* (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;
+* empty -> `'/'`.
+* Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an
+* encoded dot segment (`%2E%2E`) stays an inert literal segment.
+*/
+function routeLogicalPath(route, params) {
+	return `/${route.split("/").filter(Boolean).flatMap((segment) => {
+		const dynamic = /^\[{1,2}(?:\.\.\.)?([^\]]+)\]{1,2}$/.exec(segment);
+		if (!dynamic) return [segment];
+		return [params[dynamic[1]] ?? []].flat();
+	}).filter(isPathSegment).join("/")}`;
+}
+function readVariants(data) {
+	const variants = data?.catalogRoute?.variants;
+	if (!Array.isArray(variants)) return [];
+	return variants.filter((variant) => typeof variant?.locale === "string" && typeof variant?.path === "string");
+}
+/** Binding id -> confirmed variant path, matching BCP 47 tags case-insensitively and nothing looser. */
+function variantPathsByBinding(bindings, variants) {
+	const paths = {};
+	for (const binding of bindings) {
+		const locale = binding.locale.toLowerCase();
+		const variant = variants.find((candidate) => candidate.locale.toLowerCase() === locale);
+		if (variant) paths[binding.bindingId] = variant.path;
+	}
+	return paths;
+}
+/**
+* Why a lookup degraded, safe to log: the GraphQL error code, else the allow-listed error name. `null`
+* for `BAD_USER_INPUT`, which a path `catalogRoute` cannot parse (a slug with a dot) always answers.
+*/
+function degradedReason(error) {
+	if (!CombinedGraphQLErrors.is(error)) return loggableErrorName(error);
+	const codes = error.errors.map(({ extensions }) => extensions?.code);
+	if (codes.length > 0 && codes.every((candidate) => candidate === "BAD_USER_INPUT")) return null;
+	return codes.find((candidate) => typeof candidate === "string" && candidate !== "BAD_USER_INPUT") ?? "GRAPHQL_ERROR";
+}
+function warnDegraded(error) {
+	const reason = degradedReason(error);
+	if (reason) console.warn("[seo.catalogClusterPaths] catalogRoute lookup degraded to no cluster", reason);
+	return null;
+}
+/**
+* Binding id -> variant path for the bindings whose locale a confirmed variant matches. Never
+* rejects: a thrown loader, an `error`, a missing or `null` `catalogRoute`, or no matching variant
+* all resolve to `null`, so a catalog lookup can never fail the page it describes. A thrown loader
+* or an `error` is logged by code or error name only, never with the path or the upstream message.
+*/
+async function catalogClusterPaths(bindings, load) {
+	try {
+		const { data, error } = await load();
+		if (error) return warnDegraded(error);
+		const paths = variantPathsByBinding(bindings, readVariants(data));
+		return Object.keys(paths).length > 0 ? paths : null;
+	} catch (error) {
+		return warnDegraded(error);
+	}
+}
+//#endregion
+export { CATALOG_ROUTE_ALTERNATES_QUERY, buildPageAlternates, catalogClusterPaths, encodePath, routeLogicalPath };
+
+//# sourceMappingURL=page-alternates.js.map

package/dist/sdk/seo/page-alternates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-alternates.js","names":[],"sources":["../../../src/sdk/seo/page-alternates.ts"],"sourcesContent":["import { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { graphql } from '../generated/gql.js';\nimport type { CatalogRouteAlternatesQuery } from '../generated/graphql.js';\n\nexport type AlternateBinding = { bindingId: string; locale: string };\n\nexport type RouteVariant = NonNullable<CatalogRouteAlternatesQuery['catalogRoute']>['variants'][number];\n\n/** Structurally assignable to Next.js `Metadata['alternates']`. */\nexport type PageAlternates = {\n  canonical: string;\n  /** BCP 47 tag or `x-default` -> absolute URL. */\n  languages?: Record<string, string>;\n};\n\nexport type RouteParams = Readonly<Record<string, string | string[] | undefined>>;\n\nexport type BuildPageAlternatesOptions = {\n  bindingId: string;\n  defaultBindingId: string;\n  /** Every declared binding, in authoring order. */\n  bindings: readonly AlternateBinding[];\n  /** Decoded logical path of the request. */\n  selfPath: string;\n  /** Binding id -> decoded logical path, for the cluster members only. `null` means no cluster source. */\n  clusterPaths: Readonly<Record<string, string>> | null;\n  buildUrl: (bindingId: string, logicalPath: string) => string;\n};\n\n/**\n * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the\n * package tests validate it against the Storefront API schema.\n */\nexport const CATALOG_ROUTE_ALTERNATES_QUERY = graphql(`\n  query CatalogRouteAlternates($path: String!) {\n    catalogRoute(input: { path: $path }) {\n      variants {\n        locale\n        path\n      }\n    }\n  }\n`);\n\n/** Encodes each segment and keeps `/` literal, so a decoded path is encoded exactly once. */\nexport function encodePath(path: string): string {\n  return path.split('/').map(encodeURIComponent).join('/');\n}\n\n/**\n * One binding per locale: `hreflang` maps a tag to a single URL. The default binding represents a\n * locale it declares; otherwise the first binding declaring it does.\n */\nfunction representatives(bindings: readonly AlternateBinding[], defaultBindingId: string): AlternateBinding[] {\n  const byLocale = new Map<string, AlternateBinding>();\n  for (const binding of bindings) {\n    const key = binding.locale.toLowerCase();\n    const current = byLocale.get(key);\n    if (!current || binding.bindingId === defaultBindingId) byLocale.set(key, binding);\n  }\n  return bindings.filter((binding) => byLocale.get(binding.locale.toLowerCase()) === binding);\n}\n\n/**\n * The canonical URL plus, when a reciprocal cluster exists, `languages`. A cluster needs two members\n * and must include the rendered binding: search engines ignore a set that does not reference itself.\n */\nexport function buildPageAlternates({\n  bindingId,\n  defaultBindingId,\n  bindings,\n  selfPath,\n  clusterPaths,\n  buildUrl,\n}: BuildPageAlternatesOptions): PageAlternates {\n  const url = (id: string, path: string) => buildUrl(id, encodePath(path));\n  const pathOf = (id: string) => (clusterPaths && Object.hasOwn(clusterPaths, id) ? clusterPaths[id] : undefined);\n  const canonical = url(bindingId, pathOf(bindingId) ?? selfPath);\n\n  const members = representatives(bindings, defaultBindingId).flatMap((binding) => {\n    const path = pathOf(binding.bindingId);\n    return path === undefined ? [] : [{ ...binding, href: url(binding.bindingId, path) }];\n  });\n  if (members.length < 2 || !members.some((member) => member.bindingId === bindingId)) return { canonical };\n\n  const languages: Record<string, string> = {};\n  for (const member of members) languages[member.locale] = member.href;\n  const defaultMember = members.find((member) => member.bindingId === defaultBindingId);\n  if (defaultMember) languages['x-default'] = defaultMember.href;\n  return { canonical, languages };\n}\n\n/** `.` and `..` would make the URL a crawler resolves differ from the page that states it. */\nfunction isPathSegment(segment: string): boolean {\n  return segment !== '' && segment !== '.' && segment !== '..';\n}\n\n/**\n * The logical path a route pattern names under these params, which arrive decoded\n * (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;\n * empty -> `'/'`.\n * Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an\n * encoded dot segment (`%2E%2E`) stays an inert literal segment.\n */\nexport function routeLogicalPath(route: string, params: RouteParams): string {\n  const segments = route\n    .split('/')\n    .filter(Boolean)\n    .flatMap((segment) => {\n      const dynamic = /^\\[{1,2}(?:\\.\\.\\.)?([^\\]]+)\\]{1,2}$/.exec(segment);\n      if (!dynamic) return [segment];\n      return [params[dynamic[1] as string] ?? []].flat();\n    })\n    .filter(isPathSegment);\n  return `/${segments.join('/')}`;\n}\n\nfunction readVariants(data: unknown): RouteVariant[] {\n  const variants = (data as { catalogRoute?: { variants?: unknown } | null } | null)?.catalogRoute?.variants;\n  if (!Array.isArray(variants)) return [];\n  return variants.filter(\n    (variant): variant is RouteVariant => typeof variant?.locale === 'string' && typeof variant?.path === 'string',\n  );\n}\n\n/** Binding id -> confirmed variant path, matching BCP 47 tags case-insensitively and nothing looser. */\nfunction variantPathsByBinding(\n  bindings: readonly AlternateBinding[],\n  variants: readonly RouteVariant[],\n): Record<string, string> {\n  const paths: Record<string, string> = {};\n  for (const binding of bindings) {\n    const locale = binding.locale.toLowerCase();\n    const variant = variants.find((candidate) => candidate.locale.toLowerCase() === locale);\n    if (variant) paths[binding.bindingId] = variant.path;\n  }\n  return paths;\n}\n\n/**\n * Why a lookup degraded, safe to log: the GraphQL error code, else the allow-listed error name. `null`\n * for `BAD_USER_INPUT`, which a path `catalogRoute` cannot parse (a slug with a dot) always answers.\n */\nfunction degradedReason(error: unknown): string | null {\n  if (!CombinedGraphQLErrors.is(error)) return loggableErrorName(error);\n  const codes = error.errors.map(({ extensions }) => extensions?.code);\n  if (codes.length > 0 && codes.every((candidate) => candidate === 'BAD_USER_INPUT')) return null;\n  const code = codes.find(\n    (candidate): candidate is string => typeof candidate === 'string' && candidate !== 'BAD_USER_INPUT',\n  );\n  return code ?? 'GRAPHQL_ERROR';\n}\n\nfunction warnDegraded(error: unknown): null {\n  const reason = degradedReason(error);\n  if (reason) console.warn('[seo.catalogClusterPaths] catalogRoute lookup degraded to no cluster', reason);\n  return null;\n}\n\n/**\n * Binding id -> variant path for the bindings whose locale a confirmed variant matches. Never\n * rejects: a thrown loader, an `error`, a missing or `null` `catalogRoute`, or no matching variant\n * all resolve to `null`, so a catalog lookup can never fail the page it describes. A thrown loader\n * or an `error` is logged by code or error name only, never with the path or the upstream message.\n */\nexport async function catalogClusterPaths(\n  bindings: readonly AlternateBinding[],\n  load: () => Promise<{ data: unknown; error?: unknown }>,\n): Promise<Record<string, string> | null> {\n  try {\n    const { data, error } = await load();\n    if (error) return warnDegraded(error);\n    const paths = variantPathsByBinding(bindings, readVariants(data));\n    return Object.keys(paths).length > 0 ? paths : null;\n  } catch (error) {\n    return warnDegraded(error);\n  }\n}\n"],"mappings":";;;;;;;;AAkCA,MAAa,iCAAiC,QAAQ;;;;;;;;;CASrD;;AAGD,SAAgB,WAAW,MAAsB;CAC/C,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,KAAK,GAAG;AACzD;;;;;AAMA,SAAS,gBAAgB,UAAuC,kBAA8C;CAC5G,MAAM,2BAAW,IAAI,IAA8B;CACnD,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,MAAM,QAAQ,OAAO,YAAY;EAEvC,IAAI,CADY,SAAS,IAAI,GAClB,KAAK,QAAQ,cAAc,kBAAkB,SAAS,IAAI,KAAK,OAAO;CACnF;CACA,OAAO,SAAS,QAAQ,YAAY,SAAS,IAAI,QAAQ,OAAO,YAAY,CAAC,MAAM,OAAO;AAC5F;;;;;AAMA,SAAgB,oBAAoB,EAClC,WACA,kBACA,UACA,UACA,cACA,YAC6C;CAC7C,MAAM,OAAO,IAAY,SAAiB,SAAS,IAAI,WAAW,IAAI,CAAC;CACvE,MAAM,UAAU,OAAgB,gBAAgB,OAAO,OAAO,cAAc,EAAE,IAAI,aAAa,MAAM,KAAA;CACrG,MAAM,YAAY,IAAI,WAAW,OAAO,SAAS,KAAK,QAAQ;CAE9D,MAAM,UAAU,gBAAgB,UAAU,gBAAgB,CAAC,CAAC,SAAS,YAAY;EAC/E,MAAM,OAAO,OAAO,QAAQ,SAAS;EACrC,OAAO,SAAS,KAAA,IAAY,CAAC,IAAI,CAAC;GAAE,GAAG;GAAS,MAAM,IAAI,QAAQ,WAAW,IAAI;EAAE,CAAC;CACtF,CAAC;CACD,IAAI,QAAQ,SAAS,KAAK,CAAC,QAAQ,MAAM,WAAW,OAAO,cAAc,SAAS,GAAG,OAAO,EAAE,UAAU;CAExG,MAAM,YAAoC,CAAC;CAC3C,KAAK,MAAM,UAAU,SAAS,UAAU,OAAO,UAAU,OAAO;CAChE,MAAM,gBAAgB,QAAQ,MAAM,WAAW,OAAO,cAAc,gBAAgB;CACpF,IAAI,eAAe,UAAU,eAAe,cAAc;CAC1D,OAAO;EAAE;EAAW;CAAU;AAChC;;AAGA,SAAS,cAAc,SAA0B;CAC/C,OAAO,YAAY,MAAM,YAAY,OAAO,YAAY;AAC1D;;;;;;;;AASA,SAAgB,iBAAiB,OAAe,QAA6B;CAU3E,OAAO,IATU,MACd,MAAM,GAAG,CAAC,CACV,OAAO,OAAO,CAAC,CACf,SAAS,YAAY;EACpB,MAAM,UAAU,sCAAsC,KAAK,OAAO;EAClE,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO;EAC7B,OAAO,CAAC,OAAO,QAAQ,OAAiB,CAAC,CAAC,CAAC,CAAC,KAAK;CACnD,CAAC,CAAC,CACD,OAAO,aACQ,CAAC,CAAC,KAAK,GAAG;AAC9B;AAEA,SAAS,aAAa,MAA+B;CACnD,MAAM,WAAY,MAAkE,cAAc;CAClG,IAAI,CAAC,MAAM,QAAQ,QAAQ,GAAG,OAAO,CAAC;CACtC,OAAO,SAAS,QACb,YAAqC,OAAO,SAAS,WAAW,YAAY,OAAO,SAAS,SAAS,QACxG;AACF;;AAGA,SAAS,sBACP,UACA,UACwB;CACxB,MAAM,QAAgC,CAAC;CACvC,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,SAAS,QAAQ,OAAO,YAAY;EAC1C,MAAM,UAAU,SAAS,MAAM,cAAc,UAAU,OAAO,YAAY,MAAM,MAAM;EACtF,IAAI,SAAS,MAAM,QAAQ,aAAa,QAAQ;CAClD;CACA,OAAO;AACT;;;;;AAMA,SAAS,eAAe,OAA+B;CACrD,IAAI,CAAC,sBAAsB,GAAG,KAAK,GAAG,OAAO,kBAAkB,KAAK;CACpE,MAAM,QAAQ,MAAM,OAAO,KAAK,EAAE,iBAAiB,YAAY,IAAI;CACnE,IAAI,MAAM,SAAS,KAAK,MAAM,OAAO,cAAc,cAAc,gBAAgB,GAAG,OAAO;CAI3F,OAHa,MAAM,MAChB,cAAmC,OAAO,cAAc,YAAY,cAAc,gBAE3E,KAAK;AACjB;AAEA,SAAS,aAAa,OAAsB;CAC1C,MAAM,SAAS,eAAe,KAAK;CACnC,IAAI,QAAQ,QAAQ,KAAK,wEAAwE,MAAM;CACvG,OAAO;AACT;;;;;;;AAQA,eAAsB,oBACpB,UACA,MACwC;CACxC,IAAI;EACF,MAAM,EAAE,MAAM,UAAU,MAAM,KAAK;EACnC,IAAI,OAAO,OAAO,aAAa,KAAK;EACpC,MAAM,QAAQ,sBAAsB,UAAU,aAAa,IAAI,CAAC;EAChE,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ;CACjD,SAAS,OAAO;EACd,OAAO,aAAa,KAAK;CAC3B;AACF"}

package/dist/sdk/shipping/shipping-operations.d.ts

@@ -24,7 +24,7 @@ export type ShippingAddressUpdateErrorEntity = Readonly<{
 }>;
 export type ShippingAddressInput = Readonly<{
   savedAddressId?: string;
-  recipientName: string;
+  recipientName?: string;
   postalCode: string;
   country: string;
   street?: string;

package/dist/sdk/shipping/shipping-operations.js

@@ -62,6 +62,19 @@ const SHIPPING_ADDRESS_UPDATE = gql`
       }
       cart {
         ...CartFragment
+        freeShippingProgress {
+          threshold {
+            __typename
+            amount
+            currencyCode
+          }
+          remaining {
+            __typename
+            amount
+            currencyCode
+          }
+          qualified
+        }
       }
       userErrors {
         code

package/dist/sdk/shipping/shipping-operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"shipping-operations.js","names":[],"sources":["../../../src/sdk/shipping/shipping-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Shipping address mutation documents (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive\n * read path (`operations.ts`) — and explicitly excluded from the codegen `documents` glob (see\n * `codegen.ts`): the `gql` tag alone is still plucked by `graphql-codegen`, which would duplicate\n * these hand-written types in `sdk/generated/`. The mutation stays hand-typed as a\n * `TypedDocumentNode` (Decision 3 in the spec). The payload projects the full refreshed `shipping`\n * and `cart` state, so the response write into the cache *is* the post-update refresh: `Shipping`'s\n * reactive read flips with no refetch and no imperative cache write.\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`\n * (`ShippingAddressUpdateError`); transport and top-level GraphQL failures are infrastructure,\n * mapped by the handlers in `use-shipping-actions.ts` to the one client-synthesized code,\n * `NETWORK_USER_ERROR`.\n */\n\n/** A typed address-update failure; NETWORK_USER_ERROR is the one client-synthesized code. */\nexport type ShippingAddressUpdateErrorEntity = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError that `setAddress` *resolves*\n * (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use\n * it to route the resolved synthetic failure to the generic upstream error state (Decision 5),\n * distinct from the domain `userErrors` codes that render inline.\n */\nexport const SHIPPING_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type ShippingAddressInput = Readonly<{\n  savedAddressId?: string;\n  recipientName: string;\n  postalCode: string;\n  country: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n}>;\n\n/** The full shippingAddressUpdate mutation payload. */\nexport type ShippingAddressUpdatePayloadEntity = Readonly<{\n  __typename: 'ShippingAddressUpdatePayload';\n  shipping: {\n    __typename: 'Shipping';\n    id: string;\n    address: {\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    } | null;\n    savedAddresses: ReadonlyArray<{\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    }>;\n    options: ReadonlyArray<{\n      __typename: 'ShippingOption';\n      id: string;\n      name: string;\n      channel: string;\n      shippingEstimate: { __typename: 'ShippingEstimate'; value: number; unit: string };\n      price: { __typename: 'Money'; amount: number; currencyCode: string };\n      listPrice: { __typename: 'Money'; amount: number; currencyCode: string };\n    }>;\n    selectedOptionId?: string | null;\n  } | null;\n  cart: CartEntity;\n  userErrors: readonly ShippingAddressUpdateErrorEntity[];\n}>;\n\ntype ShippingAddressUpdateData = Readonly<{ shippingAddressUpdate: ShippingAddressUpdatePayloadEntity }>;\n\nexport const SHIPPING_ADDRESS_UPDATE: TypedDocumentNode<ShippingAddressUpdateData, { input: ShippingAddressInput }> =\n  gql`\n  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {\n    shippingAddressUpdate(input: $input) {\n      shipping {\n        __typename\n        id\n        address {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        savedAddresses {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        options {\n          __typename\n          id\n          name\n          channel\n          shippingEstimate {\n            value\n            unit\n          }\n          price {\n            amount\n            currencyCode\n          }\n          listPrice {\n            amount\n            currencyCode\n          }\n        }\n        selectedOptionId\n      }\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${CartFragment}\n`;\n"],"mappings":";;;;;;;;;AA8BA,MAAa,8BAA8B;AAgE3C,MAAa,0BACX,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6DD,aAAa"}
+{"version":3,"file":"shipping-operations.js","names":[],"sources":["../../../src/sdk/shipping/shipping-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment, type CartFreeShippingProgress } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Shipping address mutation documents (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive\n * read path (`operations.ts`) — and explicitly excluded from the codegen `documents` glob (see\n * `codegen.ts`): the `gql` tag alone is still plucked by `graphql-codegen`, which would duplicate\n * these hand-written types in `sdk/generated/`. The mutation stays hand-typed as a\n * `TypedDocumentNode` (Decision 3 in the spec). The payload projects the full refreshed `shipping`\n * and `cart` state, so the response write into the cache *is* the post-update refresh: `Shipping`'s\n * reactive read flips with no refetch and no imperative cache write.\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`\n * (`ShippingAddressUpdateError`); transport and top-level GraphQL failures are infrastructure,\n * mapped by the handlers in `use-shipping-actions.ts` to the one client-synthesized code,\n * `NETWORK_USER_ERROR`.\n */\n\n/** A typed address-update failure; NETWORK_USER_ERROR is the one client-synthesized code. */\nexport type ShippingAddressUpdateErrorEntity = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError that `setAddress` *resolves*\n * (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use\n * it to route the resolved synthetic failure to the generic upstream error state (Decision 5),\n * distinct from the domain `userErrors` codes that render inline.\n */\nexport const SHIPPING_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type ShippingAddressInput = Readonly<{\n  savedAddressId?: string;\n  recipientName?: string;\n  postalCode: string;\n  country: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n}>;\n\n/** The full shippingAddressUpdate mutation payload. */\nexport type ShippingAddressUpdatePayloadEntity = Readonly<{\n  __typename: 'ShippingAddressUpdatePayload';\n  shipping: {\n    __typename: 'Shipping';\n    id: string;\n    address: {\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    } | null;\n    savedAddresses: ReadonlyArray<{\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    }>;\n    options: ReadonlyArray<{\n      __typename: 'ShippingOption';\n      id: string;\n      name: string;\n      channel: string;\n      shippingEstimate: { __typename: 'ShippingEstimate'; value: number; unit: string };\n      price: { __typename: 'Money'; amount: number; currencyCode: string };\n      listPrice: { __typename: 'Money'; amount: number; currencyCode: string };\n    }>;\n    selectedOptionId?: string | null;\n  } | null;\n  cart: CartEntity & { freeShippingProgress: CartFreeShippingProgress | null };\n  userErrors: readonly ShippingAddressUpdateErrorEntity[];\n}>;\n\ntype ShippingAddressUpdateData = Readonly<{ shippingAddressUpdate: ShippingAddressUpdatePayloadEntity }>;\n\nexport const SHIPPING_ADDRESS_UPDATE: TypedDocumentNode<ShippingAddressUpdateData, { input: ShippingAddressInput }> =\n  gql`\n  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {\n    shippingAddressUpdate(input: $input) {\n      shipping {\n        __typename\n        id\n        address {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        savedAddresses {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        options {\n          __typename\n          id\n          name\n          channel\n          shippingEstimate {\n            value\n            unit\n          }\n          price {\n            amount\n            currencyCode\n          }\n          listPrice {\n            amount\n            currencyCode\n          }\n        }\n        selectedOptionId\n      }\n      cart {\n        ...CartFragment\n        freeShippingProgress {\n          threshold {\n            __typename\n            amount\n            currencyCode\n          }\n          remaining {\n            __typename\n            amount\n            currencyCode\n          }\n          qualified\n        }\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${CartFragment}\n`;\n"],"mappings":";;;;;;;;;AA8BA,MAAa,8BAA8B;AAgE3C,MAAa,0BACX,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0ED,aAAa"}

package/dist/sdk/state/cart.d.ts

@@ -2,8 +2,12 @@
 export declare const orderFormIdVar: import("@apollo/client").ReactiveVar<string | null>;
 /**
  * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
- * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+ * here on every call and `CartError` reads it
  * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.
+ *
+ * Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and
+ * `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,
+ * so without the mount clear an error from another page would show on the next one.
  */
 export declare const cartUserErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
   code: string;
@@ -30,8 +34,11 @@ export declare const miniCartOpenVar: import("@apollo/client").ReactiveVar<boole
  * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
  * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
  * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon
- * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+ * actions publish here on every call and `CartCouponError`
  * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+ *
+ * Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`
+ * leave it alone. A CartRoot mount clears it too, never a re-render.
  */
 export declare const cartCouponErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
   code: string;

package/dist/sdk/state/cart.js

@@ -3,8 +3,12 @@ import { makeVar } from "@apollo/client";
 const orderFormIdVar = makeVar(null);
 /**
 * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
-* here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+* here on every call and `CartError` reads it
 * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.
+*
+* Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and
+* `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,
+* so without the mount clear an error from another page would show on the next one.
 */
 const cartUserErrorsVar = makeVar([]);
 /**
@@ -28,8 +32,11 @@ const miniCartOpenVar = makeVar(false);
 * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
 * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
 * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon
-* actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+* actions publish here on every call and `CartCouponError`
 * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+*
+* Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`
+* leave it alone. A CartRoot mount clears it too, never a re-render.
 */
 const cartCouponErrorsVar = makeVar([]);
 /**

package/dist/sdk/state/cart.js.map

@@ -1 +1 @@
-{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See docs/storefront-core/reference-cart.md § Cart context; docs/storefront-core/reference-free-particle-model.md § The cart write contract.\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon\n * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;AAOzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;AASrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}
+{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See docs/storefront-core/reference-cart.md § Cart context; docs/storefront-core/reference-free-particle-model.md § The cart write contract.\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.\n *\n * Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and\n * `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,\n * so without the mount clear an error from another page would show on the next one.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon\n * actions publish here on every call and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n *\n * Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`\n * leave it alone. A CartRoot mount clears it too, never a re-render.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;;;;;AAWzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;;;;AAYrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}

package/dist/utils/own-value.js

@@ -0,0 +1,19 @@
+//#region src/utils/own-value.ts
+/**
+* Own-property read. `Object.hasOwn`, not a bare index lookup or `key in source`: every plain object
+* inherits from `Object.prototype`, so `source['constructor']` resolves to
+* `Object.prototype.constructor` — a function, therefore never `undefined` — and `__proto__` to the
+* prototype itself, and the absent-key branch of the caller would never be taken. Every keyed
+* lookup here is fed an authored or user-typed key (an element id from `JSON.parse`, a card network
+* or payment method name), so an inherited name must read as missing, never as a value.
+*
+* Lives in `utils/` because its callers span peer domains (`sdk/content`, `matter/card-entry`,
+* `matter/payment`), none of which should import a lookup helper from another.
+*/
+function ownValue(source, key) {
+	return Object.hasOwn(source, key) ? source[key] : void 0;
+}
+//#endregion
+export { ownValue };
+
+//# sourceMappingURL=own-value.js.map

package/dist/utils/own-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-value.js","names":[],"sources":["../../src/utils/own-value.ts"],"sourcesContent":["/**\n * Own-property read. `Object.hasOwn`, not a bare index lookup or `key in source`: every plain object\n * inherits from `Object.prototype`, so `source['constructor']` resolves to\n * `Object.prototype.constructor` — a function, therefore never `undefined` — and `__proto__` to the\n * prototype itself, and the absent-key branch of the caller would never be taken. Every keyed\n * lookup here is fed an authored or user-typed key (an element id from `JSON.parse`, a card network\n * or payment method name), so an inherited name must read as missing, never as a value.\n *\n * Lives in `utils/` because its callers span peer domains (`sdk/content`, `matter/card-entry`,\n * `matter/payment`), none of which should import a lookup helper from another.\n */\nexport function ownValue<T>(source: Record<string, T>, key: string): T | undefined {\n  return Object.hasOwn(source, key) ? source[key] : undefined;\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,SAAY,QAA2B,KAA4B;CACjF,OAAO,OAAO,OAAO,QAAQ,GAAG,IAAI,OAAO,OAAO,KAAA;AACpD"}

package/dist/utils/safe-href.d.ts

@@ -1,11 +1,11 @@
+import { PageRef } from "../sdk/navigation/types.js";
 //#region src/utils/safe-href.d.ts
 /**
- * Builds the sign-in destination, carrying the current path so the shopper can be returned where they
+ * The sign-in page, carrying the current logical path so the shopper can be returned where they
  * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow
  * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of
- * travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes
- * a nullable one.
+ * travelling encoded, and so does a router reporting no path.
  */
-export declare function resolveSignInHref(pathname: string | null): string;
+export declare function signInTarget(path: string | null): PageRef;
 //#endregion
 //# sourceMappingURL=safe-href.d.ts.map

package/dist/utils/safe-href.js

@@ -49,9 +49,8 @@ function resolveSafeHref(raw) {
 		reason: "forbidden-scheme"
 	};
 }
-/** The storefront's own sign-in route, which forwards to the platform's login. A fixed convention,
-*  never an authored value. */
-const SIGN_IN_ROUTE = "/login";
+/** The storefront's own sign-in page, which forwards to the platform's login. Never an authored value. */
+const SIGN_IN_PAGE = { standard: "sign-in" };
 /** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */
 const RETURN_URL_PARAM = "returnUrl";
 /**
@@ -61,7 +60,7 @@ const RETURN_URL_PARAM = "returnUrl";
 * unchanged, so a caller logging the reason still sees which spelling arrived.
 *
 * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch
-* for a URL the shopper typed: the account button builds the destination through `resolveSignInHref`, and
+* for a URL the shopper typed: the account button builds the destination through `signInTarget`, and
 * the sign-in route revalidates what arrives through `resolveReturnHref`.
 */
 function resolveSiteRelativeHref(raw) {
@@ -92,50 +91,60 @@ function resolveNavigableHref(raw) {
 * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route
 * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which
 * hands them to the platform a second time — a sign-in that never lands where the parameter promised.
+*
+* `signInPath` is the sign-in page's logical path, since a return is one; `null` when the store has no
+* sign-in page, and then no return is the route.
 */
-function resolveReturnHref(raw) {
+function resolveReturnHref(raw, signInPath) {
 	const destination = resolveSiteRelativeHref(raw);
 	if (!destination.safe) return destination;
-	return isSignInRoute(destination.href) ? {
+	return isSignInRoute(destination.href, signInPath) ? {
 		safe: false,
 		reason: "sign-in-route"
 	} : destination;
 }
-/** Whether a site-relative value names the storefront's own sign-in route, in any of its spellings. */
-function isSignInRoute(href) {
-	return pathOf(href) === SIGN_IN_ROUTE;
+/**
+* Whether a site-relative value names the sign-in page at `signInPath`, in any of its spellings. `null`
+* is a store without a sign-in page, where nothing is the route.
+*/
+function isSignInRoute(href, signInPath) {
+	return signInPath !== null && pathOf(href) === pathOf(signInPath);
 }
 /**
 * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in
-* route is refused. Sending `/login` to `/login` reloads the same document, which mounts the same
+* route is refused. Sending the route to itself reloads the same document, which mounts the same
 * handover again — a loop the shopper never gets past, and the mirror of the refusal
 * `resolveReturnHref` already makes on the way back.
 *
 * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute
 * address needs the document's own origin to compare against, which this module does not have and a
 * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin
-* login page whose path happens to be `/login` is a different page and is left alone.
+* login page whose path happens to be the route's is a different page and is left alone.
+*
+* `signInPath` is the sign-in page's public path, since the address is a document URL.
 */
-function resolveLoginAddressHref(raw) {
+function resolveLoginAddressHref(raw, signInPath) {
 	const address = resolveNavigableHref(raw);
 	if (!address.safe || !address.href.startsWith("/")) return address;
-	return isSignInRoute(address.href) ? {
+	return isSignInRoute(address.href, signInPath) ? {
 		safe: false,
 		reason: "sign-in-route"
 	} : address;
 }
 /**
-* Builds the sign-in destination, carrying the current path so the shopper can be returned where they
+* The sign-in page, carrying the current logical path so the shopper can be returned where they
 * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow
 * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of
-* travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes
-* a nullable one.
+* travelling encoded, and so does a router reporting no path.
 */
-function resolveSignInHref(pathname) {
-	if (!pathname) return SIGN_IN_ROUTE;
-	const destination = resolveSiteRelativeHref(pathname);
-	if (!destination.safe) return SIGN_IN_ROUTE;
-	return `${SIGN_IN_ROUTE}?${RETURN_URL_PARAM}=${encodeURIComponent(destination.href)}`;
+function signInTarget(path) {
+	if (!path) return SIGN_IN_PAGE;
+	const destination = resolveSiteRelativeHref(path);
+	if (!destination.safe) return SIGN_IN_PAGE;
+	return {
+		standard: "sign-in",
+		query: { [RETURN_URL_PARAM]: destination.href }
+	};
 }
 /** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a
 *  real host; nothing is navigated to it and only `pathname` is read back. */
@@ -164,6 +173,6 @@ function hasStrippableCharacter(value) {
 	return false;
 }
 //#endregion
-export { RETURN_URL_PARAM, isSignInRoute, resolveLoginAddressHref, resolveNavigableHref, resolveReturnHref, resolveSafeHref, resolveSignInHref, resolveSiteRelativeHref };
+export { RETURN_URL_PARAM, SIGN_IN_PAGE, isSignInRoute, resolveLoginAddressHref, resolveNavigableHref, resolveReturnHref, resolveSafeHref, resolveSiteRelativeHref, signInTarget };
 
 //# sourceMappingURL=safe-href.js.map

package/dist/utils/safe-href.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-href.js","names":[],"sources":["../../src/utils/safe-href.ts"],"sourcesContent":["export type SafeHrefRejection =\n  | 'blank'\n  | 'malformed'\n  | 'protocol-relative'\n  | 'forbidden-scheme'\n  | 'absolute'\n  | 'sign-in-route';\n\nexport type SafeHrefResult = { safe: true; href: string } | { safe: false; reason: SafeHrefRejection };\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * The only gate on a CMS-authored destination: `http:`, `https:`, `mailto:`, `tel:`, and paths\n * starting with a single `/`. The runtime slice does not enforce a model's `pattern`, and the sukima\n * preflight that does never sees content published after a deploy, so an authored `javascript:` value\n * can reach the component intact and this is what stands between it and an `href`.\n *\n * Rejects rather than sanitizes: a destination that comes back safe is character-for-character the\n * trimmed authored value, so no value is ever silently rewritten into a different working one.\n */\nexport function resolveSafeHref(raw: string): SafeHrefResult {\n  const href = raw.trim();\n  if (href.length === 0) {\n    return { safe: false, reason: 'blank' };\n  }\n  // Browsers strip ASCII tabs and newlines from a URL before parsing it, so `java<TAB>script:alert(1)`\n  // executes. Refusing the whole value is the only defense that does not depend on stripping the same\n  // characters in the same order the parser does.\n  if (hasStrippableCharacter(href)) {\n    return { safe: false, reason: 'malformed' };\n  }\n  // A URL parser reads `\\` as `/` under a special scheme, so `/\\evil.example` resolves against the\n  // store's origin as an authority rather than a path. Any pair of leading slashes is an off-site\n  // jump however it is spelled, and only `//` looks like one.\n  if (/^[/\\\\]{2}/.test(href)) {\n    return { safe: false, reason: 'protocol-relative' };\n  }\n  if (href.startsWith('/')) {\n    return { safe: true, href };\n  }\n\n  let protocol: string;\n  try {\n    protocol = new URL(href).protocol;\n  } catch {\n    return { safe: false, reason: 'malformed' };\n  }\n  // `new URL` lowercases the protocol, so `JavaScript:` and `javascript:` are the same rejection.\n  return ALLOWED_PROTOCOLS.has(protocol) ? { safe: true, href } : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/** The storefront's own sign-in route, which forwards to the platform's login. A fixed convention,\n *  never an authored value. */\nconst SIGN_IN_ROUTE = '/login';\n\n/** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */\nexport const RETURN_URL_PARAM = 'returnUrl';\n\n/**\n * `resolveSafeHref` narrowed to the site-relative subset: the destinations a shopper may be sent back to\n * across the auth hop. The allowlist admits absolute http(s) values, which are legitimate for an authored\n * link but are exactly what would turn the hop into an open redirect. Every other rejection travels out\n * unchanged, so a caller logging the reason still sees which spelling arrived.\n *\n * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch\n * for a URL the shopper typed: the account button builds the destination through `resolveSignInHref`, and\n * the sign-in route revalidates what arrives through `resolveReturnHref`.\n */\nexport function resolveSiteRelativeHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return destination.href.startsWith('/') ? destination : { safe: false, reason: 'absolute' };\n}\n\n/** The subset of the allowlist that resolves to a page a document can be handed over to. */\nconst NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);\n\n/**\n * `resolveSafeHref` narrowed to the destinations that resolve to a page: site-relative, or absolute\n * `http(s)`. `mailto:` and `tel:` are legitimate for an authored link and refused here, since handing a\n * document over to one leaves the shopper in a mail client instead of a login.\n */\nexport function resolveNavigableHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe || destination.href.startsWith('/')) {\n    return destination;\n  }\n  // The allowlist already parsed this value, so the protocol is readable without a second guard.\n  const { protocol } = new URL(destination.href);\n  return NAVIGABLE_PROTOCOLS.has(protocol) ? destination : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/**\n * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route\n * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which\n * hands them to the platform a second time — a sign-in that never lands where the parameter promised.\n */\nexport function resolveReturnHref(raw: string): SafeHrefResult {\n  const destination = resolveSiteRelativeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return isSignInRoute(destination.href) ? { safe: false, reason: 'sign-in-route' } : destination;\n}\n\n/** Whether a site-relative value names the storefront's own sign-in route, in any of its spellings. */\nexport function isSignInRoute(href: string): boolean {\n  return pathOf(href) === SIGN_IN_ROUTE;\n}\n\n/**\n * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in\n * route is refused. Sending `/login` to `/login` reloads the same document, which mounts the same\n * handover again — a loop the shopper never gets past, and the mirror of the refusal\n * `resolveReturnHref` already makes on the way back.\n *\n * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute\n * address needs the document's own origin to compare against, which this module does not have and a\n * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin\n * login page whose path happens to be `/login` is a different page and is left alone.\n */\nexport function resolveLoginAddressHref(raw: string): SafeHrefResult {\n  const address = resolveNavigableHref(raw);\n  if (!address.safe || !address.href.startsWith('/')) {\n    return address;\n  }\n  return isSignInRoute(address.href) ? { safe: false, reason: 'sign-in-route' } : address;\n}\n\n/**\n * Builds the sign-in destination, carrying the current path so the shopper can be returned where they\n * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow\n * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of\n * travelling encoded, and so does a router reporting no path — `usePathname()`'s type is why this takes\n * a nullable one.\n */\nexport function resolveSignInHref(pathname: string | null): string {\n  if (!pathname) {\n    return SIGN_IN_ROUTE;\n  }\n  const destination = resolveSiteRelativeHref(pathname);\n  if (!destination.safe) {\n    return SIGN_IN_ROUTE;\n  }\n  return `${SIGN_IN_ROUTE}?${RETURN_URL_PARAM}=${encodeURIComponent(destination.href)}`;\n}\n\n/** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a\n *  real host; nothing is navigated to it and only `pathname` is read back. */\nconst PATH_COMPARISON_BASE = 'https://store.invalid';\n\n/**\n * The path of a site-relative value, without its query or fragment and without a trailing slash, so a\n * route comparison reads the route rather than one of its spellings. `/loginhelp` is a different path\n * and stays one.\n *\n * Parsed rather than sliced, because `/account/../login`, `/account\\..\\login` and `/account/%2e%2e/login`\n * are all spellings a URL parser resolves to `/login`. A slice compares them literally and admits them,\n * and the value then reaches a receiver that does resolve them — which puts the shopper back on the\n * trampoline the refusal exists to prevent. Only the comparison is normalized: the caller returns the\n * value as it arrived, so the promise that nothing is silently rewritten still holds.\n */\nfunction pathOf(href: string): string {\n  const { pathname } = new URL(href, PATH_COMPARISON_BASE);\n  return pathname.replace(/\\/+$/, '') || '/';\n}\n\n/** Any C0 control or space anywhere in the value — the set a URL parser removes or trims. */\nfunction hasStrippableCharacter(value: string): boolean {\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    if (code <= 0x20 || code === 0x7f) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":";AAUA,MAAM,oCAAoB,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;;;;;AAWxE,SAAgB,gBAAgB,KAA6B;CAC3D,MAAM,OAAO,IAAI,KAAK;CACtB,IAAI,KAAK,WAAW,GAClB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAQ;CAKxC,IAAI,uBAAuB,IAAI,GAC7B,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAY;CAK5C,IAAI,YAAY,KAAK,IAAI,GACvB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAoB;CAEpD,IAAI,KAAK,WAAW,GAAG,GACrB,OAAO;EAAE,MAAM;EAAM;CAAK;CAG5B,IAAI;CACJ,IAAI;EACF,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC;CAC3B,QAAQ;EACN,OAAO;GAAE,MAAM;GAAO,QAAQ;EAAY;CAC5C;CAEA,OAAO,kBAAkB,IAAI,QAAQ,IAAI;EAAE,MAAM;EAAM;CAAK,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAmB;AAC5G;;;AAIA,MAAM,gBAAgB;;AAGtB,MAAa,mBAAmB;;;;;;;;;;;AAYhC,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,YAAY,KAAK,WAAW,GAAG,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAW;AAC5F;;AAGA,MAAM,sCAAsB,IAAI,IAAI,CAAC,SAAS,QAAQ,CAAC;;;;;;AAOvD,SAAgB,qBAAqB,KAA6B;CAChE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,QAAQ,YAAY,KAAK,WAAW,GAAG,GACtD,OAAO;CAGT,MAAM,EAAE,aAAa,IAAI,IAAI,YAAY,IAAI;CAC7C,OAAO,oBAAoB,IAAI,QAAQ,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAmB;AACrG;;;;;;AAOA,SAAgB,kBAAkB,KAA6B;CAC7D,MAAM,cAAc,wBAAwB,GAAG;CAC/C,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,cAAc,YAAY,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AACtF;;AAGA,SAAgB,cAAc,MAAuB;CACnD,OAAO,OAAO,IAAI,MAAM;AAC1B;;;;;;;;;;;;AAaA,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,UAAU,qBAAqB,GAAG;CACxC,IAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,KAAK,WAAW,GAAG,GAC/C,OAAO;CAET,OAAO,cAAc,QAAQ,IAAI,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAClF;;;;;;;;AASA,SAAgB,kBAAkB,UAAiC;CACjE,IAAI,CAAC,UACH,OAAO;CAET,MAAM,cAAc,wBAAwB,QAAQ;CACpD,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,GAAG,cAAc,GAAG,iBAAiB,GAAG,mBAAmB,YAAY,IAAI;AACpF;;;AAIA,MAAM,uBAAuB;;;;;;;;;;;;AAa7B,SAAS,OAAO,MAAsB;CACpC,MAAM,EAAE,aAAa,IAAI,IAAI,MAAM,oBAAoB;CACvD,OAAO,SAAS,QAAQ,QAAQ,EAAE,KAAK;AACzC;;AAGA,SAAS,uBAAuB,OAAwB;CACtD,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,IAAI,QAAQ,MAAQ,SAAS,KAC3B,OAAO;CAEX;CACA,OAAO;AACT"}
+{"version":3,"file":"safe-href.js","names":[],"sources":["../../src/utils/safe-href.ts"],"sourcesContent":["import type { PageRef } from '../sdk/navigation/types.js';\n\nexport type SafeHrefRejection =\n  | 'blank'\n  | 'malformed'\n  | 'protocol-relative'\n  | 'forbidden-scheme'\n  | 'absolute'\n  | 'sign-in-route';\n\nexport type SafeHrefResult = { safe: true; href: string } | { safe: false; reason: SafeHrefRejection };\n\nconst ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * The only gate on a CMS-authored destination: `http:`, `https:`, `mailto:`, `tel:`, and paths\n * starting with a single `/`. The runtime slice does not enforce a model's `pattern`, and the sukima\n * preflight that does never sees content published after a deploy, so an authored `javascript:` value\n * can reach the component intact and this is what stands between it and an `href`.\n *\n * Rejects rather than sanitizes: a destination that comes back safe is character-for-character the\n * trimmed authored value, so no value is ever silently rewritten into a different working one.\n */\nexport function resolveSafeHref(raw: string): SafeHrefResult {\n  const href = raw.trim();\n  if (href.length === 0) {\n    return { safe: false, reason: 'blank' };\n  }\n  // Browsers strip ASCII tabs and newlines from a URL before parsing it, so `java<TAB>script:alert(1)`\n  // executes. Refusing the whole value is the only defense that does not depend on stripping the same\n  // characters in the same order the parser does.\n  if (hasStrippableCharacter(href)) {\n    return { safe: false, reason: 'malformed' };\n  }\n  // A URL parser reads `\\` as `/` under a special scheme, so `/\\evil.example` resolves against the\n  // store's origin as an authority rather than a path. Any pair of leading slashes is an off-site\n  // jump however it is spelled, and only `//` looks like one.\n  if (/^[/\\\\]{2}/.test(href)) {\n    return { safe: false, reason: 'protocol-relative' };\n  }\n  if (href.startsWith('/')) {\n    return { safe: true, href };\n  }\n\n  let protocol: string;\n  try {\n    protocol = new URL(href).protocol;\n  } catch {\n    return { safe: false, reason: 'malformed' };\n  }\n  // `new URL` lowercases the protocol, so `JavaScript:` and `javascript:` are the same rejection.\n  return ALLOWED_PROTOCOLS.has(protocol) ? { safe: true, href } : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/** The storefront's own sign-in page, which forwards to the platform's login. Never an authored value. */\nexport const SIGN_IN_PAGE: PageRef = { standard: 'sign-in' };\n\n/** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */\nexport const RETURN_URL_PARAM = 'returnUrl';\n\n/**\n * `resolveSafeHref` narrowed to the site-relative subset: the destinations a shopper may be sent back to\n * across the auth hop. The allowlist admits absolute http(s) values, which are legitimate for an authored\n * link but are exactly what would turn the hop into an open redirect. Every other rejection travels out\n * unchanged, so a caller logging the reason still sees which spelling arrived.\n *\n * Both ends of the flow narrow through here rather than only the sender, because the sender cannot vouch\n * for a URL the shopper typed: the account button builds the destination through `signInTarget`, and\n * the sign-in route revalidates what arrives through `resolveReturnHref`.\n */\nexport function resolveSiteRelativeHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return destination.href.startsWith('/') ? destination : { safe: false, reason: 'absolute' };\n}\n\n/** The subset of the allowlist that resolves to a page a document can be handed over to. */\nconst NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);\n\n/**\n * `resolveSafeHref` narrowed to the destinations that resolve to a page: site-relative, or absolute\n * `http(s)`. `mailto:` and `tel:` are legitimate for an authored link and refused here, since handing a\n * document over to one leaves the shopper in a mail client instead of a login.\n */\nexport function resolveNavigableHref(raw: string): SafeHrefResult {\n  const destination = resolveSafeHref(raw);\n  if (!destination.safe || destination.href.startsWith('/')) {\n    return destination;\n  }\n  // The allowlist already parsed this value, so the protocol is readable without a second guard.\n  const { protocol } = new URL(destination.href);\n  return NAVIGABLE_PROTOCOLS.has(protocol) ? destination : { safe: false, reason: 'forbidden-scheme' };\n}\n\n/**\n * `resolveSiteRelativeHref` narrowed further, for a return arriving at the sign-in route: the route\n * itself is refused. Admitting it sends a shopper who just authenticated back to the trampoline, which\n * hands them to the platform a second time — a sign-in that never lands where the parameter promised.\n *\n * `signInPath` is the sign-in page's logical path, since a return is one; `null` when the store has no\n * sign-in page, and then no return is the route.\n */\nexport function resolveReturnHref(raw: string, signInPath: string | null): SafeHrefResult {\n  const destination = resolveSiteRelativeHref(raw);\n  if (!destination.safe) {\n    return destination;\n  }\n  return isSignInRoute(destination.href, signInPath) ? { safe: false, reason: 'sign-in-route' } : destination;\n}\n\n/**\n * Whether a site-relative value names the sign-in page at `signInPath`, in any of its spellings. `null`\n * is a store without a sign-in page, where nothing is the route.\n */\nexport function isSignInRoute(href: string, signInPath: string | null): boolean {\n  return signInPath !== null && pathOf(href) === pathOf(signInPath);\n}\n\n/**\n * `resolveNavigableHref` narrowed for the address a handover targets: the storefront's own sign-in\n * route is refused. Sending the route to itself reloads the same document, which mounts the same\n * handover again — a loop the shopper never gets past, and the mirror of the refusal\n * `resolveReturnHref` already makes on the way back.\n *\n * Only the site-relative spelling is decidable here, being same-origin by construction. An absolute\n * address needs the document's own origin to compare against, which this module does not have and a\n * prerender does not either, so `isSignInRoute` is exported for the caller that does. A cross-origin\n * login page whose path happens to be the route's is a different page and is left alone.\n *\n * `signInPath` is the sign-in page's public path, since the address is a document URL.\n */\nexport function resolveLoginAddressHref(raw: string, signInPath: string | null): SafeHrefResult {\n  const address = resolveNavigableHref(raw);\n  if (!address.safe || !address.href.startsWith('/')) {\n    return address;\n  }\n  return isSignInRoute(address.href, signInPath) ? { safe: false, reason: 'sign-in-route' } : address;\n}\n\n/**\n * The sign-in page, carrying the current logical path so the shopper can be returned where they\n * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow\n * the parameter again on arrival. A path the narrowing refuses drops the parameter instead of\n * travelling encoded, and so does a router reporting no path.\n */\nexport function signInTarget(path: string | null): PageRef {\n  if (!path) {\n    return SIGN_IN_PAGE;\n  }\n  const destination = resolveSiteRelativeHref(path);\n  if (!destination.safe) {\n    return SIGN_IN_PAGE;\n  }\n  return { standard: 'sign-in', query: { [RETURN_URL_PARAM]: destination.href } };\n}\n\n/** Opaque base for resolving a site-relative value to a path. Reserved by RFC 6761, so it never names a\n *  real host; nothing is navigated to it and only `pathname` is read back. */\nconst PATH_COMPARISON_BASE = 'https://store.invalid';\n\n/**\n * The path of a site-relative value, without its query or fragment and without a trailing slash, so a\n * route comparison reads the route rather than one of its spellings. `/loginhelp` is a different path\n * and stays one.\n *\n * Parsed rather than sliced, because `/account/../login`, `/account\\..\\login` and `/account/%2e%2e/login`\n * are all spellings a URL parser resolves to `/login`. A slice compares them literally and admits them,\n * and the value then reaches a receiver that does resolve them — which puts the shopper back on the\n * trampoline the refusal exists to prevent. Only the comparison is normalized: the caller returns the\n * value as it arrived, so the promise that nothing is silently rewritten still holds.\n */\nfunction pathOf(href: string): string {\n  const { pathname } = new URL(href, PATH_COMPARISON_BASE);\n  return pathname.replace(/\\/+$/, '') || '/';\n}\n\n/** Any C0 control or space anywhere in the value — the set a URL parser removes or trims. */\nfunction hasStrippableCharacter(value: string): boolean {\n  for (const character of value) {\n    const code = character.codePointAt(0) ?? 0;\n    if (code <= 0x20 || code === 0x7f) {\n      return true;\n    }\n  }\n  return false;\n}\n"],"mappings":";AAYA,MAAM,oCAAoB,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;;;;;AAWxE,SAAgB,gBAAgB,KAA6B;CAC3D,MAAM,OAAO,IAAI,KAAK;CACtB,IAAI,KAAK,WAAW,GAClB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAQ;CAKxC,IAAI,uBAAuB,IAAI,GAC7B,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAY;CAK5C,IAAI,YAAY,KAAK,IAAI,GACvB,OAAO;EAAE,MAAM;EAAO,QAAQ;CAAoB;CAEpD,IAAI,KAAK,WAAW,GAAG,GACrB,OAAO;EAAE,MAAM;EAAM;CAAK;CAG5B,IAAI;CACJ,IAAI;EACF,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC;CAC3B,QAAQ;EACN,OAAO;GAAE,MAAM;GAAO,QAAQ;EAAY;CAC5C;CAEA,OAAO,kBAAkB,IAAI,QAAQ,IAAI;EAAE,MAAM;EAAM;CAAK,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAmB;AAC5G;;AAGA,MAAa,eAAwB,EAAE,UAAU,UAAU;;AAG3D,MAAa,mBAAmB;;;;;;;;;;;AAYhC,SAAgB,wBAAwB,KAA6B;CACnE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,YAAY,KAAK,WAAW,GAAG,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAW;AAC5F;;AAGA,MAAM,sCAAsB,IAAI,IAAI,CAAC,SAAS,QAAQ,CAAC;;;;;;AAOvD,SAAgB,qBAAqB,KAA6B;CAChE,MAAM,cAAc,gBAAgB,GAAG;CACvC,IAAI,CAAC,YAAY,QAAQ,YAAY,KAAK,WAAW,GAAG,GACtD,OAAO;CAGT,MAAM,EAAE,aAAa,IAAI,IAAI,YAAY,IAAI;CAC7C,OAAO,oBAAoB,IAAI,QAAQ,IAAI,cAAc;EAAE,MAAM;EAAO,QAAQ;CAAmB;AACrG;;;;;;;;;AAUA,SAAgB,kBAAkB,KAAa,YAA2C;CACxF,MAAM,cAAc,wBAAwB,GAAG;CAC/C,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO,cAAc,YAAY,MAAM,UAAU,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAClG;;;;;AAMA,SAAgB,cAAc,MAAc,YAAoC;CAC9E,OAAO,eAAe,QAAQ,OAAO,IAAI,MAAM,OAAO,UAAU;AAClE;;;;;;;;;;;;;;AAeA,SAAgB,wBAAwB,KAAa,YAA2C;CAC9F,MAAM,UAAU,qBAAqB,GAAG;CACxC,IAAI,CAAC,QAAQ,QAAQ,CAAC,QAAQ,KAAK,WAAW,GAAG,GAC/C,OAAO;CAET,OAAO,cAAc,QAAQ,MAAM,UAAU,IAAI;EAAE,MAAM;EAAO,QAAQ;CAAgB,IAAI;AAC9F;;;;;;;AAQA,SAAgB,aAAa,MAA8B;CACzD,IAAI,CAAC,MACH,OAAO;CAET,MAAM,cAAc,wBAAwB,IAAI;CAChD,IAAI,CAAC,YAAY,MACf,OAAO;CAET,OAAO;EAAE,UAAU;EAAW,OAAO,GAAG,mBAAmB,YAAY,KAAK;CAAE;AAChF;;;AAIA,MAAM,uBAAuB;;;;;;;;;;;;AAa7B,SAAS,OAAO,MAAsB;CACpC,MAAM,EAAE,aAAa,IAAI,IAAI,MAAM,oBAAoB;CACvD,OAAO,SAAS,QAAQ,QAAQ,EAAE,KAAK;AACzC;;AAGA,SAAS,uBAAuB,OAAwB;CACtD,KAAK,MAAM,aAAa,OAAO;EAC7B,MAAM,OAAO,UAAU,YAAY,CAAC,KAAK;EACzC,IAAI,QAAQ,MAAQ,SAAS,KAC3B,OAAO;CAEX;CACA,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore",
-  "version": "0.0.7",
+  "version": "0.0.10",
   "description": "FastStore AI Native component library built on Base UI with AI-editable styles",
   "license": "MIT",
   "homepage": "https://developers.vtex.com/docs/guides/faststore",
@@ -50,12 +50,16 @@
   },
   "files": [
     "dist",
+    "skills",
     "src/styles/tailwind.css",
     "CHANGELOG.md"
   ],
   "dependencies": {
     "@base-ui/react": "^1.3.0",
     "@graphql-typed-document-node/core": "^3.2.0",
+    "@vtex/country-forms": "1.14.0",
+    "@vtex/faststore-catalog": "0.0.10",
+    "esbuild": "~0.27.3",
     "graphql": "^16.13.1",
     "react-hook-form": "^7.85.0",
     "react-intl": "^10.1.22",