@vtex/faststore 0.0.5 → 0.0.6

package/dist/sdk/actions/analytics-action-provider.d.ts

@@ -0,0 +1,15 @@
+import { ActionProviderProps } from "./inject-actions.js";
+import { ReactNode } from "react";
+//#region src/sdk/actions/analytics-action-provider.d.ts
+export type AnalyticsActionProviderProps = ActionProviderProps;
+/**
+ * Compiler-emitted runtime wrapper for the `analytics` action namespace. The compiler wraps every
+ * element whose definition declares `actions: { analytics: [...] }` with
+ * `<AnalyticsActionProvider methods={[...]}>`, calls `useAnalyticsActions` once, narrows the
+ * surface to the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with
+ * any outer namespace provider, per `useInjectActions`) for `useActionsOverride` to read further
+ * down. A namespace a component does not declare is never wrapped, so its hook is never called.
+ */
+export declare function AnalyticsActionProvider(props: AnalyticsActionProviderProps): ReactNode;
+//#endregion
+//# sourceMappingURL=analytics-action-provider.d.ts.map

package/dist/sdk/actions/analytics-action-provider.js

@@ -0,0 +1,19 @@
+"use client";
+import { useAnalyticsActions } from "../analytics/use-analytics-actions.js";
+import { useInjectActions } from "./inject-actions.js";
+//#region src/sdk/actions/analytics-action-provider.tsx
+/**
+* Compiler-emitted runtime wrapper for the `analytics` action namespace. The compiler wraps every
+* element whose definition declares `actions: { analytics: [...] }` with
+* `<AnalyticsActionProvider methods={[...]}>`, calls `useAnalyticsActions` once, narrows the
+* surface to the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with
+* any outer namespace provider, per `useInjectActions`) for `useActionsOverride` to read further
+* down. A namespace a component does not declare is never wrapped, so its hook is never called.
+*/
+function AnalyticsActionProvider(props) {
+	return useInjectActions("analytics", useAnalyticsActions(), props);
+}
+//#endregion
+export { AnalyticsActionProvider };
+
+//# sourceMappingURL=analytics-action-provider.js.map

package/dist/sdk/actions/analytics-action-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-action-provider.js","names":[],"sources":["../../../src/sdk/actions/analytics-action-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { ReactNode } from 'react';\nimport { useAnalyticsActions } from '../analytics/use-analytics-actions.js';\nimport { type ActionProviderProps, useInjectActions } from './inject-actions.js';\n\nexport type AnalyticsActionProviderProps = ActionProviderProps;\n\n/**\n * Compiler-emitted runtime wrapper for the `analytics` action namespace. The compiler wraps every\n * element whose definition declares `actions: { analytics: [...] }` with\n * `<AnalyticsActionProvider methods={[...]}>`, calls `useAnalyticsActions` once, narrows the\n * surface to the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with\n * any outer namespace provider, per `useInjectActions`) for `useActionsOverride` to read further\n * down. A namespace a component does not declare is never wrapped, so its hook is never called.\n */\nexport function AnalyticsActionProvider(props: AnalyticsActionProviderProps): ReactNode {\n  return useInjectActions('analytics', useAnalyticsActions(), props);\n}\n"],"mappings":";;;;;;;;;;;;AAgBA,SAAgB,wBAAwB,OAAgD;CACtF,OAAO,iBAAiB,aAAa,oBAAoB,GAAG,KAAK;AACnE"}

package/dist/sdk/actions/index.d.ts

@@ -1,7 +1,9 @@
 import { ComponentActions } from "./types.js";
+import { AnalyticsActionProvider, AnalyticsActionProviderProps } from "./analytics-action-provider.js";
 import { CartActionProvider, CartActionProviderProps } from "./cart-action-provider.js";
 import { IdentityActionProvider, IdentityActionProviderProps } from "./identity-action-provider.js";
+import { PaymentActionProvider, PaymentActionProviderProps } from "./payment-action-provider.js";
 import { RegionActionProvider, RegionActionProviderProps } from "./region-action-provider.js";
 import { SessionActionProvider, SessionActionProviderProps } from "./session-action-provider.js";
 import { ShippingActionProvider, ShippingActionProviderProps } from "./shipping-action-provider.js";
-export { CartActionProvider, type CartActionProviderProps, IdentityActionProvider, type IdentityActionProviderProps, RegionActionProvider, type RegionActionProviderProps, SessionActionProvider, type SessionActionProviderProps, ShippingActionProvider, type ShippingActionProviderProps };
+export { AnalyticsActionProvider, type AnalyticsActionProviderProps, CartActionProvider, type CartActionProviderProps, IdentityActionProvider, type IdentityActionProviderProps, PaymentActionProvider, type PaymentActionProviderProps, RegionActionProvider, type RegionActionProviderProps, SessionActionProvider, type SessionActionProviderProps, ShippingActionProvider, type ShippingActionProviderProps };

package/dist/sdk/actions/index.js

@@ -1,6 +1,8 @@
+import { AnalyticsActionProvider } from "./analytics-action-provider.js";
 import { CartActionProvider } from "./cart-action-provider.js";
 import { IdentityActionProvider } from "./identity-action-provider.js";
+import { PaymentActionProvider } from "./payment-action-provider.js";
 import { RegionActionProvider } from "./region-action-provider.js";
 import { SessionActionProvider } from "./session-action-provider.js";
 import { ShippingActionProvider } from "./shipping-action-provider.js";
-export { CartActionProvider, IdentityActionProvider, RegionActionProvider, SessionActionProvider, ShippingActionProvider };
+export { AnalyticsActionProvider, CartActionProvider, IdentityActionProvider, PaymentActionProvider, RegionActionProvider, SessionActionProvider, ShippingActionProvider };

package/dist/sdk/actions/payment-action-provider.d.ts

@@ -0,0 +1,22 @@
+import { ActionProviderProps } from "./inject-actions.js";
+import { ReactNode } from "react";
+//#region src/sdk/actions/payment-action-provider.d.ts
+export type PaymentActionProviderProps = ActionProviderProps;
+/**
+ * Compiler-emitted runtime wrapper for the `payment` action namespace. The compiler wraps every
+ * element whose definition declares `actions: { payment: [...] }` with
+ * `<PaymentActionProvider methods={[...]}>`, calls `usePaymentActions` once, narrows the surface to
+ * the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with any outer
+ * namespace provider, per `useInjectActions`) for `useActionsOverride` to read further down. A
+ * namespace a component does not declare is never wrapped, so its hook is never called
+ * (specs/actions.md FR-6).
+ *
+ * Narrowing matters more here than elsewhere: a component that declares only `setMethod` never receives
+ * `sendPayments`, because its own provider replaces the whole `payment` namespace an outer provider
+ * published (specs/payment-action-namespace.md, Decision 5). Context does not narrow a component that
+ * declares no `payment` method at all: rendered inside one that does, it can read the outer set
+ * (specs/sfs-3395-action-provider-context-delivery.md, Decision 2).
+ */
+export declare function PaymentActionProvider(props: PaymentActionProviderProps): ReactNode;
+//#endregion
+//# sourceMappingURL=payment-action-provider.d.ts.map

package/dist/sdk/actions/payment-action-provider.js

@@ -0,0 +1,26 @@
+"use client";
+import { useInjectActions } from "./inject-actions.js";
+import { usePaymentActions } from "../payment/use-payment-actions.js";
+//#region src/sdk/actions/payment-action-provider.tsx
+/**
+* Compiler-emitted runtime wrapper for the `payment` action namespace. The compiler wraps every
+* element whose definition declares `actions: { payment: [...] }` with
+* `<PaymentActionProvider methods={[...]}>`, calls `usePaymentActions` once, narrows the surface to
+* the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with any outer
+* namespace provider, per `useInjectActions`) for `useActionsOverride` to read further down. A
+* namespace a component does not declare is never wrapped, so its hook is never called
+* (specs/actions.md FR-6).
+*
+* Narrowing matters more here than elsewhere: a component that declares only `setMethod` never receives
+* `sendPayments`, because its own provider replaces the whole `payment` namespace an outer provider
+* published (specs/payment-action-namespace.md, Decision 5). Context does not narrow a component that
+* declares no `payment` method at all: rendered inside one that does, it can read the outer set
+* (specs/sfs-3395-action-provider-context-delivery.md, Decision 2).
+*/
+function PaymentActionProvider(props) {
+	return useInjectActions("payment", usePaymentActions(), props);
+}
+//#endregion
+export { PaymentActionProvider };
+
+//# sourceMappingURL=payment-action-provider.js.map

package/dist/sdk/actions/payment-action-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-action-provider.js","names":[],"sources":["../../../src/sdk/actions/payment-action-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { ReactNode } from 'react';\nimport { usePaymentActions } from '../payment/use-payment-actions.js';\nimport { type ActionProviderProps, useInjectActions } from './inject-actions.js';\n\nexport type PaymentActionProviderProps = ActionProviderProps;\n\n/**\n * Compiler-emitted runtime wrapper for the `payment` action namespace. The compiler wraps every\n * element whose definition declares `actions: { payment: [...] }` with\n * `<PaymentActionProvider methods={[...]}>`, calls `usePaymentActions` once, narrows the surface to\n * the declared `methods`, and publishes it through `ActionsOverrideContext` (merging with any outer\n * namespace provider, per `useInjectActions`) for `useActionsOverride` to read further down. A\n * namespace a component does not declare is never wrapped, so its hook is never called\n * (specs/actions.md FR-6).\n *\n * Narrowing matters more here than elsewhere: a component that declares only `setMethod` never receives\n * `sendPayments`, because its own provider replaces the whole `payment` namespace an outer provider\n * published (specs/payment-action-namespace.md, Decision 5). Context does not narrow a component that\n * declares no `payment` method at all: rendered inside one that does, it can read the outer set\n * (specs/sfs-3395-action-provider-context-delivery.md, Decision 2).\n */\nexport function PaymentActionProvider(props: PaymentActionProviderProps): ReactNode {\n  return useInjectActions('payment', usePaymentActions(), props);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,sBAAsB,OAA8C;CAClF,OAAO,iBAAiB,WAAW,kBAAkB,GAAG,KAAK;AAC/D"}

package/dist/sdk/actions/types.d.ts

@@ -1,5 +1,7 @@
+import { AnalyticsActions } from "../analytics/use-analytics-actions.js";
 import { CartActions } from "../cart/use-cart-actions.js";
 import { IdentityActions } from "../identity/use-identity-actions.js";
+import { PaymentActions } from "../payment/use-payment-actions.js";
 import { RegionActions } from "../region/use-region-actions.js";
 import { SessionActions } from "../session/use-session-actions.js";
 import { ShippingActions } from "../shipping/use-shipping-actions.js";
@@ -7,12 +9,14 @@ import { ShippingActions } from "../shipping/use-shipping-actions.js";
 /**
  * The `$actions` prop the compiler injects (and `mockAction` builds for tests). Each namespace is
  * optional and each method is optional within it, because a component only receives the methods it
- * declared under `actions: { ... }`. Ships the `cart`, `identity`, `region`, `session`, and
- * `shipping` namespaces.
+ * declared under `actions: { ... }`. Ships the `analytics`, `cart`, `identity`, `payment`, `region`,
+ * `session`, and `shipping` namespaces.
  */
 export type ComponentActions = {
+  analytics?: Partial<AnalyticsActions>;
   cart?: Partial<CartActions>;
   identity?: Partial<IdentityActions>;
+  payment?: Partial<PaymentActions>;
   region?: Partial<RegionActions>;
   session?: Partial<SessionActions>;
   shipping?: Partial<ShippingActions>;

package/dist/sdk/analytics/analytics-destination.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from "react";
+//#region src/sdk/analytics/analytics-destination.d.ts
+/**
+ * Configurable analytics destination (specs/make-the-analytics-destination-configurable-for.md;
+ * credit-card epic T120; RFC `docs/features/credit-card/rfc.md` § D14 — Analytics events
+ * (cross-cutting)). `use-analytics-actions.ts`'s `pushToDataLayer` used to hardcode
+ * `window.dataLayer`. This module narrows "configurable destination" to the *name* of the
+ * `window` array the two standard payment events (`add_payment_info`, `purchase`) are pushed to —
+ * not a vendor id, not a transport, not a fan-out list. The payload and its GA4 shape are
+ * unchanged; only the array it lands in differs.
+ *
+ * Resolution precedence: the nearest `AnalyticsDestinationProvider` -> the build-inlined
+ * `process.env.NEXT_PUBLIC_ANALYTICS_DESTINATION` -> `DEFAULT_ANALYTICS_DESTINATION`. Resolution
+ * happens at call time, inside `track` (see `use-analytics-actions.ts`) — never once at module
+ * scope — so a build-time env change and a test's `vi.stubEnv` are both observed without a remount.
+ *
+ * A destination that is not a plain identifier, or that names `__proto__` / `constructor` /
+ * `prototype`, is never written to `window`: it is rejected, logged once, and resolution falls
+ * back to the default instead. A misconfiguration can only cost an analytics event — it can never
+ * block payment submission or order placement, the same invariant `use-analytics-actions.ts`
+ * already holds.
+ */
+/** The name of the `window` property the standard analytics events are pushed to. */
+export type AnalyticsDestination = string;
+export type AnalyticsDestinationProviderProps = Readonly<{
+  /**
+   * The `window` property name events are pushed to. Must be a build-time or merchant-authored
+   * constant — never wire this from user input. The identifier pattern and denylist block the
+   * known prototype-pollution keys, but a value that passes validation could still name a live,
+   * load-bearing global (`__NEXT_P`, `_gaq`, or a merchant queue with a hijacked `push`).
+   */
+  destination: AnalyticsDestination;
+  children: ReactNode;
+}>;
+/**
+ * Publishes a destination to the subtree — for a host that renders the components by hand (an
+ * embedder, a Storybook story, a test) and wants to supply or override the destination in React
+ * rather than through the build. Optional: an unprovided tree is the normal case, and the nearest
+ * provider wins over any outer one.
+ */
+export declare function AnalyticsDestinationProvider({ destination, children }: AnalyticsDestinationProviderProps): ReactNode;
+//#endregion
+//# sourceMappingURL=analytics-destination.d.ts.map

package/dist/sdk/analytics/analytics-destination.js

@@ -0,0 +1,90 @@
+"use client";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/sdk/analytics/analytics-destination.tsx
+/** The sink every store used before this task, and the fallback for anything invalid. */
+const DEFAULT_ANALYTICS_DESTINATION = "dataLayer";
+/** A plain property name: no dots, no dashes, no spaces, no leading digit. */
+const DESTINATION_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Never written to `window`, whatever the build says. */
+const UNSAFE_DESTINATION_KEYS = [
+	"__proto__",
+	"constructor",
+	"prototype"
+];
+/**
+* A plain, safe `window` property name: matches the identifier pattern and is absent from the
+* unsafe-key denylist. Operates on the value exactly as given — trimming, and treating
+* empty-after-trim as unset, are `resolveAnalyticsDestination`'s job, not this predicate's.
+*/
+function isValidAnalyticsDestination(value) {
+	return DESTINATION_PATTERN.test(value) && !UNSAFE_DESTINATION_KEYS.some((unsafeKey) => unsafeKey === value);
+}
+/**
+* Returns the first non-empty-after-trim candidate in precedence order — `override`, then the
+* build-inlined env var — together with whether that candidate is valid. Resolution never walks
+* past that first configured candidate: an invalid `override` is never rescued by a valid env
+* var, it falls straight through to `resolveAnalyticsDestination`'s default, exactly like an
+* invalid env var with no override does. Validation itself is `isValidAnalyticsDestination`'s
+* job — this function only picks which single candidate gets validated.
+*/
+function firstConfiguredCandidate(override) {
+	const envValue = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_ANALYTICS_DESTINATION : void 0;
+	for (const candidate of [override, envValue]) {
+		if (candidate === void 0) continue;
+		const trimmed = candidate.trim();
+		if (trimmed.length === 0) continue;
+		return {
+			value: trimmed,
+			valid: isValidAnalyticsDestination(trimmed)
+		};
+	}
+}
+/**
+* Precedence: `override` (context) -> NEXT_PUBLIC_ANALYTICS_DESTINATION -> DEFAULT.
+* Trims; treats empty-after-trim as unset. A present-but-invalid value logs once via
+* console.error and resolves to DEFAULT. Never throws.
+*
+* `hasLoggedRejection`, when passed, is a mutable latch: the first rejection while it is `false`
+* logs and flips it to `true`; every later rejection while it stays `true` is silent. Omit it —
+* every direct/unit-test call does — to log every rejection. `useAnalyticsActions` is the only
+* caller that owns one, scoped to its own hook instance via `useRef`, so "logs once" means once
+* per mounted `useAnalyticsActions()`, not once for the whole page.
+*/
+function resolveAnalyticsDestination(options) {
+	const outcome = firstConfiguredCandidate(options?.override);
+	if (outcome === void 0) return DEFAULT_ANALYTICS_DESTINATION;
+	if (outcome.valid) return outcome.value;
+	const hasLoggedRejection = options?.hasLoggedRejection;
+	if (!hasLoggedRejection?.current) {
+		const message = `[analytics.track] ${JSON.stringify(outcome.value)} is not a valid analytics destination; falling back to ${JSON.stringify(DEFAULT_ANALYTICS_DESTINATION)}`;
+		console.error(message);
+		if (hasLoggedRejection) hasLoggedRejection.current = true;
+	}
+	return DEFAULT_ANALYTICS_DESTINATION;
+}
+/**
+* Private, so the only read is `useAnalyticsDestination` — which, unlike `useStorefrontContext`,
+* never throws when unprovided: an unprovided tree is the normal case here, not a bug.
+*/
+const AnalyticsDestinationContext = createContext(void 0);
+/**
+* Publishes a destination to the subtree — for a host that renders the components by hand (an
+* embedder, a Storybook story, a test) and wants to supply or override the destination in React
+* rather than through the build. Optional: an unprovided tree is the normal case, and the nearest
+* provider wins over any outer one.
+*/
+function AnalyticsDestinationProvider({ destination, children }) {
+	return /* @__PURE__ */ jsx(AnalyticsDestinationContext.Provider, {
+		value: destination,
+		children
+	});
+}
+/** The nearest provided destination, or `undefined` when no provider is in the tree. Never throws. */
+function useAnalyticsDestination() {
+	return useContext(AnalyticsDestinationContext);
+}
+//#endregion
+export { AnalyticsDestinationProvider, DEFAULT_ANALYTICS_DESTINATION, isValidAnalyticsDestination, resolveAnalyticsDestination, useAnalyticsDestination };
+
+//# sourceMappingURL=analytics-destination.js.map

package/dist/sdk/analytics/analytics-destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-destination.js","names":[],"sources":["../../../src/sdk/analytics/analytics-destination.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext } from 'react';\n\n/**\n * Configurable analytics destination (specs/make-the-analytics-destination-configurable-for.md;\n * credit-card epic T120; RFC `docs/features/credit-card/rfc.md` § D14 — Analytics events\n * (cross-cutting)). `use-analytics-actions.ts`'s `pushToDataLayer` used to hardcode\n * `window.dataLayer`. This module narrows \"configurable destination\" to the *name* of the\n * `window` array the two standard payment events (`add_payment_info`, `purchase`) are pushed to —\n * not a vendor id, not a transport, not a fan-out list. The payload and its GA4 shape are\n * unchanged; only the array it lands in differs.\n *\n * Resolution precedence: the nearest `AnalyticsDestinationProvider` -> the build-inlined\n * `process.env.NEXT_PUBLIC_ANALYTICS_DESTINATION` -> `DEFAULT_ANALYTICS_DESTINATION`. Resolution\n * happens at call time, inside `track` (see `use-analytics-actions.ts`) — never once at module\n * scope — so a build-time env change and a test's `vi.stubEnv` are both observed without a remount.\n *\n * A destination that is not a plain identifier, or that names `__proto__` / `constructor` /\n * `prototype`, is never written to `window`: it is rejected, logged once, and resolution falls\n * back to the default instead. A misconfiguration can only cost an analytics event — it can never\n * block payment submission or order placement, the same invariant `use-analytics-actions.ts`\n * already holds.\n */\n\n/** The name of the `window` property the standard analytics events are pushed to. */\nexport type AnalyticsDestination = string;\n\n/** The sink every store used before this task, and the fallback for anything invalid. */\nexport const DEFAULT_ANALYTICS_DESTINATION = 'dataLayer';\n\n/** A plain property name: no dots, no dashes, no spaces, no leading digit. */\nconst DESTINATION_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/** Never written to `window`, whatever the build says. */\nconst UNSAFE_DESTINATION_KEYS = ['__proto__', 'constructor', 'prototype'] as const;\n\n/**\n * A plain, safe `window` property name: matches the identifier pattern and is absent from the\n * unsafe-key denylist. Operates on the value exactly as given — trimming, and treating\n * empty-after-trim as unset, are `resolveAnalyticsDestination`'s job, not this predicate's.\n */\nexport function isValidAnalyticsDestination(value: string): boolean {\n  return DESTINATION_PATTERN.test(value) && !UNSAFE_DESTINATION_KEYS.some((unsafeKey) => unsafeKey === value);\n}\n\n/** The first configured candidate in precedence order, paired with whether it is valid. */\ntype CandidateOutcome = Readonly<{ value: string; valid: boolean }>;\n\n/**\n * Returns the first non-empty-after-trim candidate in precedence order — `override`, then the\n * build-inlined env var — together with whether that candidate is valid. Resolution never walks\n * past that first configured candidate: an invalid `override` is never rescued by a valid env\n * var, it falls straight through to `resolveAnalyticsDestination`'s default, exactly like an\n * invalid env var with no override does. Validation itself is `isValidAnalyticsDestination`'s\n * job — this function only picks which single candidate gets validated.\n */\nfunction firstConfiguredCandidate(override: string | undefined): CandidateOutcome | undefined {\n  // `typeof process !== 'undefined'` guards a client bundle with no `process` shim at all (a\n  // Vite/Rollup/esbuild embedder, US-2's stated host) — unlike a direct read, `typeof` never\n  // throws when the identifier doesn't exist at all. The member expression itself stays literal\n  // so Next's build-time inlining can still statically replace it (Decision 5).\n  const envValue = typeof process !== 'undefined' ? process.env.NEXT_PUBLIC_ANALYTICS_DESTINATION : undefined;\n\n  for (const candidate of [override, envValue]) {\n    if (candidate === undefined) continue;\n    const trimmed = candidate.trim();\n    if (trimmed.length === 0) continue;\n    return { value: trimmed, valid: isValidAnalyticsDestination(trimmed) };\n  }\n  return undefined;\n}\n\n/**\n * Precedence: `override` (context) -> NEXT_PUBLIC_ANALYTICS_DESTINATION -> DEFAULT.\n * Trims; treats empty-after-trim as unset. A present-but-invalid value logs once via\n * console.error and resolves to DEFAULT. Never throws.\n *\n * `hasLoggedRejection`, when passed, is a mutable latch: the first rejection while it is `false`\n * logs and flips it to `true`; every later rejection while it stays `true` is silent. Omit it —\n * every direct/unit-test call does — to log every rejection. `useAnalyticsActions` is the only\n * caller that owns one, scoped to its own hook instance via `useRef`, so \"logs once\" means once\n * per mounted `useAnalyticsActions()`, not once for the whole page.\n */\nexport function resolveAnalyticsDestination(options?: {\n  override?: string;\n  hasLoggedRejection?: { current: boolean };\n}): AnalyticsDestination {\n  const outcome = firstConfiguredCandidate(options?.override);\n  if (outcome === undefined) return DEFAULT_ANALYTICS_DESTINATION;\n  if (outcome.valid) return outcome.value;\n\n  const hasLoggedRejection = options?.hasLoggedRejection;\n  if (!hasLoggedRejection?.current) {\n    const message =\n      `[analytics.track] ${JSON.stringify(outcome.value)} is not a valid analytics destination; ` +\n      `falling back to ${JSON.stringify(DEFAULT_ANALYTICS_DESTINATION)}`;\n    console.error(message);\n    if (hasLoggedRejection) hasLoggedRejection.current = true;\n  }\n  return DEFAULT_ANALYTICS_DESTINATION;\n}\n\nexport type AnalyticsDestinationProviderProps = Readonly<{\n  /**\n   * The `window` property name events are pushed to. Must be a build-time or merchant-authored\n   * constant — never wire this from user input. The identifier pattern and denylist block the\n   * known prototype-pollution keys, but a value that passes validation could still name a live,\n   * load-bearing global (`__NEXT_P`, `_gaq`, or a merchant queue with a hijacked `push`).\n   */\n  destination: AnalyticsDestination;\n  children: ReactNode;\n}>;\n\n/**\n * Private, so the only read is `useAnalyticsDestination` — which, unlike `useStorefrontContext`,\n * never throws when unprovided: an unprovided tree is the normal case here, not a bug.\n */\nconst AnalyticsDestinationContext = createContext<AnalyticsDestination | undefined>(undefined);\n\n/**\n * Publishes a destination to the subtree — for a host that renders the components by hand (an\n * embedder, a Storybook story, a test) and wants to supply or override the destination in React\n * rather than through the build. Optional: an unprovided tree is the normal case, and the nearest\n * provider wins over any outer one.\n */\nexport function AnalyticsDestinationProvider({ destination, children }: AnalyticsDestinationProviderProps): ReactNode {\n  return <AnalyticsDestinationContext.Provider value={destination}>{children}</AnalyticsDestinationContext.Provider>;\n}\n\n/** The nearest provided destination, or `undefined` when no provider is in the tree. Never throws. */\nexport function useAnalyticsDestination(): AnalyticsDestination | undefined {\n  return useContext(AnalyticsDestinationContext);\n}\n"],"mappings":";;;;;AA6BA,MAAa,gCAAgC;;AAG7C,MAAM,sBAAsB;;AAG5B,MAAM,0BAA0B;CAAC;CAAa;CAAe;AAAW;;;;;;AAOxE,SAAgB,4BAA4B,OAAwB;CAClE,OAAO,oBAAoB,KAAK,KAAK,KAAK,CAAC,wBAAwB,MAAM,cAAc,cAAc,KAAK;AAC5G;;;;;;;;;AAaA,SAAS,yBAAyB,UAA4D;CAK5F,MAAM,WAAW,OAAO,YAAY,cAAc,QAAQ,IAAI,oCAAoC,KAAA;CAElG,KAAK,MAAM,aAAa,CAAC,UAAU,QAAQ,GAAG;EAC5C,IAAI,cAAc,KAAA,GAAW;EAC7B,MAAM,UAAU,UAAU,KAAK;EAC/B,IAAI,QAAQ,WAAW,GAAG;EAC1B,OAAO;GAAE,OAAO;GAAS,OAAO,4BAA4B,OAAO;EAAE;CACvE;AAEF;;;;;;;;;;;;AAaA,SAAgB,4BAA4B,SAGnB;CACvB,MAAM,UAAU,yBAAyB,SAAS,QAAQ;CAC1D,IAAI,YAAY,KAAA,GAAW,OAAO;CAClC,IAAI,QAAQ,OAAO,OAAO,QAAQ;CAElC,MAAM,qBAAqB,SAAS;CACpC,IAAI,CAAC,oBAAoB,SAAS;EAChC,MAAM,UACJ,qBAAqB,KAAK,UAAU,QAAQ,KAAK,EAAE,yDAChC,KAAK,UAAU,6BAA6B;EACjE,QAAQ,MAAM,OAAO;EACrB,IAAI,oBAAoB,mBAAmB,UAAU;CACvD;CACA,OAAO;AACT;;;;;AAiBA,MAAM,8BAA8B,cAAgD,KAAA,CAAS;;;;;;;AAQ7F,SAAgB,6BAA6B,EAAE,aAAa,YAA0D;CACpH,OAAO,oBAAC,4BAA4B,UAA7B;EAAsC,OAAO;EAAc;CAA+C,CAAA;AACnH;;AAGA,SAAgB,0BAA4D;CAC1E,OAAO,WAAW,2BAA2B;AAC/C"}

package/dist/sdk/analytics/use-analytics-actions.d.ts

@@ -0,0 +1,57 @@
+import "../../core/dist/index.js";
+//#region src/sdk/analytics/use-analytics-actions.d.ts
+/**
+ * The `analytics` action namespace (specs/analytics-events.md) — a dispatcher-flavor namespace
+ * (docs/storefront-core/adr-0010-actions-own-the-write-side.md; docs/storefront-core/rfc-actions.md
+ * § "Three binding flavors") that pushes the two standard payment analytics events,
+ * `add_payment_info` and `purchase`, to a `window` array — `window.dataLayer` by default, the
+ * GTM/GA4-recognizable event convention. It never touches the Apollo cache, never issues a GraphQL
+ * operation, and never throws: a broken tag-manager script can never block payment submission or
+ * order placement.
+ *
+ * The destination array is configurable at build time
+ * (specs/make-the-analytics-destination-configurable-for.md; T120) — see
+ * `./analytics-destination.js` for the resolution precedence, validation, and the
+ * `AnalyticsDestinationProvider`. The pushed entry's shape is a data *contract* (a well-known
+ * browser-global array shape), not a *provider* — no vendor SDK, no server call. A future
+ * platform/foundation epic may replace this sink with a real `AnalyticsContext`; the
+ * `track(event: AnalyticsEvent): void` signature and `AnalyticsActions` type are the stable public
+ * contract every call site depends on until then (US-4).
+ */
+export type AnalyticsMoney = Readonly<{
+  amount: number;
+  currencyCode: string;
+}>;
+export type AnalyticsLineItem = Readonly<{
+  sku: string;
+  name: string;
+  price: AnalyticsMoney;
+  quantity: number;
+}>;
+/** Dispatched by T7's CardEntry, before opening the transaction. */
+export type AddPaymentInfoEvent = Readonly<{
+  name: 'add_payment_info';
+  value: AnalyticsMoney;
+  /**
+   * Derived from the selected method's `groupName` at the moment this fires (T140, Decision 5).
+   * Optional because the event fires on the cart total, before a method is necessarily selected —
+   * omitted rather than a guessed literal, so a downstream consumer never reads a false payment kind.
+   * `toEcommercePayload` below drops the corresponding key entirely when this is absent.
+   */
+  paymentType?: 'Credit Card' | 'Debit Card';
+  items?: readonly AnalyticsLineItem[];
+}>;
+/** Dispatched by T13's usePlaceOrder, after a successful gateway callback. */
+export type PurchaseEvent = Readonly<{
+  name: 'purchase';
+  transactionId: string;
+  value: AnalyticsMoney;
+  items?: readonly AnalyticsLineItem[];
+}>;
+export type AnalyticsEvent = AddPaymentInfoEvent | PurchaseEvent;
+export type AnalyticsActions = Readonly<{
+  /** Push a standard analytics event to window.dataLayer. Fire-and-forget; never throws. */
+  track: (event: AnalyticsEvent) => void;
+}>;
+//#endregion
+//# sourceMappingURL=use-analytics-actions.d.ts.map

package/dist/sdk/analytics/use-analytics-actions.js

@@ -0,0 +1,108 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { DEFAULT_ANALYTICS_DESTINATION, resolveAnalyticsDestination, useAnalyticsDestination } from "./analytics-destination.js";
+import { useCallback, useMemo, useRef } from "react";
+//#region src/sdk/analytics/use-analytics-actions.ts
+function toEcommerceItems(items) {
+	return (items ?? []).map((item) => ({
+		item_id: item.sku,
+		item_name: item.name,
+		price: item.price.amount,
+		quantity: item.quantity
+	}));
+}
+function toEcommercePayload(event) {
+	if (event.name === "add_payment_info") return {
+		currency: event.value.currencyCode,
+		value: event.value.amount,
+		...event.paymentType !== void 0 ? { payment_type: event.paymentType } : {},
+		items: toEcommerceItems(event.items)
+	};
+	return {
+		transaction_id: event.transactionId,
+		currency: event.value.currencyCode,
+		value: event.value.amount,
+		items: toEcommerceItems(event.items)
+	};
+}
+function pushToDataLayer(event, destination) {
+	if (typeof window === "undefined") return;
+	let layer = Reflect.get(window, destination);
+	if (layer === void 0) {
+		layer = [];
+		Reflect.set(window, destination, layer);
+	} else if (!Array.isArray(layer)) {
+		console.error(`[analytics.track] window.${destination} already exists and is not an array; the event was dropped`);
+		return;
+	}
+	layer.push({
+		event: event.name,
+		ecommerce: toEcommercePayload(event)
+	});
+}
+/**
+* The `analytics` namespace hook. Registered with the first-party action registry via
+* `analyticsActions` below; the compiler-emitted `AnalyticsActionProvider` calls it and threads
+* the narrowed methods into each consumer's `$actions.analytics`. Dispatcher flavor: no
+* `useMutation`, no cache read or write (ADR-0010). Fire-and-forget — `track` never throws, so a
+* broken tag-manager script can never block payment submission or order placement.
+*/
+function useAnalyticsActions() {
+	const override = useAnalyticsDestination();
+	const hasLoggedRejectionRef = useRef(false);
+	const track = useCallback((event) => {
+		if (typeof window === "undefined") return;
+		let destination = DEFAULT_ANALYTICS_DESTINATION;
+		try {
+			destination = resolveAnalyticsDestination({
+				override,
+				hasLoggedRejection: hasLoggedRejectionRef
+			});
+			pushToDataLayer(event, destination);
+		} catch (error) {
+			console.error(`[analytics.track] window.${destination} push failed`, error);
+		}
+	}, [override]);
+	return useMemo(() => ({ track }), [track]);
+}
+defineActions({
+	namespace: "analytics",
+	description: "Dispatcher-flavor namespace that pushes standard add_payment_info / purchase events to window.dataLayer. Never touches the Apollo cache.",
+	provider: {
+		name: "AnalyticsActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: { track: {
+		description: "Push a standard analytics event (add_payment_info | purchase) to window.dataLayer. Fire-and-forget; never throws.",
+		payload: [
+			{
+				name: "name",
+				type: "string"
+			},
+			{
+				name: "currencyCode",
+				type: "string"
+			},
+			{
+				name: "amount",
+				type: "number"
+			},
+			{
+				name: "paymentType",
+				type: "string",
+				optional: true
+			},
+			{
+				name: "transactionId",
+				type: "string",
+				optional: true
+			}
+		]
+	} },
+	use: useAnalyticsActions
+});
+//#endregion
+export { useAnalyticsActions };
+
+//# sourceMappingURL=use-analytics-actions.js.map

package/dist/sdk/analytics/use-analytics-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-analytics-actions.js","names":[],"sources":["../../../src/sdk/analytics/use-analytics-actions.ts"],"sourcesContent":["'use client';\n\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo, useRef } from 'react';\nimport {\n  type AnalyticsDestination,\n  DEFAULT_ANALYTICS_DESTINATION,\n  resolveAnalyticsDestination,\n  useAnalyticsDestination,\n} from './analytics-destination.js';\n\n/**\n * The `analytics` action namespace (specs/analytics-events.md) — a dispatcher-flavor namespace\n * (docs/storefront-core/adr-0010-actions-own-the-write-side.md; docs/storefront-core/rfc-actions.md\n * § \"Three binding flavors\") that pushes the two standard payment analytics events,\n * `add_payment_info` and `purchase`, to a `window` array — `window.dataLayer` by default, the\n * GTM/GA4-recognizable event convention. It never touches the Apollo cache, never issues a GraphQL\n * operation, and never throws: a broken tag-manager script can never block payment submission or\n * order placement.\n *\n * The destination array is configurable at build time\n * (specs/make-the-analytics-destination-configurable-for.md; T120) — see\n * `./analytics-destination.js` for the resolution precedence, validation, and the\n * `AnalyticsDestinationProvider`. The pushed entry's shape is a data *contract* (a well-known\n * browser-global array shape), not a *provider* — no vendor SDK, no server call. A future\n * platform/foundation epic may replace this sink with a real `AnalyticsContext`; the\n * `track(event: AnalyticsEvent): void` signature and `AnalyticsActions` type are the stable public\n * contract every call site depends on until then (US-4).\n */\n\nexport type AnalyticsMoney = Readonly<{\n  amount: number;\n  currencyCode: string;\n}>;\n\nexport type AnalyticsLineItem = Readonly<{\n  sku: string;\n  name: string;\n  price: AnalyticsMoney;\n  quantity: number;\n}>;\n\n/** Dispatched by T7's CardEntry, before opening the transaction. */\nexport type AddPaymentInfoEvent = Readonly<{\n  name: 'add_payment_info';\n  value: AnalyticsMoney;\n  /**\n   * Derived from the selected method's `groupName` at the moment this fires (T140, Decision 5).\n   * Optional because the event fires on the cart total, before a method is necessarily selected —\n   * omitted rather than a guessed literal, so a downstream consumer never reads a false payment kind.\n   * `toEcommercePayload` below drops the corresponding key entirely when this is absent.\n   */\n  paymentType?: 'Credit Card' | 'Debit Card';\n  items?: readonly AnalyticsLineItem[];\n}>;\n\n/** Dispatched by T13's usePlaceOrder, after a successful gateway callback. */\nexport type PurchaseEvent = Readonly<{\n  name: 'purchase';\n  transactionId: string;\n  value: AnalyticsMoney;\n  items?: readonly AnalyticsLineItem[];\n}>;\n\nexport type AnalyticsEvent = AddPaymentInfoEvent | PurchaseEvent;\n\nexport type AnalyticsActions = Readonly<{\n  /** Push a standard analytics event to window.dataLayer. Fire-and-forget; never throws. */\n  track: (event: AnalyticsEvent) => void;\n}>;\n\n/** The shape pushed onto window.dataLayer — GTM/GA4's own event convention. */\nexport type AnalyticsDataLayerEvent = Readonly<{\n  event: 'add_payment_info' | 'purchase';\n  ecommerce: Record<string, unknown>;\n}>;\n\nfunction toEcommerceItems(items: readonly AnalyticsLineItem[] | undefined) {\n  return (items ?? []).map((item) => ({\n    item_id: item.sku,\n    item_name: item.name,\n    price: item.price.amount,\n    quantity: item.quantity,\n  }));\n}\n\nfunction toEcommercePayload(event: AnalyticsEvent): Record<string, unknown> {\n  if (event.name === 'add_payment_info') {\n    return {\n      currency: event.value.currencyCode,\n      value: event.value.amount,\n      // T140, Decision 5: the key itself must be absent when `paymentType` is, not merely `undefined`\n      // — `pushToDataLayer` pushes this object as-is with no serialization step to strip it, and\n      // `'payment_type' in ecommerce` would otherwise still report true.\n      ...(event.paymentType !== undefined ? { payment_type: event.paymentType } : {}),\n      items: toEcommerceItems(event.items),\n    };\n  }\n  return {\n    transaction_id: event.transactionId,\n    currency: event.value.currencyCode,\n    value: event.value.amount,\n    items: toEcommerceItems(event.items),\n  };\n}\n\n// `Reflect.get`/`Reflect.set` below match `storefront-provider.tsx`'s existing pattern for a\n// dynamic `window` key — they are not a security mechanism. `Reflect.set(target, k, v)` invokes\n// an inherited setter and creates no own property, exactly like `window[k] = v` would; it adds no\n// hardening on its own. What actually blocks prototype pollution is\n// `isValidAnalyticsDestination`'s denylist and identifier pattern, checked by the caller before\n// `destination` ever reaches this function, plus the non-array guard immediately below.\n//\n// The cast below, not a `declare global` augmentation of `Window`, is what keeps this typed: a\n// global augmentation here would ship inside this package's own `.d.ts` output and hand every\n// consumer's `window.dataLayer` this package's narrow event union, wrong for a store that also\n// pushes its own GTM events (packages/components/scripts/dist-type-boundary.test.ts). `destination`\n// is a runtime string anyway — `Window` has nothing to look up a dynamic key against — so the local\n// cast is also the only type-safe option, not merely the non-leaking one.\nfunction pushToDataLayer(event: AnalyticsEvent, destination: AnalyticsDestination): void {\n  if (typeof window === 'undefined') return;\n\n  let layer = Reflect.get(window, destination) as AnalyticsDataLayerEvent[] | undefined;\n  if (layer === undefined) {\n    layer = [];\n    Reflect.set(window, destination, layer);\n  } else if (!Array.isArray(layer)) {\n    console.error(`[analytics.track] window.${destination} already exists and is not an array; the event was dropped`);\n    return;\n  }\n\n  layer.push({ event: event.name, ecommerce: toEcommercePayload(event) });\n}\n\n/**\n * The `analytics` namespace hook. Registered with the first-party action registry via\n * `analyticsActions` below; the compiler-emitted `AnalyticsActionProvider` calls it and threads\n * the narrowed methods into each consumer's `$actions.analytics`. Dispatcher flavor: no\n * `useMutation`, no cache read or write (ADR-0010). Fire-and-forget — `track` never throws, so a\n * broken tag-manager script can never block payment submission or order placement.\n */\nexport function useAnalyticsActions(): AnalyticsActions {\n  const override = useAnalyticsDestination();\n  // Scoped to this hook instance, not the module: \"logs once\" means once per mounted\n  // `useAnalyticsActions()`, so two independent call sites each still get their own first warning.\n  const hasLoggedRejectionRef = useRef(false);\n\n  const track = useCallback<AnalyticsActions['track']>(\n    (event) => {\n      // The SSR guard runs before any destination resolution is attempted — not just before the\n      // write. Preserved from the pre-T120 behaviour (US-3, \"SSR — no destination resolution\n      // attempted at all\").\n      if (typeof window === 'undefined') return;\n      let destination: AnalyticsDestination = DEFAULT_ANALYTICS_DESTINATION;\n      try {\n        destination = resolveAnalyticsDestination({\n          override,\n          hasLoggedRejection: hasLoggedRejectionRef,\n        });\n        pushToDataLayer(event, destination);\n      } catch (error) {\n        console.error(`[analytics.track] window.${destination} push failed`, error);\n      }\n    },\n    [override],\n  );\n\n  return useMemo(() => ({ track }), [track]);\n}\n\n/**\n * Declares the `analytics` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The\n * native catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit\n * `actions.json`; at runtime `AnalyticsActionProvider` calls `useAnalyticsActions` directly.\n *\n * The `payload` below is a flattened, best-effort scalar approximation of `AnalyticsEvent` for\n * catalog/docs tooling: `ActionPayloadField.type` supports only scalar primitives and cannot\n * express a discriminated union or a nested `items` array. The TS `AnalyticsEvent` union above is\n * the source of truth for the real call shape.\n */\nexport const analyticsActions = defineActions({\n  namespace: 'analytics',\n  description:\n    'Dispatcher-flavor namespace that pushes standard add_payment_info / purchase events to window.dataLayer. Never touches the Apollo cache.',\n  provider: { name: 'AnalyticsActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    track: {\n      description:\n        'Push a standard analytics event (add_payment_info | purchase) to window.dataLayer. Fire-and-forget; never throws.',\n      payload: [\n        { name: 'name', type: 'string' },\n        { name: 'currencyCode', type: 'string' },\n        { name: 'amount', type: 'number' },\n        { name: 'paymentType', type: 'string', optional: true },\n        { name: 'transactionId', type: 'string', optional: true },\n      ],\n    },\n  },\n  use: useAnalyticsActions,\n});\n"],"mappings":";;;;;;AA6EA,SAAS,iBAAiB,OAAiD;CACzE,QAAQ,SAAS,CAAC,EAAA,CAAG,KAAK,UAAU;EAClC,SAAS,KAAK;EACd,WAAW,KAAK;EAChB,OAAO,KAAK,MAAM;EAClB,UAAU,KAAK;CACjB,EAAE;AACJ;AAEA,SAAS,mBAAmB,OAAgD;CAC1E,IAAI,MAAM,SAAS,oBACjB,OAAO;EACL,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EAInB,GAAI,MAAM,gBAAgB,KAAA,IAAY,EAAE,cAAc,MAAM,YAAY,IAAI,CAAC;EAC7E,OAAO,iBAAiB,MAAM,KAAK;CACrC;CAEF,OAAO;EACL,gBAAgB,MAAM;EACtB,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EACnB,OAAO,iBAAiB,MAAM,KAAK;CACrC;AACF;AAeA,SAAS,gBAAgB,OAAuB,aAAyC;CACvF,IAAI,OAAO,WAAW,aAAa;CAEnC,IAAI,QAAQ,QAAQ,IAAI,QAAQ,WAAW;CAC3C,IAAI,UAAU,KAAA,GAAW;EACvB,QAAQ,CAAC;EACT,QAAQ,IAAI,QAAQ,aAAa,KAAK;CACxC,OAAO,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;EAChC,QAAQ,MAAM,4BAA4B,YAAY,2DAA2D;EACjH;CACF;CAEA,MAAM,KAAK;EAAE,OAAO,MAAM;EAAM,WAAW,mBAAmB,KAAK;CAAE,CAAC;AACxE;;;;;;;;AASA,SAAgB,sBAAwC;CACtD,MAAM,WAAW,wBAAwB;CAGzC,MAAM,wBAAwB,OAAO,KAAK;CAE1C,MAAM,QAAQ,aACX,UAAU;EAIT,IAAI,OAAO,WAAW,aAAa;EACnC,IAAI,cAAoC;EACxC,IAAI;GACF,cAAc,4BAA4B;IACxC;IACA,oBAAoB;GACtB,CAAC;GACD,gBAAgB,OAAO,WAAW;EACpC,SAAS,OAAO;GACd,QAAQ,MAAM,4BAA4B,YAAY,eAAe,KAAK;EAC5E;CACF,GACA,CAAC,QAAQ,CACX;CAEA,OAAO,eAAe,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC;AAC3C;AAagC,cAAc;CAC5C,WAAW;CACX,aACE;CACF,UAAU;EAAE,MAAM;EAA2B,YAAY;CAAkC;CAC3F,SAAS,EACP,OAAO;EACL,aACE;EACF,SAAS;GACP;IAAE,MAAM;IAAQ,MAAM;GAAS;GAC/B;IAAE,MAAM;IAAgB,MAAM;GAAS;GACvC;IAAE,MAAM;IAAU,MAAM;GAAS;GACjC;IAAE,MAAM;IAAe,MAAM;IAAU,UAAU;GAAK;GACtD;IAAE,MAAM;IAAiB,MAAM;IAAU,UAAU;GAAK;EAC1D;CACF,EACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/cart/use-cart-actions.js

@@ -1,8 +1,8 @@
 "use client";
 import { defineActions } from "../../core/dist/actions/registry.js";
 import "../../core/dist/index.js";
-import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
 import { CART_COUPON_APPLY, CART_COUPON_REMOVE, CART_ITEMS_REMOVE, CART_ITEM_ADD, CART_ITEM_QUANTITY_DECREASE, CART_ITEM_QUANTITY_INCREASE, CART_ITEM_REMOVE, CART_VALIDATE, CartFragment } from "./operations.js";
+import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
 import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildOptimisticRemoveItems } from "./optimistic.js";
 import { markAvailabilityFresh, trackCartWrite } from "./write-gate.js";
 import { useApolloClient, useMutation } from "@apollo/client/react";

package/dist/sdk/data/entity-resolution-context.js

@@ -0,0 +1,31 @@
+"use client";
+import { createContext, useContext } from "react";
+//#region src/sdk/data/entity-resolution-context.ts
+/**
+* Is the `$data` reaching this subtree the cache's own answer for the entity the page query
+* currently points at, or the server-rendered `fallbackData` standing in for one?
+*
+* `DataOverrideContext` carries the slice and cannot carry this: a fallback slice and a resolved
+* one are the same shape, and an entity whose saved values are genuinely absent looks exactly like
+* an entity whose cache read regressed. Only `useReactiveEntity` knows which of the two it just
+* handed down, so it is the one that publishes here — see its `resolved` return.
+*
+* Default `true`: with no reactive provider above, nothing is outstanding. Storybook, unit tests and
+* any tree handing `$data` over as a plain prop read the default and gate nothing, exactly as they
+* do with `useReactiveDataSettled`.
+*/
+const EntityResolutionContext = createContext(true);
+/**
+* Every entity slice composed into this subtree's `$data` is the cache's own answer.
+*
+* Unlike `useReactiveDataSettled`, this is not latched: it re-arms on its own whenever the entity
+* ref moves or its cache read stops being complete, which is the whole point — a latched page-level
+* signal cannot tell a form that the data under it has gone back to being a placeholder.
+*/
+function useEntityDataResolved() {
+	return useContext(EntityResolutionContext);
+}
+//#endregion
+export { EntityResolutionContext, useEntityDataResolved };
+
+//# sourceMappingURL=entity-resolution-context.js.map

package/dist/sdk/data/entity-resolution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-resolution-context.js","names":[],"sources":["../../../src/sdk/data/entity-resolution-context.ts"],"sourcesContent":["'use client';\n\nimport { createContext, useContext } from 'react';\n\n/**\n * Is the `$data` reaching this subtree the cache's own answer for the entity the page query\n * currently points at, or the server-rendered `fallbackData` standing in for one?\n *\n * `DataOverrideContext` carries the slice and cannot carry this: a fallback slice and a resolved\n * one are the same shape, and an entity whose saved values are genuinely absent looks exactly like\n * an entity whose cache read regressed. Only `useReactiveEntity` knows which of the two it just\n * handed down, so it is the one that publishes here — see its `resolved` return.\n *\n * Default `true`: with no reactive provider above, nothing is outstanding. Storybook, unit tests and\n * any tree handing `$data` over as a plain prop read the default and gate nothing, exactly as they\n * do with `useReactiveDataSettled`.\n */\nexport const EntityResolutionContext = createContext<boolean>(true);\n\n/**\n * Every entity slice composed into this subtree's `$data` is the cache's own answer.\n *\n * Unlike `useReactiveDataSettled`, this is not latched: it re-arms on its own whenever the entity\n * ref moves or its cache read stops being complete, which is the whole point — a latched page-level\n * signal cannot tell a form that the data under it has gone back to being a placeholder.\n */\nexport function useEntityDataResolved(): boolean {\n  return useContext(EntityResolutionContext);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAa,0BAA0B,cAAuB,IAAI;;;;;;;;AASlE,SAAgB,wBAAiC;CAC/C,OAAO,WAAW,uBAAuB;AAC3C"}

package/dist/sdk/data/entity-subscriber.js

@@ -1,7 +1,8 @@
 "use client";
 import { DataOverrideContext } from "./data-override-context.js";
+import { EntityResolutionContext } from "./entity-resolution-context.js";
 import { useReactiveEntity } from "./use-reactive-entity.js";
-import { useContext } from "react";
+import { useContext, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/data/entity-subscriber.tsx
 /**
@@ -12,14 +13,23 @@ import { jsx } from "react/jsx-runtime";
 */
 function EntitySubscriber({ entityFragment, fragmentName, rootField, fallbackData, reset, children }) {
 	const outer = useContext(DataOverrideContext);
-	const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
-	const value = reset ? { [rootField]: resolved } : {
+	const outerResolved = useContext(EntityResolutionContext);
+	const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
+	const value = useMemo(() => reset ? { [rootField]: data } : {
 		...outer && typeof outer === "object" ? outer : {},
-		[rootField]: resolved
-	};
-	return /* @__PURE__ */ jsx(DataOverrideContext, {
-		value,
-		children
+		[rootField]: data
+	}, [
+		reset,
+		rootField,
+		data,
+		outer
+	]);
+	return /* @__PURE__ */ jsx(EntityResolutionContext, {
+		value: reset ? resolved : outerResolved && resolved,
+		children: /* @__PURE__ */ jsx(DataOverrideContext, {
+			value,
+			children
+		})
 	});
 }
 //#endregion

package/dist/sdk/data/entity-subscriber.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity-subscriber.js","names":[],"sources":["../../../src/sdk/data/entity-subscriber.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } from 'react';\nimport { useContext } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { useReactiveEntity } from './use-reactive-entity.js';\n\nexport type EntitySubscriberProps = Readonly<{\n  /** Derived `fragment <X>_<EntityType> on <EntityType>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  /** Top-level field of the page query (e.g. 'cart') used to extract the entity ref, and the key\n   * under which the resolved slice is merged into the composed `$data` object. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  /**\n   * When `true`, RESETS the context to `{ [rootField]: resolved }`, discarding any outer\n   * `DataOverrideContext` value — this is the outermost subscriber of a component's nested stack,\n   * and prevents a parent component's `$data` from leaking into this component's descendants. When\n   * `false`, merges this subscriber's slice into the SAME-stack outer value instead.\n   */\n  reset: boolean;\n  children: ReactNode;\n}>;\n\n/**\n * Per-entity subscriber used internally by `MultipleReactiveDataProvider` to compose several\n * entities' cache slices into one keyed `$data` object for a single component. Resolves its own\n * slice exactly like `ReactiveDataProvider` (see `useReactiveEntity`), then merges it under\n * `rootField` into the outer `DataOverrideContext` value.\n */\nexport function EntitySubscriber({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  reset,\n  children,\n}: EntitySubscriberProps): ReactNode {\n  const outer = useContext(DataOverrideContext);\n  const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  const value = reset\n    ? { [rootField]: resolved }\n    : { ...(outer && typeof outer === 'object' ? outer : {}), [rootField]: resolved };\n\n  return <DataOverrideContext value={value}>{children}</DataOverrideContext>;\n}\n"],"mappings":";;;;;;;;;;;;AAkCA,SAAgB,iBAAiB,EAC/B,gBACA,cACA,WACA,cACA,OACA,YACmC;CACnC,MAAM,QAAQ,WAAW,mBAAmB;CAC5C,MAAM,WAAW,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAExF,MAAM,QAAQ,QACV,GAAG,YAAY,SAAS,IACxB;EAAE,GAAI,SAAS,OAAO,UAAU,WAAW,QAAQ,CAAC;GAAK,YAAY;CAAS;CAElF,OAAO,oBAAC,qBAAD;EAA4B;EAAQ;CAA8B,CAAA;AAC3E"}
+{"version":3,"file":"entity-subscriber.js","names":[],"sources":["../../../src/sdk/data/entity-subscriber.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } from 'react';\nimport { useContext, useMemo } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { EntityResolutionContext } from './entity-resolution-context.js';\nimport { useReactiveEntity } from './use-reactive-entity.js';\n\nexport type EntitySubscriberProps = Readonly<{\n  /** Derived `fragment <X>_<EntityType> on <EntityType>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  /** Top-level field of the page query (e.g. 'cart') used to extract the entity ref, and the key\n   * under which the resolved slice is merged into the composed `$data` object. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  /**\n   * When `true`, RESETS the context to `{ [rootField]: resolved }`, discarding any outer\n   * `DataOverrideContext` value — this is the outermost subscriber of a component's nested stack,\n   * and prevents a parent component's `$data` from leaking into this component's descendants. When\n   * `false`, merges this subscriber's slice into the SAME-stack outer value instead.\n   */\n  reset: boolean;\n  children: ReactNode;\n}>;\n\n/**\n * Per-entity subscriber used internally by `MultipleReactiveDataProvider` to compose several\n * entities' cache slices into one keyed `$data` object for a single component. Resolves its own\n * slice exactly like `ReactiveDataProvider` (see `useReactiveEntity`), then merges it under\n * `rootField` into the outer `DataOverrideContext` value.\n */\nexport function EntitySubscriber({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  reset,\n  children,\n}: EntitySubscriberProps): ReactNode {\n  const outer = useContext(DataOverrideContext);\n  const outerResolved = useContext(EntityResolutionContext);\n  const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  // Memoised because this object is the context value: a fresh identity on every render makes every\n  // consumer below re-render, and in a form that is every keystroke. Its two sibling providers pass a\n  // stable reference already.\n  const value = useMemo(\n    () => (reset ? { [rootField]: data } : { ...(outer && typeof outer === 'object' ? outer : {}), [rootField]: data }),\n    [reset, rootField, data, outer],\n  );\n\n  // Mirrors the data merge exactly: the composed `$data` is resolved only when every slice merged\n  // into it is. `reset` discards the outer verdict for the same reason it discards the outer value —\n  // that verdict belongs to an ancestor component's own entities, not to this component's.\n  const resolution = reset ? resolved : outerResolved && resolved;\n\n  return (\n    <EntityResolutionContext value={resolution}>\n      <DataOverrideContext value={value}>{children}</DataOverrideContext>\n    </EntityResolutionContext>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAmCA,SAAgB,iBAAiB,EAC/B,gBACA,cACA,WACA,cACA,OACA,YACmC;CACnC,MAAM,QAAQ,WAAW,mBAAmB;CAC5C,MAAM,gBAAgB,WAAW,uBAAuB;CACxD,MAAM,EAAE,MAAM,aAAa,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAKlG,MAAM,QAAQ,cACL,QAAQ,GAAG,YAAY,KAAK,IAAI;EAAE,GAAI,SAAS,OAAO,UAAU,WAAW,QAAQ,CAAC;GAAK,YAAY;CAAK,GACjH;EAAC;EAAO;EAAW;EAAM;CAAK,CAChC;CAOA,OACE,oBAAC,yBAAD;EAAyB,OAHR,QAAQ,WAAW,iBAAiB;EAInD,UAAA,oBAAC,qBAAD;GAA4B;GAAQ;EAA8B,CAAA;CAC3C,CAAA;AAE7B"}

package/dist/sdk/data/index.js

@@ -2,6 +2,7 @@ import { DataOverrideContext, useDataOverride } from "./data-override-context.js
 import { HotDataProvider } from "./hot-data-provider.js";
 import { ListItemRefContext, useListItemRef } from "./list-item-ref-context.js";
 import { PageReactiveDataRoot, ReactiveRootContext } from "./page-reactive-data-root.js";
+import "./entity-resolution-context.js";
 import { MultipleReactiveDataProvider } from "./multiple-reactive-data-provider.js";
 import { ReactiveDataProvider } from "./reactive-data-provider.js";
 import { ReactiveListItemDataProvider } from "./reactive-list-item-data-provider.js";