@vtex/faststore 0.0.5 → 0.0.6

package/dist/sdk/data/page-reactive-data-root.d.ts

@@ -33,6 +33,24 @@ export type ReactiveRootContextValue<TData = unknown> = Readonly<{
    * from "entity is legitimately absent" (docs/storefront-core/reference-free-particle-model.md § Read side — data).
    */
   error: ErrorLike | undefined;
+  /**
+   * True only under a real `PageReactiveDataRoot`. Every other field above is ambiguous between
+   * "no root at all" and "a root with nothing to give right now" — `rootQueryData: undefined` and
+   * `loading: false` describe both the context default and a root whose query is skipped for want
+   * of a reactive variable. `useReactiveEntity` needs that distinction to tell a placeholder slice
+   * apart from the only slice there is.
+   *
+   * Required, not optional, and deliberately so. This flag is the whole of what arms the gate in
+   * `useReactiveEntity`, so a provider that omits it disarms the gate silently — measured: a value
+   * that `satisfies ReactiveRootContextValue` without it reproduces the corrupting payload byte for
+   * byte on an otherwise-fixed tree, and no test fails. `ReactiveRootContext` is public surface via
+   * `sdk/data/index.ts`, so that provider need not live in this repo. Making it required moves that
+   * failure to compile time.
+   *
+   * A hand-built context value stands in for a root's *output*, not for the reactive runtime, so it
+   * declares `false` and its subtree keeps gating on nothing.
+   */
+  hasRoot: boolean;
 }>;
 export declare const ReactiveRootContext: import("react").Context<Readonly<{
   /** Current root query data exposed to descendant `ReactiveDataProvider`s. */
@@ -47,6 +65,24 @@ export declare const ReactiveRootContext: import("react").Context<Readonly<{
    * from "entity is legitimately absent" (docs/storefront-core/reference-free-particle-model.md § Read side — data).
    */
   error: ErrorLike | undefined;
+  /**
+   * True only under a real `PageReactiveDataRoot`. Every other field above is ambiguous between
+   * "no root at all" and "a root with nothing to give right now" — `rootQueryData: undefined` and
+   * `loading: false` describe both the context default and a root whose query is skipped for want
+   * of a reactive variable. `useReactiveEntity` needs that distinction to tell a placeholder slice
+   * apart from the only slice there is.
+   *
+   * Required, not optional, and deliberately so. This flag is the whole of what arms the gate in
+   * `useReactiveEntity`, so a provider that omits it disarms the gate silently — measured: a value
+   * that `satisfies ReactiveRootContextValue` without it reproduces the corrupting payload byte for
+   * byte on an otherwise-fixed tree, and no test fails. `ReactiveRootContext` is public surface via
+   * `sdk/data/index.ts`, so that provider need not live in this repo. Making it required moves that
+   * failure to compile time.
+   *
+   * A hand-built context value stands in for a root's *output*, not for the reactive runtime, so it
+   * declares `false` and its subtree keeps gating on nothing.
+   */
+  hasRoot: boolean;
 }>>;
 export declare function PageReactiveDataRoot<TData = unknown, TVars extends OperationVariables = OperationVariables>(props: PageReactiveDataRootProps<TData, TVars>): ReactNode;
 //#endregion

package/dist/sdk/data/page-reactive-data-root.js

@@ -15,7 +15,8 @@ const ReactiveRootContext = createContext({
 	rootQueryData: void 0,
 	loading: false,
 	hasAllRequiredVariables: false,
-	error: void 0
+	error: void 0,
+	hasRoot: false
 });
 function getOperationDefinition(query) {
 	for (const definition of query.definitions) if (definition.kind === Kind.OPERATION_DEFINITION) return definition;
@@ -135,7 +136,8 @@ function PageReactiveDataRoot(props) {
 		rootQueryData: data ?? void 0,
 		loading,
 		hasAllRequiredVariables,
-		error
+		error,
+		hasRoot: true
 	}), [
 		data,
 		loading,

package/dist/sdk/data/page-reactive-data-root.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-reactive-data-root.js","names":[],"sources":["../../../src/sdk/data/page-reactive-data-root.tsx"],"sourcesContent":["'use client';\n\nimport type { ErrorLike, OperationVariables, ReactiveVar, TypedDocumentNode } from '@apollo/client';\nimport { useApolloClient, useQuery } from '@apollo/client/react';\nimport { type DocumentNode, Kind, type OperationDefinitionNode } from 'graphql';\nimport { createContext, type ReactNode, useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';\n\n// Reactive vars resolvable by name from a Server Component. Functions cannot cross the\n// Server→Client boundary in RSC, so the compiler emits string keys and this component resolves\n// them at runtime. New reactive vars must be registered here to be addressable from generated\n// pages. Currently empty: cart context travels on the transport, so no cart entry is needed\n// (docs/storefront-core/reference-cart.md § Cart context).\nconst REACTIVE_VAR_REGISTRY: Record<string, ReactiveVar<unknown>> = {};\n\n/**\n * Compile-time-stable map keyed by the operation's variable names. Each value is either an Apollo\n * reactive variable (`makeVar`) or the string name of one registered in REACTIVE_VAR_REGISTRY —\n * Server Components must pass strings because functions cannot cross the RSC boundary. Vars that\n * have not yet resolved should hold `null`; the runtime treats both `null` and `undefined` as\n * \"not yet ready\" and keeps `useQuery` skipped.\n */\nexport type ClientVariablesMap<TVars> = Partial<{\n  [K in keyof TVars]: ReactiveVar<TVars[K] | null> | string;\n}>;\n\nfunction resolveReactiveVar(value: ReactiveVar<unknown> | string): ReactiveVar<unknown> | undefined {\n  if (typeof value === 'function') return value;\n  const resolved = REACTIVE_VAR_REGISTRY[value];\n  if (!resolved) {\n    throw new Error(\n      `PageReactiveDataRoot: clientVariables entry \"${value}\" is not registered. Add it to REACTIVE_VAR_REGISTRY in page-reactive-data-root.tsx.`,\n    );\n  }\n  return resolved;\n}\n\nexport type PageReactiveDataRootProps<TData, TVars extends OperationVariables> = Readonly<{\n  /** The composed PAGE_QUERY operation document. */\n  query: TypedDocumentNode<TData, TVars>;\n  /** Variables the server used when calling fetchPageData. Only used to seed the client cache. */\n  serverVariables?: TVars;\n  /** Server-rendered PAGE_QUERY result. When present and shape-matched, seeded into the cache once. */\n  initialData?: TData | null;\n  /** Reactive vars whose current values are merged into operation variables at render time. */\n  clientVariables?: ClientVariablesMap<TVars>;\n  children: ReactNode;\n}>;\n\nexport type ReactiveRootContextValue<TData = unknown> = Readonly<{\n  /** Current root query data exposed to descendant `ReactiveDataProvider`s. */\n  rootQueryData: TData | undefined;\n  /** Whether the underlying useQuery is currently in flight. */\n  loading: boolean;\n  /** False when at least one required variable has not been provided yet. */\n  hasAllRequiredVariables: boolean;\n  /**\n   * Error from the underlying useQuery. With non-null root fields (e.g. `cart: Cart!`), a failed\n   * fetch nulls the whole operation's `data` — descendants need this to tell \"fetch failed\" apart\n   * from \"entity is legitimately absent\" (docs/storefront-core/reference-free-particle-model.md § Read side — data).\n   */\n  error: ErrorLike | undefined;\n}>;\n\nexport const ReactiveRootContext = createContext<ReactiveRootContextValue>({\n  rootQueryData: undefined,\n  loading: false,\n  hasAllRequiredVariables: false,\n  error: undefined,\n});\n\nfunction getOperationDefinition(query: DocumentNode): OperationDefinitionNode | undefined {\n  for (const definition of query.definitions) {\n    if (definition.kind === Kind.OPERATION_DEFINITION) return definition;\n  }\n  return undefined;\n}\n\nfunction getRequiredVariableNames(query: DocumentNode): string[] {\n  const op = getOperationDefinition(query);\n  if (!op?.variableDefinitions) return [];\n  const required: string[] = [];\n  for (const def of op.variableDefinitions) {\n    if (def.type.kind === Kind.NON_NULL_TYPE && def.defaultValue === undefined) {\n      required.push(def.variable.name.value);\n    }\n  }\n  return required;\n}\n\nfunction getTopLevelFieldNames(query: DocumentNode): Set<string> {\n  const op = getOperationDefinition(query);\n  const names = new Set<string>();\n  if (!op) return names;\n  for (const sel of op.selectionSet.selections) {\n    if (sel.kind === Kind.FIELD) {\n      names.add((sel.alias ?? sel.name).value);\n    }\n  }\n  return names;\n}\n\nfunction shapeMatches(query: DocumentNode, data: unknown): boolean {\n  if (data == null || typeof data !== 'object') return false;\n  const expected = getTopLevelFieldNames(query);\n  if (expected.size === 0) return false;\n  const actual = data as Record<string, unknown>;\n  // Require AT LEAST ONE top-level field name to be present in `data`. The operation's full\n  // top-level shape may include fields the server did not return; partial seeds still help. A total\n  // miss (no overlap at all) signals a shape mismatch and we skip the seed.\n  for (const key of expected) {\n    if (key in actual) return true;\n  }\n  return false;\n}\n\n/**\n * Reads the current values of every reactive var in `clientVariables` into a plain object via a\n * single `useSyncExternalStore` call (no hooks-in-loop). Apollo's `ReactiveVar.onNextChange` fires\n * once per registration, so the subscriber re-attaches after each notification to stay listening.\n */\nfunction useClientVariableValues<TVars>(clientVariables: ClientVariablesMap<TVars> | undefined): Partial<TVars> {\n  // Keep the latest map identity reachable from inside subscribe()/getSnapshot() without forcing\n  // useSyncExternalStore to tear down the underlying subscription.\n  const varsRef = useRef(clientVariables);\n  // react-doctor-disable-next-line no-ref-current-in-render -- keeps the latest map reachable from the stable subscribe()/getSnapshot() callbacks below\n  varsRef.current = clientVariables;\n\n  const subscribe = useCallback((notify: () => void): (() => void) => {\n    const cv = varsRef.current;\n    if (!cv) return () => {};\n\n    const activeUnsubs: Array<() => void> = [];\n    let cancelled = false;\n\n    const attach = (rv: ReactiveVar<unknown>): void => {\n      if (cancelled) return;\n      const unsub = rv.onNextChange(() => {\n        notify();\n        // onNextChange fires only once — re-attach to keep listening for subsequent changes.\n        attach(rv);\n      });\n      activeUnsubs.push(unsub);\n    };\n\n    for (const rv of Object.values(cv)) {\n      if (rv === undefined || rv === null) continue;\n      const resolved = resolveReactiveVar(rv as ReactiveVar<unknown> | string);\n      if (resolved) attach(resolved);\n    }\n\n    return () => {\n      cancelled = true;\n      for (const u of activeUnsubs) u();\n    };\n  }, []);\n\n  const lastSnapshotRef = useRef<{ json: string; value: Record<string, unknown> } | null>(null);\n\n  const getSnapshot = (): string => {\n    const cv = varsRef.current;\n    const snap: Record<string, unknown> = {};\n    if (cv) {\n      for (const [key, reactiveVar] of Object.entries(cv)) {\n        if (reactiveVar === undefined || reactiveVar === null) continue;\n        const resolved = resolveReactiveVar(reactiveVar as ReactiveVar<unknown> | string);\n        if (!resolved) continue;\n        const value = resolved();\n        if (value !== null && value !== undefined) snap[key] = value;\n      }\n    }\n    const json = JSON.stringify(snap);\n    // useSyncExternalStore expects a stable snapshot reference until the value changes (Object.is\n    // identity check) — return the cached `json` whenever the contents are unchanged.\n    if (lastSnapshotRef.current && lastSnapshotRef.current.json === json) {\n      return lastSnapshotRef.current.json;\n    }\n    lastSnapshotRef.current = { json, value: snap };\n    return json;\n  };\n\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  return (lastSnapshotRef.current?.value ?? {}) as Partial<TVars>;\n}\n\nexport function PageReactiveDataRoot<TData = unknown, TVars extends OperationVariables = OperationVariables>(\n  props: PageReactiveDataRootProps<TData, TVars>,\n): ReactNode {\n  const { query, serverVariables, initialData, clientVariables, children } = props;\n  const client = useApolloClient();\n  const seededRef = useRef(false);\n\n  const clientValues = useClientVariableValues<TVars>(clientVariables);\n  const mergedVariables = { ...(serverVariables ?? ({} as TVars)), ...clientValues } as TVars;\n\n  const requiredNames = getRequiredVariableNames(query);\n  const mergedRecord = mergedVariables as Record<string, unknown>;\n  const hasAllRequiredVariables = requiredNames.every((name) => {\n    const v = mergedRecord[name];\n    return v !== null && v !== undefined;\n  });\n\n  // Ref- and shape-guarded one-time cache seed from server props. We use `useEffect` (not\n  // `useLayoutEffect`) to avoid the SSR-pass warning emitted by React 19 — the resulting \"first\n  // render shows fallbackData, second render shows cache slice\" behaviour is acceptable because\n  // initialData is the same value `ReactiveDataProvider` falls back to anyway.\n  useEffect(() => {\n    if (seededRef.current) return;\n    if (!serverVariables || initialData == null) return;\n    if (!shapeMatches(query, initialData)) return;\n    client.cache.writeQuery({ query, variables: serverVariables, data: initialData });\n    seededRef.current = true;\n  }, [client, query, serverVariables, initialData]);\n\n  const { data, loading, error } = useQuery(query, {\n    variables: mergedVariables,\n    fetchPolicy: 'cache-first',\n    skip: !hasAllRequiredVariables,\n  });\n\n  const contextValue: ReactiveRootContextValue<TData> = useMemo(\n    () => ({\n      rootQueryData: (data ?? undefined) as TData | undefined,\n      loading,\n      hasAllRequiredVariables,\n      error,\n    }),\n    [data, loading, hasAllRequiredVariables, error],\n  );\n\n  return (\n    <ReactiveRootContext.Provider value={contextValue as ReactiveRootContextValue}>\n      {children}\n    </ReactiveRootContext.Provider>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"page-reactive-data-root.js","names":[],"sources":["../../../src/sdk/data/page-reactive-data-root.tsx"],"sourcesContent":["'use client';\n\nimport type { ErrorLike, OperationVariables, ReactiveVar, TypedDocumentNode } from '@apollo/client';\nimport { useApolloClient, useQuery } from '@apollo/client/react';\nimport { type DocumentNode, Kind, type OperationDefinitionNode } from 'graphql';\nimport { createContext, type ReactNode, useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';\n\n// Reactive vars resolvable by name from a Server Component. Functions cannot cross the\n// Server→Client boundary in RSC, so the compiler emits string keys and this component resolves\n// them at runtime. New reactive vars must be registered here to be addressable from generated\n// pages. Currently empty: cart context travels on the transport, so no cart entry is needed\n// (docs/storefront-core/reference-cart.md § Cart context).\nconst REACTIVE_VAR_REGISTRY: Record<string, ReactiveVar<unknown>> = {};\n\n/**\n * Compile-time-stable map keyed by the operation's variable names. Each value is either an Apollo\n * reactive variable (`makeVar`) or the string name of one registered in REACTIVE_VAR_REGISTRY —\n * Server Components must pass strings because functions cannot cross the RSC boundary. Vars that\n * have not yet resolved should hold `null`; the runtime treats both `null` and `undefined` as\n * \"not yet ready\" and keeps `useQuery` skipped.\n */\nexport type ClientVariablesMap<TVars> = Partial<{\n  [K in keyof TVars]: ReactiveVar<TVars[K] | null> | string;\n}>;\n\nfunction resolveReactiveVar(value: ReactiveVar<unknown> | string): ReactiveVar<unknown> | undefined {\n  if (typeof value === 'function') return value;\n  const resolved = REACTIVE_VAR_REGISTRY[value];\n  if (!resolved) {\n    throw new Error(\n      `PageReactiveDataRoot: clientVariables entry \"${value}\" is not registered. Add it to REACTIVE_VAR_REGISTRY in page-reactive-data-root.tsx.`,\n    );\n  }\n  return resolved;\n}\n\nexport type PageReactiveDataRootProps<TData, TVars extends OperationVariables> = Readonly<{\n  /** The composed PAGE_QUERY operation document. */\n  query: TypedDocumentNode<TData, TVars>;\n  /** Variables the server used when calling fetchPageData. Only used to seed the client cache. */\n  serverVariables?: TVars;\n  /** Server-rendered PAGE_QUERY result. When present and shape-matched, seeded into the cache once. */\n  initialData?: TData | null;\n  /** Reactive vars whose current values are merged into operation variables at render time. */\n  clientVariables?: ClientVariablesMap<TVars>;\n  children: ReactNode;\n}>;\n\nexport type ReactiveRootContextValue<TData = unknown> = Readonly<{\n  /** Current root query data exposed to descendant `ReactiveDataProvider`s. */\n  rootQueryData: TData | undefined;\n  /** Whether the underlying useQuery is currently in flight. */\n  loading: boolean;\n  /** False when at least one required variable has not been provided yet. */\n  hasAllRequiredVariables: boolean;\n  /**\n   * Error from the underlying useQuery. With non-null root fields (e.g. `cart: Cart!`), a failed\n   * fetch nulls the whole operation's `data` — descendants need this to tell \"fetch failed\" apart\n   * from \"entity is legitimately absent\" (docs/storefront-core/reference-free-particle-model.md § Read side — data).\n   */\n  error: ErrorLike | undefined;\n  /**\n   * True only under a real `PageReactiveDataRoot`. Every other field above is ambiguous between\n   * \"no root at all\" and \"a root with nothing to give right now\" — `rootQueryData: undefined` and\n   * `loading: false` describe both the context default and a root whose query is skipped for want\n   * of a reactive variable. `useReactiveEntity` needs that distinction to tell a placeholder slice\n   * apart from the only slice there is.\n   *\n   * Required, not optional, and deliberately so. This flag is the whole of what arms the gate in\n   * `useReactiveEntity`, so a provider that omits it disarms the gate silently — measured: a value\n   * that `satisfies ReactiveRootContextValue` without it reproduces the corrupting payload byte for\n   * byte on an otherwise-fixed tree, and no test fails. `ReactiveRootContext` is public surface via\n   * `sdk/data/index.ts`, so that provider need not live in this repo. Making it required moves that\n   * failure to compile time.\n   *\n   * A hand-built context value stands in for a root's *output*, not for the reactive runtime, so it\n   * declares `false` and its subtree keeps gating on nothing.\n   */\n  hasRoot: boolean;\n}>;\n\nexport const ReactiveRootContext = createContext<ReactiveRootContextValue>({\n  rootQueryData: undefined,\n  loading: false,\n  hasAllRequiredVariables: false,\n  error: undefined,\n  hasRoot: false,\n});\n\nfunction getOperationDefinition(query: DocumentNode): OperationDefinitionNode | undefined {\n  for (const definition of query.definitions) {\n    if (definition.kind === Kind.OPERATION_DEFINITION) return definition;\n  }\n  return undefined;\n}\n\nfunction getRequiredVariableNames(query: DocumentNode): string[] {\n  const op = getOperationDefinition(query);\n  if (!op?.variableDefinitions) return [];\n  const required: string[] = [];\n  for (const def of op.variableDefinitions) {\n    if (def.type.kind === Kind.NON_NULL_TYPE && def.defaultValue === undefined) {\n      required.push(def.variable.name.value);\n    }\n  }\n  return required;\n}\n\nfunction getTopLevelFieldNames(query: DocumentNode): Set<string> {\n  const op = getOperationDefinition(query);\n  const names = new Set<string>();\n  if (!op) return names;\n  for (const sel of op.selectionSet.selections) {\n    if (sel.kind === Kind.FIELD) {\n      names.add((sel.alias ?? sel.name).value);\n    }\n  }\n  return names;\n}\n\nfunction shapeMatches(query: DocumentNode, data: unknown): boolean {\n  if (data == null || typeof data !== 'object') return false;\n  const expected = getTopLevelFieldNames(query);\n  if (expected.size === 0) return false;\n  const actual = data as Record<string, unknown>;\n  // Require AT LEAST ONE top-level field name to be present in `data`. The operation's full\n  // top-level shape may include fields the server did not return; partial seeds still help. A total\n  // miss (no overlap at all) signals a shape mismatch and we skip the seed.\n  for (const key of expected) {\n    if (key in actual) return true;\n  }\n  return false;\n}\n\n/**\n * Reads the current values of every reactive var in `clientVariables` into a plain object via a\n * single `useSyncExternalStore` call (no hooks-in-loop). Apollo's `ReactiveVar.onNextChange` fires\n * once per registration, so the subscriber re-attaches after each notification to stay listening.\n */\nfunction useClientVariableValues<TVars>(clientVariables: ClientVariablesMap<TVars> | undefined): Partial<TVars> {\n  // Keep the latest map identity reachable from inside subscribe()/getSnapshot() without forcing\n  // useSyncExternalStore to tear down the underlying subscription.\n  const varsRef = useRef(clientVariables);\n  // react-doctor-disable-next-line no-ref-current-in-render -- keeps the latest map reachable from the stable subscribe()/getSnapshot() callbacks below\n  varsRef.current = clientVariables;\n\n  const subscribe = useCallback((notify: () => void): (() => void) => {\n    const cv = varsRef.current;\n    if (!cv) return () => {};\n\n    const activeUnsubs: Array<() => void> = [];\n    let cancelled = false;\n\n    const attach = (rv: ReactiveVar<unknown>): void => {\n      if (cancelled) return;\n      const unsub = rv.onNextChange(() => {\n        notify();\n        // onNextChange fires only once — re-attach to keep listening for subsequent changes.\n        attach(rv);\n      });\n      activeUnsubs.push(unsub);\n    };\n\n    for (const rv of Object.values(cv)) {\n      if (rv === undefined || rv === null) continue;\n      const resolved = resolveReactiveVar(rv as ReactiveVar<unknown> | string);\n      if (resolved) attach(resolved);\n    }\n\n    return () => {\n      cancelled = true;\n      for (const u of activeUnsubs) u();\n    };\n  }, []);\n\n  const lastSnapshotRef = useRef<{ json: string; value: Record<string, unknown> } | null>(null);\n\n  const getSnapshot = (): string => {\n    const cv = varsRef.current;\n    const snap: Record<string, unknown> = {};\n    if (cv) {\n      for (const [key, reactiveVar] of Object.entries(cv)) {\n        if (reactiveVar === undefined || reactiveVar === null) continue;\n        const resolved = resolveReactiveVar(reactiveVar as ReactiveVar<unknown> | string);\n        if (!resolved) continue;\n        const value = resolved();\n        if (value !== null && value !== undefined) snap[key] = value;\n      }\n    }\n    const json = JSON.stringify(snap);\n    // useSyncExternalStore expects a stable snapshot reference until the value changes (Object.is\n    // identity check) — return the cached `json` whenever the contents are unchanged.\n    if (lastSnapshotRef.current && lastSnapshotRef.current.json === json) {\n      return lastSnapshotRef.current.json;\n    }\n    lastSnapshotRef.current = { json, value: snap };\n    return json;\n  };\n\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  return (lastSnapshotRef.current?.value ?? {}) as Partial<TVars>;\n}\n\nexport function PageReactiveDataRoot<TData = unknown, TVars extends OperationVariables = OperationVariables>(\n  props: PageReactiveDataRootProps<TData, TVars>,\n): ReactNode {\n  const { query, serverVariables, initialData, clientVariables, children } = props;\n  const client = useApolloClient();\n  const seededRef = useRef(false);\n\n  const clientValues = useClientVariableValues<TVars>(clientVariables);\n  const mergedVariables = { ...(serverVariables ?? ({} as TVars)), ...clientValues } as TVars;\n\n  const requiredNames = getRequiredVariableNames(query);\n  const mergedRecord = mergedVariables as Record<string, unknown>;\n  const hasAllRequiredVariables = requiredNames.every((name) => {\n    const v = mergedRecord[name];\n    return v !== null && v !== undefined;\n  });\n\n  // Ref- and shape-guarded one-time cache seed from server props. We use `useEffect` (not\n  // `useLayoutEffect`) to avoid the SSR-pass warning emitted by React 19 — the resulting \"first\n  // render shows fallbackData, second render shows cache slice\" behaviour is acceptable because\n  // initialData is the same value `ReactiveDataProvider` falls back to anyway.\n  useEffect(() => {\n    if (seededRef.current) return;\n    if (!serverVariables || initialData == null) return;\n    if (!shapeMatches(query, initialData)) return;\n    client.cache.writeQuery({ query, variables: serverVariables, data: initialData });\n    seededRef.current = true;\n  }, [client, query, serverVariables, initialData]);\n\n  const { data, loading, error } = useQuery(query, {\n    variables: mergedVariables,\n    fetchPolicy: 'cache-first',\n    skip: !hasAllRequiredVariables,\n  });\n\n  const contextValue: ReactiveRootContextValue<TData> = useMemo(\n    () => ({\n      rootQueryData: (data ?? undefined) as TData | undefined,\n      loading,\n      hasAllRequiredVariables,\n      error,\n      hasRoot: true,\n    }),\n    [data, loading, hasAllRequiredVariables, error],\n  );\n\n  return (\n    <ReactiveRootContext.Provider value={contextValue as ReactiveRootContextValue}>\n      {children}\n    </ReactiveRootContext.Provider>\n  );\n}\n"],"mappings":"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"}

package/dist/sdk/data/reactive-data-provider.js

@@ -1,5 +1,6 @@
 "use client";
 import { DataOverrideContext } from "./data-override-context.js";
+import { EntityResolutionContext } from "./entity-resolution-context.js";
 import { useReactiveEntity } from "./use-reactive-entity.js";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/data/reactive-data-provider.tsx
@@ -12,10 +13,13 @@ import { jsx } from "react/jsx-runtime";
 * See docs/storefront-core/reference-data-layer-runtime.md § Per-component subscription and rfc-data-layer.md §"Reactive fetch".
 */
 function ReactiveDataProvider({ entityFragment, fragmentName, rootField, fallbackData, children }) {
-	const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
-	return /* @__PURE__ */ jsx(DataOverrideContext, {
+	const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
+	return /* @__PURE__ */ jsx(EntityResolutionContext, {
 		value: resolved,
-		children
+		children: /* @__PURE__ */ jsx(DataOverrideContext, {
+			value: data,
+			children
+		})
 	});
 }
 //#endregion

package/dist/sdk/data/reactive-data-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactive-data-provider.js","names":[],"sources":["../../../src/sdk/data/reactive-data-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { useReactiveEntity } from './use-reactive-entity.js';\n\nexport type ReactiveDataProviderProps = 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. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  children: ReactNode;\n}>;\n\n/**\n * Per-particle reactive subscriber (AD-4 / AD-D2).\n *\n * Resolves its entity slice via `useReactiveEntity` (the shared single-entity resolve; see that\n * hook's doc for the cache-read details) and writes it, unmodified, into `DataOverrideContext`.\n *\n * See docs/storefront-core/reference-data-layer-runtime.md § Per-component subscription and rfc-data-layer.md §\"Reactive fetch\".\n */\nexport function ReactiveDataProvider({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  children,\n}: ReactiveDataProviderProps): ReactNode {\n  const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  return <DataOverrideContext value={resolved}>{children}</DataOverrideContext>;\n}\n"],"mappings":";;;;;;;;;;;;;AA2BA,SAAgB,qBAAqB,EACnC,gBACA,cACA,WACA,cACA,YACuC;CACvC,MAAM,WAAW,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAExF,OAAO,oBAAC,qBAAD;EAAqB,OAAO;EAAW;CAA8B,CAAA;AAC9E"}
+{"version":3,"file":"reactive-data-provider.js","names":[],"sources":["../../../src/sdk/data/reactive-data-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } 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 ReactiveDataProviderProps = 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. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  children: ReactNode;\n}>;\n\n/**\n * Per-particle reactive subscriber (AD-4 / AD-D2).\n *\n * Resolves its entity slice via `useReactiveEntity` (the shared single-entity resolve; see that\n * hook's doc for the cache-read details) and writes it, unmodified, into `DataOverrideContext`.\n *\n * See docs/storefront-core/reference-data-layer-runtime.md § Per-component subscription and rfc-data-layer.md §\"Reactive fetch\".\n */\nexport function ReactiveDataProvider({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  children,\n}: ReactiveDataProviderProps): ReactNode {\n  const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  return (\n    <EntityResolutionContext value={resolved}>\n      <DataOverrideContext value={data}>{children}</DataOverrideContext>\n    </EntityResolutionContext>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,SAAgB,qBAAqB,EACnC,gBACA,cACA,WACA,cACA,YACuC;CACvC,MAAM,EAAE,MAAM,aAAa,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAElG,OACE,oBAAC,yBAAD;EAAyB,OAAO;EAC9B,UAAA,oBAAC,qBAAD;GAAqB,OAAO;GAAO;EAA8B,CAAA;CAC1C,CAAA;AAE7B"}

package/dist/sdk/data/reactive-list-item-data-provider.js

@@ -1,7 +1,10 @@
 "use client";
 import { DataOverrideContext } from "./data-override-context.js";
 import { useListItemRef } from "./list-item-ref-context.js";
+import { ReactiveRootContext } from "./page-reactive-data-root.js";
+import { EntityResolutionContext } from "./entity-resolution-context.js";
 import { useApolloClient, useFragment } from "@apollo/client/react";
+import { useContext } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/data/reactive-list-item-data-provider.tsx
 /**
@@ -30,10 +33,15 @@ function ReactiveListItemDataProvider({ entityFragment, fragmentName, children }
 		fragmentName,
 		from: from ?? ""
 	});
-	const resolved = from && fragmentResult.complete ? fragmentResult.data : ref?.fallbackData;
-	return /* @__PURE__ */ jsx(DataOverrideContext, {
-		value: resolved,
-		children
+	const { hasRoot } = useContext(ReactiveRootContext);
+	const hit = Boolean(from) && fragmentResult.complete;
+	const resolved = hit ? fragmentResult.data : ref?.fallbackData;
+	return /* @__PURE__ */ jsx(EntityResolutionContext, {
+		value: !hasRoot || ref === void 0 || hit,
+		children: /* @__PURE__ */ jsx(DataOverrideContext, {
+			value: resolved,
+			children
+		})
 	});
 }
 //#endregion

package/dist/sdk/data/reactive-list-item-data-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactive-list-item-data-provider.js","names":[],"sources":["../../../src/sdk/data/reactive-list-item-data-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport { useApolloClient, useFragment } from '@apollo/client/react';\nimport type { ReactNode } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { useListItemRef } from './list-item-ref-context.js';\n\nexport type ReactiveListItemDataProviderProps = Readonly<{\n  /** Derived `fragment <X>_<ListElementEntity> on <ListElementEntity>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  children: ReactNode;\n}>;\n\n/**\n * Per-iterated-line reactive subscriber.\n *\n * The list-item sibling of `ReactiveDataProvider`: instead of deriving the entity ref from a\n * top-level page-query field, it reads the current line's ref from `ListItemRefContext` (published\n * per line by the iterator, e.g. `CartList`) and subscribes to that one normalized entity\n * (`CartItem:<id>`) via `useFragment`. The hook never triggers a network request — it is purely a\n * cache reader. When the ref is unresolved or the cache slice is incomplete, it falls back to the\n * line's server-rendered slice (`fallbackData`) so descendants always see a value. The resolved\n * slice is published through the same `DataOverrideContext` seam reactive components read today.\n *\n * See docs/storefront-core/reference-free-particle-model.md § Per-item delivery for iterated matters.\n */\nexport function ReactiveListItemDataProvider({\n  entityFragment,\n  fragmentName,\n  children,\n}: ReactiveListItemDataProviderProps): ReactNode {\n  const ref = useListItemRef();\n  const client = useApolloClient();\n\n  // Derive a stable cache identifier when both __typename and id are present. `cache.identify`\n  // returns undefined when the inputs are not normalisable, which we treat the same as a missing\n  // ref — useFragment then has nothing to subscribe to and the line shows its fallback slice.\n  let from: string | undefined;\n  if (ref?.__typename != null && ref.id != null) {\n    from = client.cache.identify({ __typename: ref.__typename, id: ref.id });\n  }\n\n  // useFragment must be called unconditionally to satisfy the Rules of Hooks. When `from` is\n  // undefined, Apollo's useFragment returns `{ data: {}, complete: false }` and never reads the\n  // cache; the empty-string sentinel keeps the hook invoked but the read a no-op.\n  const fragmentResult = useFragment({\n    fragment: entityFragment,\n    fragmentName,\n    from: from ?? '',\n  });\n\n  const resolved = from && fragmentResult.complete ? fragmentResult.data : ref?.fallbackData;\n\n  return <DataOverrideContext value={resolved}>{children}</DataOverrideContext>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,6BAA6B,EAC3C,gBACA,cACA,YAC+C;CAC/C,MAAM,MAAM,eAAe;CAC3B,MAAM,SAAS,gBAAgB;CAK/B,IAAI;CACJ,IAAI,KAAK,cAAc,QAAQ,IAAI,MAAM,MACvC,OAAO,OAAO,MAAM,SAAS;EAAE,YAAY,IAAI;EAAY,IAAI,IAAI;CAAG,CAAC;CAMzE,MAAM,iBAAiB,YAAY;EACjC,UAAU;EACV;EACA,MAAM,QAAQ;CAChB,CAAC;CAED,MAAM,WAAW,QAAQ,eAAe,WAAW,eAAe,OAAO,KAAK;CAE9E,OAAO,oBAAC,qBAAD;EAAqB,OAAO;EAAW;CAA8B,CAAA;AAC9E"}
+{"version":3,"file":"reactive-list-item-data-provider.js","names":[],"sources":["../../../src/sdk/data/reactive-list-item-data-provider.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport { useApolloClient, useFragment } from '@apollo/client/react';\nimport type { ReactNode } from 'react';\nimport { useContext } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { EntityResolutionContext } from './entity-resolution-context.js';\nimport { useListItemRef } from './list-item-ref-context.js';\nimport { ReactiveRootContext } from './page-reactive-data-root.js';\n\nexport type ReactiveListItemDataProviderProps = Readonly<{\n  /** Derived `fragment <X>_<ListElementEntity> on <ListElementEntity>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  children: ReactNode;\n}>;\n\n/**\n * Per-iterated-line reactive subscriber.\n *\n * The list-item sibling of `ReactiveDataProvider`: instead of deriving the entity ref from a\n * top-level page-query field, it reads the current line's ref from `ListItemRefContext` (published\n * per line by the iterator, e.g. `CartList`) and subscribes to that one normalized entity\n * (`CartItem:<id>`) via `useFragment`. The hook never triggers a network request — it is purely a\n * cache reader. When the ref is unresolved or the cache slice is incomplete, it falls back to the\n * line's server-rendered slice (`fallbackData`) so descendants always see a value. The resolved\n * slice is published through the same `DataOverrideContext` seam reactive components read today.\n *\n * See docs/storefront-core/reference-free-particle-model.md § Per-item delivery for iterated matters.\n */\nexport function ReactiveListItemDataProvider({\n  entityFragment,\n  fragmentName,\n  children,\n}: ReactiveListItemDataProviderProps): ReactNode {\n  const ref = useListItemRef();\n  const client = useApolloClient();\n\n  // Derive a stable cache identifier when both __typename and id are present. `cache.identify`\n  // returns undefined when the inputs are not normalisable, which we treat the same as a missing\n  // ref — useFragment then has nothing to subscribe to and the line shows its fallback slice.\n  let from: string | undefined;\n  if (ref?.__typename != null && ref.id != null) {\n    from = client.cache.identify({ __typename: ref.__typename, id: ref.id });\n  }\n\n  // useFragment must be called unconditionally to satisfy the Rules of Hooks. When `from` is\n  // undefined, Apollo's useFragment returns `{ data: {}, complete: false }` and never reads the\n  // cache; the empty-string sentinel keeps the hook invoked but the read a no-op.\n  const fragmentResult = useFragment({\n    fragment: entityFragment,\n    fragmentName,\n    from: from ?? '',\n  });\n\n  const { hasRoot } = useContext(ReactiveRootContext);\n  const hit = Boolean(from) && fragmentResult.complete;\n  const resolved = hit ? fragmentResult.data : ref?.fallbackData;\n\n  // Resets the resolution verdict for the same reason it resets the slice: the line's own entity is\n  // what this subtree reads, so an ancestor's verdict no longer describes it. Two escapes, mirroring\n  // `useReactiveEntity`: no reactive root above means nothing is outstanding anywhere, and no iterator\n  // above (`ref` undefined) means there is no reactive runtime here at all. Without the first, a line\n  // rendered from plain props under a real ref would report unresolved forever.\n  return (\n    <EntityResolutionContext value={!hasRoot || ref === undefined || hit}>\n      <DataOverrideContext value={resolved}>{children}</DataOverrideContext>\n    </EntityResolutionContext>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,6BAA6B,EAC3C,gBACA,cACA,YAC+C;CAC/C,MAAM,MAAM,eAAe;CAC3B,MAAM,SAAS,gBAAgB;CAK/B,IAAI;CACJ,IAAI,KAAK,cAAc,QAAQ,IAAI,MAAM,MACvC,OAAO,OAAO,MAAM,SAAS;EAAE,YAAY,IAAI;EAAY,IAAI,IAAI;CAAG,CAAC;CAMzE,MAAM,iBAAiB,YAAY;EACjC,UAAU;EACV;EACA,MAAM,QAAQ;CAChB,CAAC;CAED,MAAM,EAAE,YAAY,WAAW,mBAAmB;CAClD,MAAM,MAAM,QAAQ,IAAI,KAAK,eAAe;CAC5C,MAAM,WAAW,MAAM,eAAe,OAAO,KAAK;CAOlD,OACE,oBAAC,yBAAD;EAAyB,OAAO,CAAC,WAAW,QAAQ,KAAA,KAAa;EAC/D,UAAA,oBAAC,qBAAD;GAAqB,OAAO;GAAW;EAA8B,CAAA;CAC9C,CAAA;AAE7B"}

package/dist/sdk/data/use-reactive-data-settled.js

@@ -0,0 +1,39 @@
+"use client";
+import { ReactiveRootContext } from "./page-reactive-data-root.js";
+import { useContext, useState } from "react";
+//#region src/sdk/data/use-reactive-data-settled.ts
+/**
+* Has this page's reactive root query settled at least once since the caller mounted?
+*
+* `useReactiveEntity` answers "what is this entity's slice" and never "has it arrived": it returns
+* `fallbackData` whenever the cache read is incomplete, so a `reactive` component's `$data` is
+* defined from the first render — empty or not. That is fine for a read-only component, which just
+* re-renders when the real values land, and wrong for a form, whose controls hand their seed to
+* react-hook-form's `defaultValue`, which re-adopts it on every render only while the field stays
+* clean: mounting on a placeholder seed before the real answer lands would make a shopper who starts
+* typing dirty the field against that placeholder for good, and even a shopper who does not type
+* would see the field flash from the placeholder to the real value. A form needs the one thing the
+* entity slice cannot express: whether the answer it is holding is the server's or a placeholder.
+*
+* `PageReactiveDataRoot` already publishes that on `ReactiveRootContext.loading` — the in-flight
+* state of the page query every reactive slice is read from. This hook latches it one way: `false`
+* until the first settled render, `true` for the rest of the mount. The latch is what keeps the
+* signal usable as a mount gate. A later refetch flips `loading` back to `true`, and a caller
+* gating its children on the raw flag would unmount them mid-edit and re-seed over whatever the
+* shopper had typed. Reactivity after that first paint is unaffected: the slice keeps arriving
+* through `DataOverrideContext` exactly as before.
+*
+* With no `PageReactiveDataRoot` above — Storybook, unit tests, any tree passing `$data` as a plain
+* prop — the context default carries `loading: false`, so this reads `true` on the first render and
+* gates nothing. Callers keep their own `$data === undefined` check for those trees.
+*/
+function useReactiveDataSettled() {
+	const { loading } = useContext(ReactiveRootContext);
+	const [settled, setSettled] = useState(false);
+	if (!loading && !settled) setSettled(true);
+	return settled;
+}
+//#endregion
+export { useReactiveDataSettled };
+
+//# sourceMappingURL=use-reactive-data-settled.js.map

package/dist/sdk/data/use-reactive-data-settled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-reactive-data-settled.js","names":[],"sources":["../../../src/sdk/data/use-reactive-data-settled.ts"],"sourcesContent":["'use client';\n\nimport { useContext, useState } from 'react';\nimport { ReactiveRootContext } from './page-reactive-data-root.js';\n\n/**\n * Has this page's reactive root query settled at least once since the caller mounted?\n *\n * `useReactiveEntity` answers \"what is this entity's slice\" and never \"has it arrived\": it returns\n * `fallbackData` whenever the cache read is incomplete, so a `reactive` component's `$data` is\n * defined from the first render — empty or not. That is fine for a read-only component, which just\n * re-renders when the real values land, and wrong for a form, whose controls hand their seed to\n * react-hook-form's `defaultValue`, which re-adopts it on every render only while the field stays\n * clean: mounting on a placeholder seed before the real answer lands would make a shopper who starts\n * typing dirty the field against that placeholder for good, and even a shopper who does not type\n * would see the field flash from the placeholder to the real value. A form needs the one thing the\n * entity slice cannot express: whether the answer it is holding is the server's or a placeholder.\n *\n * `PageReactiveDataRoot` already publishes that on `ReactiveRootContext.loading` — the in-flight\n * state of the page query every reactive slice is read from. This hook latches it one way: `false`\n * until the first settled render, `true` for the rest of the mount. The latch is what keeps the\n * signal usable as a mount gate. A later refetch flips `loading` back to `true`, and a caller\n * gating its children on the raw flag would unmount them mid-edit and re-seed over whatever the\n * shopper had typed. Reactivity after that first paint is unaffected: the slice keeps arriving\n * through `DataOverrideContext` exactly as before.\n *\n * With no `PageReactiveDataRoot` above — Storybook, unit tests, any tree passing `$data` as a plain\n * prop — the context default carries `loading: false`, so this reads `true` on the first render and\n * gates nothing. Callers keep their own `$data === undefined` check for those trees.\n */\nexport function useReactiveDataSettled(): boolean {\n  const { loading } = useContext(ReactiveRootContext);\n  const [settled, setSettled] = useState(false);\n\n  // Render-phase compare-and-set, not a ref: a render React abandons without committing (a suspended\n  // transition, a Suspense retry) must not advance this latch, and a state update queued on that\n  // abandoned attempt is exactly what React discards on retry — a ref write is not. No `settled ||\n  // !loading` guard is needed: this re-invokes before the render commits, so the returned value\n  // already reflects the latch this render just set.\n  if (!loading && !settled) setSettled(true);\n\n  return settled;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,yBAAkC;CAChD,MAAM,EAAE,YAAY,WAAW,mBAAmB;CAClD,MAAM,CAAC,SAAS,cAAc,SAAS,KAAK;CAO5C,IAAI,CAAC,WAAW,CAAC,SAAS,WAAW,IAAI;CAEzC,OAAO;AACT"}

package/dist/sdk/data/use-reactive-entity.js

@@ -32,7 +32,11 @@ function useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData
 		fragmentName,
 		from: from ?? ""
 	});
-	return from && fragmentResult.complete ? fragmentResult.data : fallbackData;
+	const hit = Boolean(from) && fragmentResult.complete;
+	return {
+		data: hit ? fragmentResult.data : fallbackData,
+		resolved: !ctx.hasRoot || hit
+	};
 }
 //#endregion
 export { useReactiveEntity };

package/dist/sdk/data/use-reactive-entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-reactive-entity.js","names":[],"sources":["../../../src/sdk/data/use-reactive-entity.ts"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport { useApolloClient, useFragment } from '@apollo/client/react';\nimport { useContext } from 'react';\nimport { ReactiveRootContext } from './page-reactive-data-root.js';\n\ntype EntityRef = {\n  __typename?: string;\n  id?: string | number;\n};\n\n/**\n * Shared single-entity resolve logic used by BOTH `ReactiveDataProvider` and `EntitySubscriber`\n * (AD-4 / AD-D2).\n *\n * Reads the root query data exposed by `PageReactiveDataRoot` via context, derives the entity ref\n * for the configured `rootField`, and subscribes to the cache via `useFragment`. The hook never\n * triggers a network request — it is purely a cache reader. When the entity ref is unresolved or\n * the cache slice is incomplete, falls back to `fallbackData` (the server-rendered payload) so\n * descendants always see a value.\n *\n * This hook is intentionally single-entity: it has no notion of merging/composing multiple\n * entities' slices — that's layered on top by `EntitySubscriber`.\n *\n * See docs/storefront-core/reference-data-layer-runtime.md § Per-component subscription and rfc-data-layer.md §\"Reactive fetch\".\n */\nexport function useReactiveEntity(\n  entityFragment: DocumentNode,\n  fragmentName: string,\n  rootField: string,\n  fallbackData: unknown,\n): unknown {\n  const ctx = useContext(ReactiveRootContext);\n  const client = useApolloClient();\n\n  const root = ctx.rootQueryData as Record<string, unknown> | undefined;\n  const rootSlice = root?.[rootField] as EntityRef | null | undefined;\n\n  // Derive a stable cache identifier when both __typename and id are present. `cache.identify`\n  // returns undefined when the inputs are not normalisable (no id, no keyFields), which we treat\n  // the same as a missing ref — useFragment then has nothing to subscribe to.\n  let from: string | undefined;\n  if (rootSlice?.__typename != null && rootSlice.id != null) {\n    from = client.cache.identify({ __typename: rootSlice.__typename, id: rootSlice.id });\n  }\n\n  // useFragment must be called unconditionally to satisfy the Rules of Hooks. When `from` is\n  // undefined, Apollo's useFragment returns `{ data: {}, complete: false }` and never reads the\n  // cache. Pass an empty string as a sentinel so the hook is invoked but the read is a no-op.\n  const fragmentResult = useFragment({\n    fragment: entityFragment,\n    fragmentName,\n    from: from ?? '',\n  });\n\n  return from && fragmentResult.complete ? fragmentResult.data : fallbackData;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,kBACd,gBACA,cACA,WACA,cACS;CACT,MAAM,MAAM,WAAW,mBAAmB;CAC1C,MAAM,SAAS,gBAAgB;CAG/B,MAAM,YADO,IAAI,gBACQ;CAKzB,IAAI;CACJ,IAAI,WAAW,cAAc,QAAQ,UAAU,MAAM,MACnD,OAAO,OAAO,MAAM,SAAS;EAAE,YAAY,UAAU;EAAY,IAAI,UAAU;CAAG,CAAC;CAMrF,MAAM,iBAAiB,YAAY;EACjC,UAAU;EACV;EACA,MAAM,QAAQ;CAChB,CAAC;CAED,OAAO,QAAQ,eAAe,WAAW,eAAe,OAAO;AACjE"}
+{"version":3,"file":"use-reactive-entity.js","names":[],"sources":["../../../src/sdk/data/use-reactive-entity.ts"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport { useApolloClient, useFragment } from '@apollo/client/react';\nimport { useContext } from 'react';\nimport { ReactiveRootContext } from './page-reactive-data-root.js';\n\ntype EntityRef = {\n  __typename?: string;\n  id?: string | number;\n};\n\nexport type ReactiveEntitySlice = Readonly<{\n  /** The slice descendants read: the cache's answer when there is one, `fallbackData` otherwise. */\n  data: unknown;\n  /**\n   * Is `data` the cache's own answer for the ref the page query currently holds? False whenever\n   * `fallbackData` is standing in for one under a live reactive root — the first render before the\n   * page query lands, a root whose query is skipped for want of a variable, an entity ref that has\n   * moved to a node this cache never stored, an evicted field. Always true with no reactive root\n   * above, where `fallbackData` is not a placeholder but the only answer there is.\n   */\n  resolved: boolean;\n}>;\n\n/**\n * Shared single-entity resolve logic used by BOTH `ReactiveDataProvider` and `EntitySubscriber`\n * (AD-4 / AD-D2).\n *\n * Reads the root query data exposed by `PageReactiveDataRoot` via context, derives the entity ref\n * for the configured `rootField`, and subscribes to the cache via `useFragment`. The hook never\n * triggers a network request — it is purely a cache reader. When the entity ref is unresolved or\n * the cache slice is incomplete, falls back to `fallbackData` (the server-rendered payload) so\n * descendants always see a value.\n *\n * This hook is intentionally single-entity: it has no notion of merging/composing multiple\n * entities' slices — that's layered on top by `EntitySubscriber`.\n *\n * See docs/storefront-core/reference-data-layer-runtime.md § Per-component subscription and rfc-data-layer.md §\"Reactive fetch\".\n */\nexport function useReactiveEntity(\n  entityFragment: DocumentNode,\n  fragmentName: string,\n  rootField: string,\n  fallbackData: unknown,\n): ReactiveEntitySlice {\n  const ctx = useContext(ReactiveRootContext);\n  const client = useApolloClient();\n\n  const root = ctx.rootQueryData as Record<string, unknown> | undefined;\n  const rootSlice = root?.[rootField] as EntityRef | null | undefined;\n\n  // Derive a stable cache identifier when both __typename and id are present. `cache.identify`\n  // returns undefined when the inputs are not normalisable (no id, no keyFields), which we treat\n  // the same as a missing ref — useFragment then has nothing to subscribe to.\n  let from: string | undefined;\n  if (rootSlice?.__typename != null && rootSlice.id != null) {\n    from = client.cache.identify({ __typename: rootSlice.__typename, id: rootSlice.id });\n  }\n\n  // useFragment must be called unconditionally to satisfy the Rules of Hooks. When `from` is\n  // undefined, Apollo's useFragment returns `{ data: {}, complete: false }` and never reads the\n  // cache. Pass an empty string as a sentinel so the hook is invoked but the read is a no-op.\n  const fragmentResult = useFragment({\n    fragment: entityFragment,\n    fragmentName,\n    from: from ?? '',\n  });\n\n  const hit = Boolean(from) && fragmentResult.complete;\n\n  // `hasRoot` is what separates \"no reactive runtime here\" from \"the reactive runtime has nothing\n  // for this entity right now\" — two states the rest of this context value cannot tell apart, since\n  // its own default carries `rootQueryData: undefined` exactly like a root whose query is skipped.\n  // Without the distinction a prop-driven tree (Storybook, a unit test) would report an unresolved\n  // slice forever and any caller gating on it would never render.\n  return { data: hit ? fragmentResult.data : fallbackData, resolved: !ctx.hasRoot || hit };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,kBACd,gBACA,cACA,WACA,cACqB;CACrB,MAAM,MAAM,WAAW,mBAAmB;CAC1C,MAAM,SAAS,gBAAgB;CAG/B,MAAM,YADO,IAAI,gBACQ;CAKzB,IAAI;CACJ,IAAI,WAAW,cAAc,QAAQ,UAAU,MAAM,MACnD,OAAO,OAAO,MAAM,SAAS;EAAE,YAAY,UAAU;EAAY,IAAI,UAAU;CAAG,CAAC;CAMrF,MAAM,iBAAiB,YAAY;EACjC,UAAU;EACV;EACA,MAAM,QAAQ;CAChB,CAAC;CAED,MAAM,MAAM,QAAQ,IAAI,KAAK,eAAe;CAO5C,OAAO;EAAE,MAAM,MAAM,eAAe,OAAO;EAAc,UAAU,CAAC,IAAI,WAAW;CAAI;AACzF"}

package/dist/sdk/generated/fragment-types.js

@@ -9,6 +9,8 @@ const possibleTypes = {
 		"ClientProfile",
 		"Collection",
 		"Customization",
+		"Order",
+		"Payment",
 		"Product",
 		"SalesChannel",
 		"Seller",

package/dist/sdk/generated/fragment-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"fragment-types.js","names":[],"sources":["../../../src/sdk/generated/fragment-types.ts"],"sourcesContent":["// @generated — DO NOT EDIT. Run `pnpm codegen` to regenerate.\nexport type PossibleTypes = Record<string, string[]>;\nexport const possibleTypes: PossibleTypes = {\n  Media: [\n    'Image',\n    'Video'\n  ],\n  Node: [\n    'Brand',\n    'Cart',\n    'Category',\n    'ClientPreferences',\n    'ClientProfile',\n    'Collection',\n    'Customization',\n    'Product',\n    'SalesChannel',\n    'Seller',\n    'Session',\n    'Shipping',\n    'Variant'\n  ]\n};\n"],"mappings":";AAEA,MAAa,gBAA+B;CAC1C,OAAO,CACL,SACA,OACF;CACA,MAAM;EACJ;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"fragment-types.js","names":[],"sources":["../../../src/sdk/generated/fragment-types.ts"],"sourcesContent":["// @generated — DO NOT EDIT. Run `pnpm codegen` to regenerate.\nexport type PossibleTypes = Record<string, string[]>;\nexport const possibleTypes: PossibleTypes = {\n  Media: [\n    'Image',\n    'Video'\n  ],\n  Node: [\n    'Brand',\n    'Cart',\n    'Category',\n    'ClientPreferences',\n    'ClientProfile',\n    'Collection',\n    'Customization',\n    'Order',\n    'Payment',\n    'Product',\n    'SalesChannel',\n    'Seller',\n    'Session',\n    'Shipping',\n    'Variant'\n  ]\n};\n"],"mappings":";AAEA,MAAa,gBAA+B;CAC1C,OAAO,CACL,SACA,OACF;CACA,MAAM;EACJ;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF;AACF"}