@envive-ai/react-hooks 0.3.62 → 0.3.64

package/src/services/enviveConfigService/fetchBootstrapConfig.ts

@@ -0,0 +1,276 @@
+import Logger from 'src/application/logging/logger';
+import type { UrlResolverResponse } from 'src/atoms/app/variant';
+import {
+  ExperimentConfigResolutionMetadata,
+  OrgConfigExperimentAssignment,
+  OrgConfigFeatureGate,
+} from 'src/application/models/api/orgConfigResults';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import { configVersionOverride } from 'src/types/config-versions';
+import { transformV3ProductsConfig } from './fetchGraphQLConfig';
+// Type-only import — erased at compile time, so this does not create a runtime
+// import cycle with enviveConfigService (which imports fetchBootstrapConfig).
+import type { EnviveServiceConfig } from './enviveConfigService';
+
+const logger = new Logger('fetchBootstrapConfig');
+
+// The url-resolving context bits the hooks layer can't derive on its own — the
+// injection bundle supplies env (a build-time var) and contextSource. org
+// identity is threaded from the getWidgetConfig response fetched moments earlier
+// (see enviveConfigService: bootstrap only runs on the gate-ON path, which reads
+// the gate off getWidgetConfig first, so org id/short_name are already in hand).
+export interface FetchBootstrapConfigParams {
+  baseUrl: string;
+  apiKey: string;
+  userId: string;
+  // Config `source` (Statsig user property), 'app' in the injection bundle.
+  source: string;
+  // Scopes org_config.configs to this namespace. REQUIRED: without it pymono
+  // returns EVERY namespace on the org — including internal-only configs (the AI
+  // system prompt, brand-voice instructions, etc.) — in the response the public
+  // bundle receives. The legacy /v1/org/config call scoped it the same way.
+  namespace: string;
+  gateNames: string[];
+  // url_resolving inputs:
+  url: string;
+  orgId: string;
+  orgShortName: string;
+  // Context `source` for url_resolving ('app' | 'playground'); may differ from
+  // the config `source` above (playground = Envive Hub).
+  contextSource: string;
+  env: string;
+  chatId?: string;
+  // The override-aware feature gates (FeatureFlagService.getFeatureFlags()), so
+  // client-side gate overrides (query/window/localStorage) reach page-variant
+  // resolution — same as the legacy /v1/url_resolving request. Bootstrap merges
+  // these OVER its own server-resolved gates. Harmlessly ignored by pymono until
+  // SessionBootstrapUrlResolvingRequest gains the `feature_gates` field (the
+  // schema allows unknown fields; the model is `extra='ignore'`), so the FE can
+  // ship ahead of the backend.
+  featureGates?: Record<string, boolean>;
+}
+
+export interface BootstrapResult {
+  config: EnviveServiceConfig;
+  // The initial page-variant result, ready to seed urlResolverAtom so the
+  // warm-up skips its own /v1/url_resolving call. null when bootstrap's
+  // (best-effort) url-resolving branch returned nothing.
+  urlResolving: UrlResolverResponse | null;
+}
+
+// --- raw wire shapes (POST /v1/session/bootstrap is REST snake_case) ---------
+
+interface RawFeatureGate {
+  name?: string;
+  value?: boolean;
+  group_name?: string | null;
+  rule_id?: string | null;
+}
+
+interface RawExperimentAssignment {
+  layer_name?: string;
+  namespace?: OrgConfigExperimentAssignment['namespace'];
+  allocated_experiment_name?: string | null;
+  group_name?: string | null;
+}
+
+interface RawResolution {
+  base_version?: string;
+  base_version_source?: string;
+}
+
+interface RawBootstrapResponse {
+  org_config?: {
+    org?: { org?: Record<string, string | undefined> };
+    gates?: RawFeatureGate[];
+  };
+  widget_config?: {
+    products_config?: Parameters<typeof transformV3ProductsConfig>[0];
+    // Read from widget_config (not org_config) to match getWidgetConfig — see the
+    // mapping below.
+    experiment_assignments?: RawExperimentAssignment[];
+    resolution?: RawResolution;
+  };
+  url_resolving?: UrlResolverResponse | null;
+}
+
+// gates arrive snake (`group_name`); getWidgetConfig's arrive camel. Only the
+// name/value are used for gate checks — groupName is carried for amplitude.
+const toBootstrapGates = (raw: RawFeatureGate[] | undefined): OrgConfigFeatureGate[] =>
+  (raw ?? []).map(g => ({
+    name: g.name,
+    value: g.value,
+    groupName: g.group_name ?? undefined,
+  }));
+
+// experiment_assignments already match the snake OrgConfigExperimentAssignment
+// wire shape (unlike getWidgetConfig's camel, which needs toExperimentAssignments).
+const toBootstrapAssignments = (
+  raw: RawExperimentAssignment[] | undefined,
+): OrgConfigExperimentAssignment[] =>
+  (raw ?? []).map(a => ({
+    layer_name: a.layer_name,
+    namespace: a.namespace,
+    allocated_experiment_name: a.allocated_experiment_name,
+    group_name: a.group_name,
+  }));
+
+// resolution is snake here (REST); getWidgetConfig's is camel (Ariadne).
+const toResolution = (
+  raw: RawResolution | undefined,
+): ExperimentConfigResolutionMetadata | undefined =>
+  raw ? { baseVersion: raw.base_version, baseVersionSource: raw.base_version_source } : undefined;
+
+// One round trip for the config the widget client needs at init: org identity +
+// gates + experiment assignments + productsConfig/resolution, PLUS the initial
+// url-resolving result — the consolidation of `GET /v1/org/config`, GraphQL
+// `me.getWidgetConfig`, and `POST /v1/url_resolving` behind Matt's endpoint.
+//
+// Raw fetch (the npm client `@spiffy-ai/commerce-api-client` has no bootstrap
+// method, same as getWidgetConfig). Throws on network/HTTP failure/timeout — the
+// caller (enviveConfigService) falls back to the getWidgetConfig config it already
+// holds, so a bootstrap problem degrades to the proven path rather than aborting
+// injection.
+//
+// Bootstrap is an OPTIONAL upgrade that BLOCKS the pre-first-paint critical path
+// (a second call after getWidgetConfig already succeeded), and we already hold a
+// usable getWidgetConfig config to fall back to — so it is tightly bounded. Kept
+// low so a slow/hung endpoint adds at most this much to first paint; on timeout
+// the fetch aborts and we fall back to getWidgetConfig. CALIBRATE against the
+// endpoint's real p99 before ramping the gate (a value below p99 will make normal
+// bootstraps false-abort into the fallback, defeating the consolidation).
+const BOOTSTRAP_TIMEOUT_MS = 1500;
+
+export const fetchBootstrapConfig = async ({
+  baseUrl,
+  apiKey,
+  userId,
+  source,
+  namespace,
+  gateNames,
+  url,
+  orgId,
+  orgShortName,
+  contextSource,
+  env,
+  chatId,
+  featureGates,
+}: FetchBootstrapConfigParams): Promise<BootstrapResult> => {
+  const version = configVersionOverride();
+
+  // Armed before fetch and kept live across response.json() (a stalled body read
+  // must also be interruptible), cleared in finally. On timeout the fetch rejects
+  // with an AbortError → maybeUpgradeToBootstrap's catch falls back to getWidgetConfig.
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), BOOTSTRAP_TIMEOUT_MS);
+  let result: RawBootstrapResponse;
+  try {
+    const response = await fetch(`${baseUrl}/v1/session/bootstrap`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        user_id: userId,
+        source,
+        // Scope org_config.configs to the widget namespace — WITHOUT this, pymono
+        // returns every namespace's configs (internal ones included) to the browser.
+        namespace,
+        include_feature_gates: gateNames,
+        version,
+        url_resolving: {
+          url,
+          context: {
+            user_id: userId,
+            org_id: orgId,
+            org_short_name: orgShortName,
+            chat_id: chatId ?? '',
+            source: contextSource,
+            env,
+          },
+          // Override-aware gates so client gate overrides reach page-variant
+          // resolution (bootstrap merges these over its server-resolved gates).
+          // Ignored by pymono until the endpoint gains the field — safe to ship early.
+          feature_gates: featureGates,
+          // The config-version override comes ONLY from the URL query param
+          // (configVersionOverride) — the same source getWidgetConfig uses. It must
+          // NOT come from getWidgetConfig's resolved version: on the gate-ON path
+          // that response is discarded, and bootstrap resolves the config version
+          // server-side (scoping url_resolving to that resolved version, if desired,
+          // belongs on the server — not a getWidgetConfig dependency here).
+          override_config_version: version,
+        },
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Bootstrap config request failed: ${response.statusText}`);
+    }
+    result = (await response.json()) as RawBootstrapResponse;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  // A 2xx with a missing/partial payload must NOT silently replace the known-good
+  // getWidgetConfig config with empty gates / mock products — that would disable the
+  // client session or drop experiments. Throw instead, so maybeUpgradeToBootstrap's
+  // catch falls back to the getWidgetConfig result it already holds. `gates` is
+  // required as a NON-EMPTY array: we always request the full gateNames list and
+  // only reach bootstrap because getWidgetConfig returned real gates, so an
+  // empty/absent gates response is degraded → fall back. (A products config that is
+  // present-but-malformed still degrades to mock below — only the top-level
+  // sections are required here.)
+  if (!result.org_config?.org?.org || !result.org_config?.gates?.length || !result.widget_config) {
+    throw new Error(
+      'Bootstrap config response missing required sections (org_config.org.org / org_config.gates / widget_config)',
+    );
+  }
+  const orgConfig = result.org_config;
+  const widgetConfig = result.widget_config;
+  // The guard above guarantees org.org at runtime; the `?? {}` only satisfies the
+  // type-narrowing (TS doesn't carry the optional-chain narrowing through the alias).
+  const orgOrg = orgConfig.org?.org ?? {};
+  const resolution = toResolution(widgetConfig.resolution);
+
+  // A malformed products config degrades to mock defaults WITHOUT losing the
+  // org / gates / experiments that came back fine — mirrors fetchUnifiedGraphQLConfig.
+  let orgConfigValues: GraphQlConfigValues;
+  try {
+    orgConfigValues = { ...transformV3ProductsConfig(widgetConfig.products_config), resolution };
+  } catch (err) {
+    logger.logError('fetchBootstrapConfig | Error transforming products config', err);
+    orgConfigValues = { colorsConfig: undefined, frontendConfig: undefined, resolution };
+  }
+
+  const config: EnviveServiceConfig = {
+    // org_config is byte-identical to the legacy /v1/org/config (snake), the
+    // exact shape EnviveServiceConfig.org was built to hold. Constructed
+    // defensively (like fetchUnifiedGraphQLConfig) rather than passed through.
+    org: {
+      org: {
+        id: orgOrg.id ?? '',
+        short_name: orgOrg.short_name ?? '',
+        display_name: orgOrg.display_name ?? '',
+        domain: orgOrg.domain ?? '',
+        status: orgOrg.status ?? '',
+        created_at: orgOrg.created_at ?? '',
+        updated_at: orgOrg.updated_at ?? '',
+      },
+    },
+    gates: toBootstrapGates(orgConfig.gates),
+    // From widget_config, NOT org_config: getWidgetConfig sources assignments from
+    // its widget config (ungated), whereas bootstrap's `org_config.experiment_assignments`
+    // is populated ONLY when the `use_unified_config` gate evaluates true SERVER-SIDE
+    // (pymono `unified_config_active`). Reading org_config would drop assignments —
+    // and the amplitude `experiment.{ns}.*` enrichment — on the client-override test
+    // path (gate ON via `?use_unified_config=true` but 0% server-side). widget_config
+    // matches getWidgetConfig in every case (equal when the gate is on; version pin
+    // empties both).
+    experiment_assignments: toBootstrapAssignments(widgetConfig.experiment_assignments),
+    orgConfig: orgConfigValues,
+  };
+
+  return { config, urlResolving: result.url_resolving ?? null };
+};

package/src/services/enviveConfigService/fetchGraphQLConfig.ts

@@ -151,10 +151,13 @@ const v3FrontendConfigCleanup = (
   };
 };
 
-// Turns a raw productsConfig payload (from getProductsConfigByVersion or
-// getWidgetConfig) into the camelCase GraphQlConfigValues shape the rest of
-// the toolkit consumes. Returns mock config when colors are absent.
-const transformV3ProductsConfig = (
+// Turns a raw productsConfig payload (from getProductsConfigByVersion,
+// getWidgetConfig, or the /v1/session/bootstrap widget_config) into the
+// camelCase GraphQlConfigValues shape the rest of the toolkit consumes.
+// Returns mock config when colors are absent. Exported so fetchBootstrapConfig
+// reuses the exact same transform (bootstrap's products_config carries the same
+// `.{section}.values` shape as getWidgetConfig's productsConfig).
+export const transformV3ProductsConfig = (
   productsConfig:
     | {
         frontend?: { values?: { merchant_override_css?: string } };

package/src/services/ga4ProjectionService/ga4EventSchema.ts

@@ -156,4 +156,9 @@ export const GA4_EVENT_SCHEMA: Record<EnviveMetricsEventName, GA4EventSchemaEntr
   [EnviveMetricsEventName.WidgetTextClicked]: {
     gaEventName: null,
   },
+
+  // Internal eng operational monitoring — never projected to merchant GA4.
+  [EnviveMetricsEventName.Diagnostics]: {
+    gaEventName: null,
+  },
 };

package/src/services/hardcopyService/__tests__/hardcopyService.test.ts

@@ -4,7 +4,12 @@ import type { AppDetails } from 'src/atoms/app';
 import { EnviveMetricsEventName, TrackEventParams } from 'src/services/amplitudeService';
 import { getAtomStore } from 'src/atoms/atomStore/atomStore';
 import { resolvedBaseConfigVersionAtom } from 'src/atoms/envive/resolvedBaseConfigVersion';
-import { HardcopyService, MOCK_HARDCOPY_RESPONSE, MockHardcopyService } from '../hardcopyService';
+import {
+  HARDCOPY_TIMEOUT_MS,
+  HardcopyService,
+  MOCK_HARDCOPY_RESPONSE,
+  MockHardcopyService,
+} from '../hardcopyService';
 
 const { MockLogger, mockGetHardcopy, mockGetQueryParam } = vi.hoisted(() => {
   const MockLogger = vi.fn(function () {
@@ -87,6 +92,7 @@ describe('HardcopyService', () => {
           titleLabel: 'Hello World',
           promptButtonTexts: ['Prompt 1', 'Prompt 2'],
         },
+        servedFrom: 'api',
       });
     });
 
@@ -269,6 +275,38 @@ describe('HardcopyService', () => {
       );
     });
 
+    it.each([
+      [WidgetTypeV3.ProductCardV3, 'ImagePromptCardV3'],
+      [WidgetTypeV3.PromptButtonCarouselWithImageV3, 'SingleImagePromptV3'],
+    ])(
+      'stamps the API-facing (translated) widget type on both events: %s → %s',
+      async (internalType, wireType) => {
+        // The AI-suggestions accounting joins these events against the backend registry,
+        // which is keyed by the wire type. Stamping the internal name zeroed the stats
+        // for aliased widgets (Naturalizer PLP).
+        const trackEvent = vi.fn();
+        mockGetHardcopy.mockResolvedValueOnce(makeWidgetTextResponse());
+
+        await makeService(trackEvent).getHardcopy({
+          widgetType: internalType,
+          userEvent: {} as any,
+        });
+
+        expect(trackEvent).toHaveBeenCalledWith(
+          expect.objectContaining({
+            eventName: EnviveMetricsEventName.WidgetTextRequest,
+            eventProps: expect.objectContaining({ widget_type: wireType }),
+          }),
+        );
+        expect(trackEvent).toHaveBeenCalledWith(
+          expect.objectContaining({
+            eventName: EnviveMetricsEventName.WidgetTextResponse,
+            eventProps: expect.objectContaining({ widget_type: wireType }),
+          }),
+        );
+      },
+    );
+
     it('forwards ai_suggestions_attribution_by_slot on WidgetTextResponse when present', async () => {
       const trackEvent = vi.fn();
       const attribution = {
@@ -346,7 +384,11 @@ describe('HardcopyService', () => {
         userEvent: {} as any,
       });
 
-      expect(result).toBe(MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3]);
+      expect(result).toEqual({
+        ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
+        servedFrom: 'static',
+        fallbackReason: 'error',
+      });
     });
 
     it('returns the MOCK_HARDCOPY_RESPONSE entry when the API returns falsy', async () => {
@@ -357,7 +399,11 @@ describe('HardcopyService', () => {
         userEvent: {} as any,
       });
 
-      expect(result).toBe(MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.SocialProofV3]);
+      expect(result).toEqual({
+        ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.SocialProofV3],
+        servedFrom: 'static',
+        fallbackReason: 'error',
+      });
     });
 
     it('does not fire WidgetTextResponse when falling back to mock', async () => {
@@ -385,6 +431,30 @@ describe('HardcopyService', () => {
         }),
       ).rejects.toThrow('No hardcopy response found for widget type: UnknownWidget');
     });
+
+    it('falls back to the mock when the API request hangs past the timeout', async () => {
+      // A request that never settles — the timeout is the only thing that can release it.
+      // Without it the widget's loading latch never resolves ("PLP staying in loading state").
+      vi.useFakeTimers();
+      try {
+        mockGetHardcopy.mockReturnValueOnce(new Promise(() => {}));
+
+        const resultPromise = makeService().getHardcopy({
+          widgetType: WidgetTypeV3.PromptCarouselV3,
+          userEvent: {} as any,
+        });
+
+        await vi.advanceTimersByTimeAsync(HARDCOPY_TIMEOUT_MS);
+
+        await expect(resultPromise).resolves.toEqual({
+          ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
+          servedFrom: 'static',
+          fallbackReason: 'timeout',
+        });
+      } finally {
+        vi.useRealTimers();
+      }
+    });
   });
 });
 

package/src/services/hardcopyService/hardcopyService.ts

@@ -4,6 +4,7 @@ import { WidgetString, WidgetText } from 'src/application/models/api/widgetText'
 import { WidgetTextRequest } from 'src/application/models/api/widgetTextRequest';
 import { toCamelCase } from 'src/application/models/utils/snakeToCamelTransformer';
 import { getQueryParam } from 'src/application/utils';
+import { coreWidgetTypeToApiWidgetType } from 'src/application/utils/widgetTextRequestToApiRequest';
 import { UserEvent } from 'src/application/models';
 import Logger from 'src/application/logging/logger';
 import { AppDetails } from 'src/atoms/app';
@@ -14,6 +15,30 @@ import { EnviveMetricsEventName, TrackEventParams } from '../amplitudeService';
 
 const logger = new Logger('hardcopyService');
 
+// Longest a hardcopy request may hang before we stop waiting for it. The backend-error
+// path below already falls back to static copy, but a request that never settles at all
+// never reaches that catch — it left the widget's loading latch unresolved forever, which
+// is the "PLP staying in loading state" failure. Racing the request against this timeout
+// turns a hang into the same fallback path an error takes, so the widget always leaves its
+// loading state.
+//
+// Kept under the ~4-5s at which session replays show shoppers abandon a still-loading
+// widget: a rescue that fires after they've left helps no one. When it fires, the catch
+// below logs an error (message includes "timed out") — that log is the signal monitoring
+// can count to measure how often hardcopy stalls.
+export const HARDCOPY_TIMEOUT_MS = 4000;
+
+// Reject if `promise` has not settled within `ms`. The underlying request is not aborted
+// (a late response is simply discarded) — the only goal is to stop *waiting*, so the
+// caller's error handling can run.
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> => {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`hardcopy request timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)) as Promise<T>;
+};
+
 export interface HardcopyRequest {
   widgetType: WidgetTypeV3;
   userEvent: UserEvent;
@@ -24,6 +49,10 @@ export type HardcopyResponse = {
   language: string;
   rawValues?: Record<string, WidgetString | WidgetString[]>;
   values: Record<string, string | string[]>;
+  // How the copy was served, for widget-load diagnostics: 'api' = live backend response,
+  // 'static' = fell back to the bundled MOCK_HARDCOPY_RESPONSE after a backend error or timeout.
+  servedFrom?: 'api' | 'static';
+  fallbackReason?: 'timeout' | 'error';
 };
 
 export interface IHardcopyService {
@@ -218,23 +247,42 @@ export class HardcopyService implements IHardcopyService {
       url: window.location.href,
     };
 
+    // The Widget Text events must carry the API-facing (translated) widget type, not the
+    // internal one: the AI-suggestions accounting joins these events against the backend
+    // registry, which is keyed by the wire type (e.g. ProductCardV3 is sent — and stored —
+    // as ImagePromptCardV3). Stamping the internal name here zeroed those stats. An
+    // unmapped type keeps the internal name — analytics must never block serving.
+    let wireWidgetType: string = request.widgetType;
+    try {
+      wireWidgetType = coreWidgetTypeToApiWidgetType(request.widgetType);
+    } catch {
+      logger.logDebug('no wire mapping for widget type — keeping internal name', {
+        widgetType: request.widgetType,
+      });
+    }
+
     this.config.trackEvent?.({
       eventName: EnviveMetricsEventName.WidgetTextRequest,
       eventProps: {
-        widget_type: request.widgetType,
+        widget_type: wireWidgetType,
         request_id: widgetTextRequest.requestId,
       },
     });
 
+    // Reason the API path failed, surfaced on the static fallback for widget-load diagnostics.
+    let fallbackReason: 'timeout' | 'error' | undefined;
     try {
-      const response = await CommerceApiClient.getHardcopy(widgetTextRequest);
+      const response = await withTimeout(
+        CommerceApiClient.getHardcopy(widgetTextRequest),
+        HARDCOPY_TIMEOUT_MS,
+      );
       if (response) {
         const convertedResponse = convertToHardcopyResponse(response);
         logger.logDebug('converted response', convertedResponse);
         this.config.trackEvent?.({
           eventName: EnviveMetricsEventName.WidgetTextResponse,
           eventProps: {
-            widget_type: request.widgetType,
+            widget_type: wireWidgetType,
             response_id: response.responseId,
             widget_text: response.values,
             request_id: widgetTextRequest.requestId,
@@ -245,16 +293,18 @@ export class HardcopyService implements IHardcopyService {
               : {}),
           },
         });
-        return convertedResponse;
+        return { ...convertedResponse, servedFrom: 'api' };
       }
     } catch (error) {
       logger.logError('error getting hardcopy from backend', error);
+      fallbackReason =
+        error instanceof Error && error.message.includes('timed out') ? 'timeout' : 'error';
     }
 
     const mockResponse = MOCK_HARDCOPY_RESPONSE[request.widgetType];
     if (mockResponse) {
       logger.logDebug('no real response, using mock', mockResponse);
-      return mockResponse;
+      return { ...mockResponse, servedFrom: 'static', fallbackReason: fallbackReason ?? 'error' };
     }
     throw new Error(`No hardcopy response found for widget type: ${request.widgetType}`);
   }

package/src/services/urlResolverWarmupService/__tests__/urlResolverWarmupService.test.ts

@@ -4,6 +4,7 @@ import { contextSourceAtom, envAtom, enviveConfigAtom } from 'src/atoms/envive/e
 import { featureFlagServiceAtom } from 'src/atoms/org/graphqlConfig';
 import { FeatureFlagService } from 'src/services/featureFlagService';
 import type { EnviveServiceConfig } from 'src/services/enviveConfigService';
+import { type UrlResolverResponse, urlResolverAtom } from 'src/atoms/app/variant';
 import { warmUrlResolver } from '../index';
 
 const { mockResolveUrl } = vi.hoisted(() => ({ mockResolveUrl: vi.fn() }));
@@ -82,4 +83,58 @@ describe('warmUrlResolver', () => {
     expect(getAtomStore().get(featureFlagServiceAtom)).toBeUndefined();
     expect(mockResolveUrl).toHaveBeenCalledTimes(1);
   });
+
+  it('seeds urlResolverAtom from precomputedUrlResolving when its URL matches, skipping resolveUrl', async () => {
+    // The bootstrap-consolidated path: /v1/session/bootstrap already resolved
+    // the URL, so the warm-up must NOT fire a second /v1/url_resolving.
+    const response = {
+      variant_type: 'pdp',
+      specific_details: {},
+      ready: true,
+    } as unknown as UrlResolverResponse;
+    const cleansedUrl = window.location.href.toLowerCase().trim();
+
+    await warmUrlResolver({
+      ...baseParams,
+      env: 'prod',
+      contextSource: 'app',
+      featureFlagService: new FeatureFlagService([]),
+      precomputedUrlResolving: { url: cleansedUrl, response },
+    });
+
+    expect(mockResolveUrl).not.toHaveBeenCalled();
+    expect(getAtomStore().get(urlResolverAtom)[cleansedUrl]).toEqual(response);
+  });
+
+  it('falls back to resolveUrl when the precomputed URL no longer matches (SPA nav during bootstrap)', async () => {
+    // Bootstrap resolved a DIFFERENT URL (a nav happened since) — its result must
+    // NOT be cached under the current URL; resolve the current URL instead.
+    const staleResponse = {
+      variant_type: 'plp',
+      specific_details: {},
+      ready: true,
+    } as unknown as UrlResolverResponse;
+    mockResolveUrl.mockResolvedValue({ variant_type: 'pdp', ready: true });
+
+    await warmUrlResolver({
+      ...baseParams,
+      env: 'prod',
+      contextSource: 'app',
+      featureFlagService: new FeatureFlagService([]),
+      precomputedUrlResolving: { url: 'https://other.example/stale', response: staleResponse },
+    });
+
+    expect(mockResolveUrl).toHaveBeenCalledTimes(1);
+    const cleansedUrl = window.location.href.toLowerCase().trim();
+    expect(getAtomStore().get(urlResolverAtom)[cleansedUrl]).toEqual({
+      variant_type: 'pdp',
+      ready: true,
+    });
+  });
+
+  it('falls back to resolveUrl when precomputedUrlResolving is null (getWidgetConfig path)', async () => {
+    await warmUrlResolver({ ...baseParams, precomputedUrlResolving: null });
+
+    expect(mockResolveUrl).toHaveBeenCalledTimes(1);
+  });
 });

package/src/services/urlResolverWarmupService/index.ts

@@ -19,6 +19,15 @@ export interface WarmUrlResolverParams {
   env?: string;
   contextSource?: string;
   featureFlagService?: FeatureFlagService;
+  // The url_resolving result /v1/session/bootstrap already produced (unified-config
+  // gate ON), paired with the URL it was resolved for. When set AND that URL still
+  // matches the current one, the warm-up seeds urlResolverAtom with it and skips
+  // its own /v1/url_resolving call — the third leg of the 3→1 consolidation. If a
+  // SPA navigation changed the URL since bootstrap ran, the URLs no longer match
+  // and the warm-up falls back to resolveUrl (so a stale variant is never cached
+  // under the new URL). The atom-seeding above still runs either way, so
+  // PageProvider (and any later navigation resolveUrl) sees the same context.
+  precomputedUrlResolving?: { url: string; response: UrlResolverResponse } | null;
 }
 
 /**
@@ -43,6 +52,7 @@ export const warmUrlResolver = async ({
   env,
   contextSource,
   featureFlagService,
+  precomputedUrlResolving,
 }: WarmUrlResolverParams): Promise<void> => {
   try {
     const store = getAtomStore();
@@ -79,7 +89,14 @@ export const warmUrlResolver = async ({
       store.set(resolvedBaseConfigVersionAtom, baseVersion);
     }
 
-    const response = (await CommerceApiClient.resolveUrl(cleansedUrl)) as UrlResolverResponse;
+    // Bootstrap already resolved a URL in the same round trip as the config —
+    // reuse it ONLY when it's still the current URL, so its variant is never
+    // cached under a different key after a SPA navigation. Otherwise resolve the
+    // current URL ourselves (same as the no-precompute path).
+    const response =
+      precomputedUrlResolving && precomputedUrlResolving.url === cleansedUrl
+        ? precomputedUrlResolving.response
+        : ((await CommerceApiClient.resolveUrl(cleansedUrl)) as UrlResolverResponse);
     store.set(urlResolverAtom, { url: cleansedUrl, response });
   } catch (err) {
     // Fail open: PageProvider issues its own resolveUrl call when the cache