@salesforce/storefront-next-runtime 0.2.0 → 0.3.0-alpha.1

package/dist/schema.d.ts

@@ -0,0 +1,78 @@
+//#region src/config/schema.d.ts
+/**
+ * Base configuration type for storefront-next projects.
+ *
+ * Generic parameter `App` represents the template's application config shape.
+ * The SDK does not prescribe what fields `app` must contain — templates define
+ * their own `AppConfig` type with SCAPI credentials, pages, features, etc.
+ * and pass it as `BaseConfig<AppConfig>`.
+ *
+ * The SDK accesses specific `app` fields (e.g., `commerce.api.clientId`) at
+ * runtime via the middleware validation, not via compile-time type constraints.
+ *
+ * @typeParam App - The template's application config shape (defaults to `Record<string, unknown>`)
+ *
+ * @example
+ * // In the template's types file:
+ * type AppConfig = { commerce: { api: {...} }; pages: {...}; features: {...} };
+ * type Config = BaseConfig<AppConfig>;
+ *
+ * // In config.server.ts:
+ * export default defineConfig<Config>({ metadata: {...}, app: {...} });
+ */
+type BaseConfig<App extends Record<string, unknown> = Record<string, unknown>> = {
+  metadata: {
+    projectName: string;
+    projectSlug: string;
+  };
+  runtime?: {
+    defaultMrtProject?: string;
+    defaultMrtTarget?: string;
+    ssrOnly?: string[];
+    ssrShared?: string[];
+    ssrParameters?: Record<string, string | number | boolean>;
+  };
+  app: App;
+};
+interface DefineConfigOptions {
+  /**
+   * Config paths that cannot be overridden by environment variables.
+   * Paths use double underscore separators and are matched case-insensitively.
+   *
+   * @example ['app__engagement'] — prevents PUBLIC__app__engagement__* from being set via env
+   */
+  protectedPaths?: string[];
+}
+/**
+ * Define a type-safe storefront configuration with IDE autocomplete.
+ *
+ * Automatically merges `PUBLIC__` prefixed environment variables into the config
+ * at load time. Validates env vars against the base config structure (strict mode —
+ * only allows overriding existing paths).
+ *
+ * Environment variables:
+ * - `PUBLIC__<path>` (optional): Override any config path using double underscore separators.
+ *   e.g. `PUBLIC__app__commerce__api__clientId=abc123` maps to `config.app.commerce.api.clientId`
+ * - `PUBLIC__app__pages__cart__quantityUpdateDebounce=1000` maps to a number (optimistic JSON parsing)
+ * - `PUBLIC__app__features__socialLogin__providers=["Apple","Google"]` maps to an array
+ *
+ * @param config - The base configuration object with all defaults
+ * @param options - Optional settings (e.g., protectedPaths to prevent env var overrides)
+ * @returns The config with environment variable overrides merged in
+ *
+ * @example
+ * // In config.server.ts:
+ * import { defineConfig } from '@salesforce/storefront-next-runtime/config';
+ *
+ * export default defineConfig({
+ *     metadata: { projectName: 'My Store', projectSlug: 'my-store' },
+ *     app: {
+ *         commerce: { api: { clientId: '', organizationId: '', shortCode: '' }, sites: [] },
+ *         defaultSiteId: 'RefArch',
+ *     },
+ * }, { protectedPaths: ['app__engagement'] });
+ */
+declare function defineConfig<T extends BaseConfig>(config: T, options?: DefineConfigOptions): T;
+//#endregion
+export { DefineConfigOptions as n, defineConfig as r, BaseConfig as t };
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","names":[],"sources":["../src/config/schema.ts"],"sourcesContent":[],"mappings":";;AAsCA;;;;;;AAeA;AAuCA;;;;;;;;;;;;;KAtDY,uBAAuB,0BAA0B;;;;;;;;;;oBAUrC;;OAEf;;UAGQ,mBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCD,uBAAuB,oBAAoB,aAAa,sBAAsB"}

package/dist/{multi-site.d.ts → site-context.d.ts}

@@ -1,12 +1,49 @@
 import { n as Site$1, r as Url, t as Locale$1 } from "./types.js";
 import { PropsWithChildren } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime2 from "react/jsx-runtime";
 import * as react_router0 from "react-router";
 import { Cookie, MiddlewareFunction, RouterContextProvider } from "react-router";
 import { RouteConfigEntry } from "@react-router/dev/routes";
 
-//#region src/multi-site/site-context.d.ts
+//#region src/site-context/types.d.ts
 
+type Locale = Locale$1 & {
+  alias?: string;
+};
+type Site = Omit<Site$1, 'supportedLocales'> & {
+  name?: string;
+  alias?: string;
+  supportedLocales: Locale[];
+};
+type SiteContext = {
+  site: Site;
+  locale: Locale;
+  siteCookie: Cookie;
+  localeCookie: Cookie;
+};
+/**
+ * Configuration passed into the site context middleware
+ * Configured by the consumer
+ */
+type SiteConfig = {
+  sites: Site[];
+  defaultSiteId: string;
+  defaultLocale: string;
+  siteDetectionConfig?: DetectionConfig;
+  localeDetectionConfig?: DetectionConfig;
+};
+/** Detection method identifier (used for both site and locale detection) */
+type DetectionMethod = 'path' | 'querystring' | 'cookie' | 'header';
+type DetectionConfig = {
+  order: DetectionMethod[];
+  lookupFromPathIndex?: number;
+  lookupQuerystring?: string;
+  lookupCookie?: string;
+  lookupHeader?: string;
+  caches?: Array<'cookie'>;
+};
+//#endregion
+//#region src/site-context/site-context.d.ts
 /**
  * Provides the current site to the component tree.
  * Follows the same pattern as CurrencyProvider.
@@ -18,18 +55,17 @@ declare function SiteProvider({
   value,
   children
 }: PropsWithChildren<{
-  value: Site$1;
-}>): react_jsx_runtime0.JSX.Element;
+  value: Site;
+}>): react_jsx_runtime2.JSX.Element;
 /**
  * React hook to get the current site.
  * Returns undefined when no SiteProvider is mounted.
  */
-declare function useSite(): Site$1 | undefined;
+declare function useSite(): Site | undefined;
 //#endregion
-//#region src/multi-site/apply-url-config.d.ts
-
+//#region src/site-context/apply-url-config.d.ts
 /**
- * Applies multi-site URL configuration to a set of route entries.
+ * Applies site context URL configuration to a set of route entries.
  *
  * Wraps non-excluded routes under a parent route with the configured URL prefix
  * (e.g. `/:siteId/:localeId`), while keeping excluded routes (action/resource by default)
@@ -48,12 +84,38 @@ declare function applyUrlConfig(options: {
   wrapperFile: string;
 }): RouteConfigEntry[];
 //#endregion
-//#region src/multi-site/build-url.d.ts
-
+//#region src/site-context/build-url.d.ts
 /**
- * Builds a fully-qualified URL with multi-site prefix and search params.
+ * Resolves a prefix template by replacing parameter placeholders with values.
+ * ('/:siteId/:localeId', { siteId: 'global', localeId: 'en-GB' }) → '/global/en-GB'
+ */
+declare function resolvePrefix(prefix: string, params: Record<string, string>): string;
+/**
+ * Strips the URL prefix segments from a pathname based on a prefix pattern.
+ * Since all routes are configured with the prefix baked in, segment counting is sufficient.
  *
- * Only keys defined in urlConfig.search are set by multi-site. Any other query params
+ * @param pathname - Full pathname (e.g. '/global/en-GB/checkout')
+ * @param prefixPattern - URL prefix pattern from config (e.g. '/:siteId/:localeId')
+ * @returns Pathname with prefix stripped (e.g. '/checkout'), or original if
+ *          the pathname has fewer segments than the prefix
+ *
+ * @example
+ * stripPathPrefix('/global/en-GB/checkout', '/:siteId/:localeId') // → '/checkout'
+ * stripPathPrefix('/checkout', '/:siteId/:localeId')              // → '/checkout' (fewer segments → unchanged)
+ * stripPathPrefix('/checkout', '')                                 // → '/checkout' (no prefix configured)
+ * stripPathPrefix('/', '/:siteId/:localeId')                      // → '/'
+ */
+declare function stripPathPrefix(pathname: string, prefixPattern: string): string;
+/**
+ * Sanitize a resolved prefix from a pathname if present.
+ * sanitizePrefix('/global/en-GB/product/123', '/global/en-GB') → '/product/123'
+ * sanitizePrefix('/product/123', '/global/en-GB') → '/product/123'   (no-op)
+ */
+declare function sanitizePrefix(pathname: string, pathPrefix: string): string;
+/**
+ * Builds a fully-qualified URL with site context prefix and search params.
+ *
+ * Only keys defined in urlConfig.search are set by site context. Any other query params
  * already present on the `to` URL (including duplicate keys) are preserved as-is.
  * e.g. to='/api/search?refine=color:blue&refine=size:M', search='?lng=:localeId'
  *   → '/api/search?refine=color:blue&refine=size:M&lng=en-GB'
@@ -72,47 +134,10 @@ declare function buildUrl({
   params: Record<string, string>;
 }): string;
 //#endregion
-//#region src/multi-site/types.d.ts
-type Locale = Locale$1 & {
-  alias?: string;
-};
-type Site = Omit<Site$1, 'supportedLocales'> & {
-  name?: string;
-  alias?: string;
-  supportedLocales: Locale[];
-};
-type MultiSiteContext = {
-  site: Site;
-  locale: Locale;
-  siteCookie: Cookie;
-  localeCookie: Cookie;
-};
-/**
- * Configuration passed into the multi-site middleware
- * Configured by the consumer
- */
-type MultiSiteConfig = {
-  sites: Site[];
-  defaultSiteId: string;
-  defaultLocale: string;
-  siteDetectionConfig?: DetectionConfig;
-  localeDetectionConfig?: DetectionConfig;
-};
-/** Detection method identifier (used for both site and locale detection) */
-type DetectionMethod = 'path' | 'querystring' | 'cookie' | 'header';
-type DetectionConfig = {
-  order: DetectionMethod[];
-  lookupFromPathIndex?: number;
-  lookupQuerystring?: string;
-  lookupCookie?: string;
-  lookupHeader?: string;
-  caches?: Array<'cookie'>;
-};
-//#endregion
-//#region src/multi-site/middleware.d.ts
-declare const multiSiteContext: react_router0.RouterContext<MultiSiteContext | null>;
+//#region src/site-context/middleware.d.ts
+declare const siteContext: react_router0.RouterContext<SiteContext | null>;
 /**
- * Helper function to get multi-site cookies from router context.
+ * Helper function to get site context cookies from router context.
  * Useful in server actions and loaders that need to read/set cookies.
  *
  * @param context - Router context provider
@@ -121,7 +146,7 @@ declare const multiSiteContext: react_router0.RouterContext<MultiSiteContext | n
  * @example
  * ```typescript
  * export const action: ActionFunction = async ({ request, context }) => {
- *     const cookies = getMultiSiteCookies(context);
+ *     const cookies = getSiteContextCookies(context);
  *     if (cookies) {
  *         const cookieHeader = await cookies.localeCookie.serialize(locale);
  *         // ... use cookieHeader
@@ -129,26 +154,26 @@ declare const multiSiteContext: react_router0.RouterContext<MultiSiteContext | n
  * };
  * ```
  */
-declare function getMultiSiteCookies(context: Readonly<RouterContextProvider>): {
+declare function getSiteContextCookies(context: Readonly<RouterContextProvider>): {
   siteCookie: react_router0.Cookie;
   localeCookie: react_router0.Cookie;
 } | null;
 /**
- * Creates a multi-site middleware that resolves the current site from
+ * Creates a site context middleware that resolves the current site from
  * the request (path, cookie, header, query, or default) and stores the
  * result in the router context.
  *
  * Does not import or read from app config context; the consumer supplies config.
  */
-declare function createMultiSiteMiddleware(config: MultiSiteConfig): MiddlewareFunction<Response>;
+declare function createSiteContextMiddleware(config: SiteConfig): MiddlewareFunction<Response>;
 //#endregion
-//#region src/multi-site/cookies.d.ts
+//#region src/site-context/cookies.d.ts
 /**
- * WeakMap to pass resolved locale from multi-site middleware to i18next's findLocale.
+ * WeakMap to pass resolved locale from site context middleware to i18next's findLocale.
  * WeakMap allows garbage collection when requests are done.
  * This is necessary because findLocale() only receives the Request object, not the router context.
  */
 declare const requestToLocaleMap: WeakMap<Request, string>;
 //#endregion
-export { type DetectionConfig, type Locale, type MultiSiteConfig, type MultiSiteContext, type Site, SiteProvider, applyUrlConfig, buildUrl, createMultiSiteMiddleware, getMultiSiteCookies, multiSiteContext, requestToLocaleMap, useSite };
-//# sourceMappingURL=multi-site.d.ts.map
+export { type DetectionConfig, type Locale, type Site, type SiteConfig, type SiteContext, SiteProvider, applyUrlConfig, buildUrl, createSiteContextMiddleware, getSiteContextCookies, requestToLocaleMap, resolvePrefix, sanitizePrefix, siteContext, stripPathPrefix, useSite };
+//# sourceMappingURL=site-context.d.ts.map

package/dist/site-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-context.d.ts","names":[],"sources":["../src/site-context/types.ts","../src/site-context/site-context.tsx","../src/site-context/apply-url-config.ts","../src/site-context/build-url.ts","../src/site-context/middleware.ts","../src/site-context/cookies.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAiCgB,KAbJ,MAAA,GAAS,QAaL,GAAA;EACE,KAAA,CAAA,EAAA,MAAA;CAAM;AAOZ,KAjBA,IAAA,GAAO,IAiBG,CAjBE,MAiBF,EAAA,kBAAA,CAAA,GAAA;EACX,IAAA,CAAA,EAAA,MAAA;EAGe,KAAA,CAAA,EAAA,MAAA;EACE,gBAAA,EAnBN,MAmBM,EAAA;CAAe;AAc/B,KA9BA,WAAA,GA8Be;EAGf,IAAA,EAhCF,IAgCE;UA/BA;cACI;gBACE;ACPlB,CAAA;;;;;AAAoF,KDcxE,UAAA,GCdwE;EAAA,KAAA,EDezE,ICfyE,EAAA;EASpE,aAAO,EAAA,MAAA;;wBDSG;0BACE;AE0E5B,CAAA;ACnBA;AAmBgB,KH5DJ,eAAA,GG4DY,MAAA,GAAA,aAAA,GAAA,QAAA,GAAA,QAAA;AACpB,KH1DQ,eAAA,GG0DR;EACA,KAAA,EH1DO,eG0DP,EAAA;EACA,mBAAA,CAAA,EAAA,MAAA;EAGY,iBAAA,CAAA,EAAA,MAAA;EACJ,YAAA,CAAA,EAAA,MAAA;EAAM,YAAA,CAAA,EAAA,MAAA;WH1DL;;;;;;;AA5Bb;;;;AAK2C,iBCnB3B,YAAA,CDmB2B;EAAA,KAAA;EAAA;AAiB3C,CAjB2C,ECnBO,iBDmBP,CAAA;EAc/B,KAAA,ECjCiE,IDiCjE;AAGZ,CAAA,CAAA,CAAA,ECpCoF,kBAAA,CAAA,GAAA,CAAA,ODqCzE;;;;ACrCX;AAA+B,iBASf,OAAA,CAAA,CATe,EASJ,IATI,GAAA,SAAA;;;;AC6F/B;;;;;;;;AC/DA;AA0BA;AAkBA;AAmBA;;AAEI,iBDFY,cAAA,CCEZ,OAAA,EAAA;EACA,MAAA,EDFQ,gBCER,EAAA;EAGY,SAAA,CAAA,EDJA,GCIA;EACJ,WAAA,EAAA,MAAA;CAAM,CAAA,EDHd,gBCGc,EAAA;;;;;AF3FlB;;iBEqBgB,aAAA,yBAAsC;;AD+DtD;;;;;;;;AC/DA;AA0BA;AAkBA;AAmBA;;;AAGI,iBAxCY,eAAA,CAwCZ,QAAA,EAAA,MAAA,EAAA,aAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;;;iBAtBY,cAAA;AC9EhB;AAsBA;;;;;;AAoEA;;;;;iBDOgB,QAAA;;;;;;cAMA;EEnFH,MAAA,EFoFD,MEpFC,CAAA,MAAmD,EAAA,MAAA,CAAA;;;;ALVhD,cIVH,WJUG,EIVQ,aAAA,CAAA,aJUR,CIVQ,WJUR,GAAA,IAAA,CAAA;;;AAQhB;;;;;AAmBA;AAGA;;;;ACpCA;;;;;;AAAoF,iBGkBpE,qBAAA,CHlBoE,OAAA,EGkBrC,QHlBqC,CGkB5B,qBHlB4B,CAAA,CAAA,EAAA;EASpE,UAAO,EGSgC,aAAA,CAAA,MHTxB;;;;ACoF/B;;;;;;iBEPgB,2BAAA,SAAoC,aAAa,mBAAmB;;;;;;;;AH7EpE,cIOH,kBJPkB,EIOA,OJPA,CIOA,OJPA,EAAA,MAAA,CAAA"}

package/dist/{multi-site.js → site-context.js}

@@ -3,7 +3,7 @@ import { createContext, useContext } from "react";
 import { jsx } from "react/jsx-runtime";
 import { createContext as createContext$1, createCookie } from "react-router";
 
-//#region src/multi-site/site-context.tsx
+//#region src/site-context/site-context.tsx
 const SiteContext = createContext(void 0);
 /**
 * Provides the current site to the component tree.
@@ -27,7 +27,7 @@ function useSite() {
 }
 
 //#endregion
-//#region src/multi-site/build-url.ts
+//#region src/site-context/build-url.ts
 /**
 * Parses search config string into key-value pairs, preserving ':param' placeholders.
 * '?lng=:localeId&site=:siteId' → { lng: ':localeId', site: ':siteId' }
@@ -75,6 +75,28 @@ function resolvePrefix(prefix, params) {
 	return resolved;
 }
 /**
+* Strips the URL prefix segments from a pathname based on a prefix pattern.
+* Since all routes are configured with the prefix baked in, segment counting is sufficient.
+*
+* @param pathname - Full pathname (e.g. '/global/en-GB/checkout')
+* @param prefixPattern - URL prefix pattern from config (e.g. '/:siteId/:localeId')
+* @returns Pathname with prefix stripped (e.g. '/checkout'), or original if
+*          the pathname has fewer segments than the prefix
+*
+* @example
+* stripPathPrefix('/global/en-GB/checkout', '/:siteId/:localeId') // → '/checkout'
+* stripPathPrefix('/checkout', '/:siteId/:localeId')              // → '/checkout' (fewer segments → unchanged)
+* stripPathPrefix('/checkout', '')                                 // → '/checkout' (no prefix configured)
+* stripPathPrefix('/', '/:siteId/:localeId')                      // → '/'
+*/
+function stripPathPrefix(pathname, prefixPattern) {
+	if (!prefixPattern) return pathname;
+	const prefixSegmentCount = prefixPattern.split("/").filter(Boolean).length;
+	const pathSegments = pathname.split("/").filter(Boolean);
+	if (pathSegments.length <= prefixSegmentCount) return pathSegments.length === prefixSegmentCount ? "/" : pathname;
+	return `/${pathSegments.slice(prefixSegmentCount).join("/")}`;
+}
+/**
 * Sanitize a resolved prefix from a pathname if present.
 * sanitizePrefix('/global/en-GB/product/123', '/global/en-GB') → '/product/123'
 * sanitizePrefix('/product/123', '/global/en-GB') → '/product/123'   (no-op)
@@ -86,9 +108,9 @@ function sanitizePrefix(pathname, pathPrefix) {
 	return pathname;
 }
 /**
-* Builds a fully-qualified URL with multi-site prefix and search params.
+* Builds a fully-qualified URL with site context prefix and search params.
 *
-* Only keys defined in urlConfig.search are set by multi-site. Any other query params
+* Only keys defined in urlConfig.search are set by site context. Any other query params
 * already present on the `to` URL (including duplicate keys) are preserved as-is.
 * e.g. to='/api/search?refine=color:blue&refine=size:M', search='?lng=:localeId'
 *   → '/api/search?refine=color:blue&refine=size:M&lng=en-GB'
@@ -116,7 +138,7 @@ function buildUrl({ to, urlConfig, params }) {
 }
 
 //#endregion
-//#region src/multi-site/utils.ts
+//#region src/site-context/utils.ts
 /**
 * Extract a string value from the URL path segment at the given index.
 */
@@ -137,7 +159,7 @@ async function readCookieFromRequest(request, cookie) {
 }
 
 //#endregion
-//#region src/multi-site/site-detection.ts
+//#region src/site-context/site-detection.ts
 /**
 * Detect site reference from cookie.
 */
@@ -161,8 +183,9 @@ function getSiteFromIdOrAlias(siteIdentifier, sites) {
 async function resolveSite(request, settings) {
 	const { sites, defaultSiteId, siteDetectionConfig, siteCookie } = settings;
 	const requestUrl = new URL(request.url);
+	const basePathOffset = process.env.MRT_ENV_BASE_PATH ? process.env.MRT_ENV_BASE_PATH.split("/").filter(Boolean).length : 0;
 	const resolvers = {
-		path: () => Promise.resolve(lookupFromPath(requestUrl.pathname, siteDetectionConfig.lookupFromPathIndex)),
+		path: () => Promise.resolve(lookupFromPath(requestUrl.pathname, siteDetectionConfig.lookupFromPathIndex + basePathOffset)),
 		querystring: () => Promise.resolve(requestUrl.searchParams.get(siteDetectionConfig.lookupQuerystring)),
 		header: () => Promise.resolve(request.headers.get(siteDetectionConfig.lookupHeader)),
 		cookie: async () => readSiteFromCookie(request, siteCookie)
@@ -177,7 +200,7 @@ async function resolveSite(request, settings) {
 }
 
 //#endregion
-//#region src/multi-site/configs.ts
+//#region src/site-context/configs.ts
 /**
 * Default site detection configuration
 */
@@ -212,9 +235,9 @@ const DEFAULT_LOCALE_DETECTION = {
 };
 
 //#endregion
-//#region src/multi-site/cookies.ts
+//#region src/site-context/cookies.ts
 /**
-* Cookie options for multi-site cookies
+* Cookie options for site context cookies
 */
 const COOKIE_OPTIONS = {
 	path: "/",
@@ -226,20 +249,20 @@ const COOKIE_OPTIONS = {
 * Creates a cookie instance with the given name.
 *
 * @param name - Cookie name
-* @returns Cookie instance configured with multi-site options
+* @returns Cookie instance configured with site context options
 */
-function createMultiSiteCookie(name) {
+function createSiteContextCookie(name) {
 	return createCookie(name, COOKIE_OPTIONS);
 }
 /**
-* WeakMap to pass resolved locale from multi-site middleware to i18next's findLocale.
+* WeakMap to pass resolved locale from site context middleware to i18next's findLocale.
 * WeakMap allows garbage collection when requests are done.
 * This is necessary because findLocale() only receives the Request object, not the router context.
 */
 const requestToLocaleMap = /* @__PURE__ */ new WeakMap();
 
 //#endregion
-//#region src/multi-site/locale-detection.ts
+//#region src/site-context/locale-detection.ts
 /**
 * Read locale from cookie.
 */
@@ -270,8 +293,9 @@ async function resolveLocale(request, settings, site) {
 	const { supportedLocales } = site;
 	let locale = null;
 	const requestUrl = new URL(request.url);
+	const basePathOffset = process.env.MRT_ENV_BASE_PATH ? process.env.MRT_ENV_BASE_PATH.split("/").filter(Boolean).length : 0;
 	const resolvers = {
-		path: () => Promise.resolve(lookupFromPath(requestUrl.pathname, localeDetectionConfig.lookupFromPathIndex)),
+		path: () => Promise.resolve(lookupFromPath(requestUrl.pathname, localeDetectionConfig.lookupFromPathIndex + basePathOffset)),
 		querystring: () => Promise.resolve(requestUrl.searchParams.get(localeDetectionConfig.lookupQuerystring)),
 		header: () => Promise.resolve(request.headers.get(localeDetectionConfig.lookupHeader)),
 		cookie: async () => readLocaleFromCookie(request, localeCookie)
@@ -286,10 +310,10 @@ async function resolveLocale(request, settings, site) {
 }
 
 //#endregion
-//#region src/multi-site/middleware.ts
-const multiSiteContext = createContext$1(null);
+//#region src/site-context/middleware.ts
+const siteContext = createContext$1(null);
 /**
-* Helper function to get multi-site cookies from router context.
+* Helper function to get site context cookies from router context.
 * Useful in server actions and loaders that need to read/set cookies.
 *
 * @param context - Router context provider
@@ -298,7 +322,7 @@ const multiSiteContext = createContext$1(null);
 * @example
 * ```typescript
 * export const action: ActionFunction = async ({ request, context }) => {
-*     const cookies = getMultiSiteCookies(context);
+*     const cookies = getSiteContextCookies(context);
 *     if (cookies) {
 *         const cookieHeader = await cookies.localeCookie.serialize(locale);
 *         // ... use cookieHeader
@@ -306,50 +330,52 @@ const multiSiteContext = createContext$1(null);
 * };
 * ```
 */
-function getMultiSiteCookies(context) {
-	const multiSite = context.get(multiSiteContext);
-	if (!multiSite) return null;
+function getSiteContextCookies(context) {
+	const siteCtx = context.get(siteContext);
+	if (!siteCtx) return null;
 	return {
-		siteCookie: multiSite.siteCookie,
-		localeCookie: multiSite.localeCookie
+		siteCookie: siteCtx.siteCookie,
+		localeCookie: siteCtx.localeCookie
 	};
 }
 /**
 * Helper function to determine if cookies should be set based on:
 * 1. Whether caching is enabled for each cookie type
-* 2. Whether cookies already exist in the incoming request
+* 2. Whether the resolved value differs from the existing cookie
 * 3. Whether cookies were already set by actions/loaders in the response
 *
 * @param request - Incoming request
 * @param response - Response from next()
-* @param settings - Multi-site settings with cookie instances and detection config
+* @param settings - Site context settings with cookie instances and detection config
+* @param site - Resolved site for this request
+* @param locale - Resolved locale for this request
 * @returns Object with shouldSetSiteCookie and shouldSetLocaleCookie booleans
 */
-async function shouldSetCookies(request, response, settings) {
+async function shouldSetCookies(request, response, settings, site, locale) {
 	const cacheSite = settings.siteDetectionConfig.caches?.includes("cookie");
 	const cacheLocale = settings.localeDetectionConfig.caches?.includes("cookie");
 	if (!cacheSite && !cacheLocale) return {
 		shouldSetSiteCookie: false,
 		shouldSetLocaleCookie: false
 	};
-	const requestCookieHeader = request.headers.get("Cookie");
-	const [existingSiteCookie, existingLocaleCookie] = await Promise.all([settings.siteCookie.parse(requestCookieHeader), settings.localeCookie.parse(requestCookieHeader)]);
 	const responseSetCookies = response.headers.getSetCookie?.() || [];
 	const isSettingSiteCookieInResponse = responseSetCookies.some((cookie) => cookie.startsWith(`${settings.siteCookie.name}=`));
 	const isSettingLocaleCookieInResponse = responseSetCookies.some((cookie) => cookie.startsWith(`${settings.localeCookie.name}=`));
+	const requestCookieHeader = request.headers.get("Cookie");
+	const [existingSiteCookie, existingLocaleCookie] = await Promise.all([settings.siteCookie.parse(requestCookieHeader), settings.localeCookie.parse(requestCookieHeader)]);
 	return {
-		shouldSetSiteCookie: cacheSite && !existingSiteCookie && !isSettingSiteCookieInResponse,
-		shouldSetLocaleCookie: cacheLocale && !existingLocaleCookie && !isSettingLocaleCookieInResponse
+		shouldSetSiteCookie: cacheSite && !isSettingSiteCookieInResponse && existingSiteCookie !== site.id,
+		shouldSetLocaleCookie: cacheLocale && !isSettingLocaleCookieInResponse && existingLocaleCookie !== locale.id
 	};
 }
 /**
-* Creates a multi-site middleware that resolves the current site from
+* Creates a site context middleware that resolves the current site from
 * the request (path, cookie, header, query, or default) and stores the
 * result in the router context.
 *
 * Does not import or read from app config context; the consumer supplies config.
 */
-function createMultiSiteMiddleware(config) {
+function createSiteContextMiddleware(config) {
 	const siteDetectionConfig = {
 		...DEFAULT_SITE_DETECTION,
 		...config.siteDetectionConfig
@@ -358,8 +384,8 @@ function createMultiSiteMiddleware(config) {
 		...DEFAULT_LOCALE_DETECTION,
 		...config.localeDetectionConfig
 	};
-	const siteCookie = createMultiSiteCookie(siteDetectionConfig.lookupCookie);
-	const localeCookie = createMultiSiteCookie(localeDetectionConfig.lookupCookie);
+	const siteCookie = createSiteContextCookie(siteDetectionConfig.lookupCookie);
+	const localeCookie = createSiteContextCookie(localeDetectionConfig.lookupCookie);
 	const settings = {
 		...config,
 		siteDetectionConfig,
@@ -367,10 +393,10 @@ function createMultiSiteMiddleware(config) {
 		siteCookie,
 		localeCookie
 	};
-	const multiSiteMiddleware = async ({ request, context }, next) => {
+	const siteContextMiddleware = async ({ request, context }, next) => {
 		const site = await resolveSite(request, settings);
 		const locale = await resolveLocale(request, settings, site);
-		context.set(multiSiteContext, {
+		context.set(siteContext, {
 			site,
 			locale,
 			siteCookie: settings.siteCookie,
@@ -378,16 +404,16 @@ function createMultiSiteMiddleware(config) {
 		});
 		requestToLocaleMap.set(request, locale.id);
 		const response = await next();
-		const { shouldSetSiteCookie, shouldSetLocaleCookie } = await shouldSetCookies(request, response, settings);
+		const { shouldSetSiteCookie, shouldSetLocaleCookie } = await shouldSetCookies(request, response, settings, site, locale);
 		if (!shouldSetSiteCookie && !shouldSetLocaleCookie) return response;
 		const [siteSetCookie, localeSetCookie] = await Promise.all([shouldSetSiteCookie ? settings.siteCookie.serialize(site.id, { path: "/" }) : Promise.resolve(null), shouldSetLocaleCookie ? settings.localeCookie.serialize(locale.id, { path: "/" }) : Promise.resolve(null)]);
 		if (siteSetCookie) response.headers.append("Set-Cookie", siteSetCookie);
 		if (localeSetCookie) response.headers.append("Set-Cookie", localeSetCookie);
 		return response;
 	};
-	return multiSiteMiddleware;
+	return siteContextMiddleware;
 }
 
 //#endregion
-export { SiteProvider, applyUrlConfig, buildUrl, createMultiSiteMiddleware, getMultiSiteCookies, multiSiteContext, requestToLocaleMap, useSite };
-//# sourceMappingURL=multi-site.js.map
+export { SiteProvider, applyUrlConfig, buildUrl, createSiteContextMiddleware, getSiteContextCookies, requestToLocaleMap, resolvePrefix, sanitizePrefix, siteContext, stripPathPrefix, useSite };
+//# sourceMappingURL=site-context.js.map