@open-mercato/shared 0.8.1-develop.7275.1.f772b944d4 → 0.8.1-develop.7295.1.d0e0e33014

package/src/lib/encryption/__tests__/indexDoc.test.ts

@@ -39,6 +39,45 @@ describe('encryption/indexDoc', () => {
     expect(decryptCustomFieldValueMock).toHaveBeenCalled()
   })
 
+  test('decryptIndexDocCustomFields passes each key its resolved kind (#5968)', async () => {
+    const doc = { id: '1', 'cf:note': 'enc', 'cf:count': 'enc', cf_order_ref: 'enc' }
+    const kinds = { note: 'text', count: 'integer', 'order-ref': 'text', order_ref: 'text' }
+
+    await decryptIndexDocCustomFields(doc, { tenantId: 't1', organizationId: 'org1' }, {} as any, undefined, kinds)
+
+    expect(decryptCustomFieldValueMock).toHaveBeenCalledTimes(3)
+    const kindsPassed = decryptCustomFieldValueMock.mock.calls.map((call) => call[4]?.kind).sort()
+    expect(kindsPassed).toEqual(['integer', 'text', 'text'])
+  })
+
+  test('decryptIndexDocCustomFields passes a null kind when no map is supplied (#5968)', async () => {
+    const doc = { id: '1', 'cf:note': 'enc' }
+
+    await decryptIndexDocCustomFields(doc, { tenantId: 't1', organizationId: 'org1' }, {} as any)
+
+    expect(decryptCustomFieldValueMock).toHaveBeenCalledWith('enc', 't1', {}, undefined, { kind: null })
+  })
+
+  test('decryptIndexDocForSearch forwards the kind map to the cf decryption (#5968)', async () => {
+    const service = {
+      isEnabled: () => true,
+      decryptEntityPayload: jest.fn(async () => ({})),
+    }
+
+    await decryptIndexDocForSearch(
+      'example:todo',
+      { id: '1', 'cf:note': 'enc' },
+      { tenantId: 't1', organizationId: 'org1' },
+      service as any,
+      undefined,
+      { note: 'multiline' },
+    )
+
+    expect(decryptCustomFieldValueMock).toHaveBeenCalledWith(
+      'enc', 't1', service, undefined, { kind: 'multiline' },
+    )
+  })
+
   test('decryptIndexDocForSearch merges decrypted entity payload and decrypts cf keys', async () => {
     decryptCustomFieldValueMock.mockImplementation(async (value: unknown) => (value === 'enc' ? 'dec' : value))
 

package/src/lib/encryption/indexDoc.ts

@@ -1,4 +1,5 @@
 import { decryptCustomFieldValue } from './customFieldValues'
+import { resolveCustomFieldKind, type CustomFieldKindMap } from '../custom-fields/kinds'
 import type { TenantDataEncryptionService } from './tenantDataEncryptionService'
 
 export type IndexDocScope = {
@@ -10,12 +11,15 @@ async function decryptValue(
   value: unknown,
   scope: IndexDocScope,
   service: TenantDataEncryptionService | null,
-  cache?: Map<string | null, string | null>,
+  cache: Map<string | null, string | null> | undefined,
+  kind: string | null,
 ): Promise<unknown> {
   if (Array.isArray(value)) {
-    return Promise.all(value.map((entry) => decryptCustomFieldValue(entry, scope.tenantId, service, cache)))
+    return Promise.all(
+      value.map((entry) => decryptCustomFieldValue(entry, scope.tenantId, service, cache, { kind })),
+    )
   }
-  return decryptCustomFieldValue(value, scope.tenantId, service, cache)
+  return decryptCustomFieldValue(value, scope.tenantId, service, cache, { kind })
 }
 
 export async function decryptIndexDocCustomFields(
@@ -23,6 +27,7 @@ export async function decryptIndexDocCustomFields(
   scope: IndexDocScope,
   service: TenantDataEncryptionService | null,
   cache?: Map<string | null, string | null>,
+  kinds?: CustomFieldKindMap | null,
 ): Promise<Record<string, unknown>> {
   // HybridQueryEngine aliases cf keys as `cf_<key>` (sanitized), while index docs use `cf:<key>`.
   // Support both shapes to keep decryption consistent across query paths.
@@ -33,7 +38,10 @@ export async function decryptIndexDocCustomFields(
   await Promise.all(
     keys.map(async (key) => {
       try {
-        working[key] = await decryptValue(working[key], scope, service, cache)
+        // Without the field's kind, `decryptCustomFieldValue` falls back to `JSON.parse` and
+        // retypes string-typed values whose plaintext looks like JSON — `"123"` becomes 123
+        // and `"true"` becomes true (issue #5968). An unresolved kind keeps the legacy path.
+        working[key] = await decryptValue(working[key], scope, service, cache, resolveCustomFieldKind(kinds, key))
       } catch {
         // ignore; keep original value
       }
@@ -48,12 +56,13 @@ export async function decryptIndexDocForSearch(
   scope: IndexDocScope,
   service: TenantDataEncryptionService | null,
   cache?: Map<string | null, string | null>,
+  kinds?: CustomFieldKindMap | null,
 ): Promise<Record<string, unknown>> {
   if (!service || typeof service.decryptEntityPayload !== 'function') {
-    return decryptIndexDocCustomFields(doc, scope, service, cache)
+    return decryptIndexDocCustomFields(doc, scope, service, cache, kinds)
   }
   if (service.isEnabled?.() === false) {
-    return decryptIndexDocCustomFields(doc, scope, service, cache)
+    return decryptIndexDocCustomFields(doc, scope, service, cache, kinds)
   }
 
   let working: Record<string, unknown> = doc
@@ -72,7 +81,7 @@ export async function decryptIndexDocForSearch(
     await decryptEntity('customers:customer_entity')
   }
 
-  return decryptIndexDocCustomFields(working, scope, service, cache)
+  return decryptIndexDocCustomFields(working, scope, service, cache, kinds)
 }
 
 export async function encryptIndexDocForStorage(

package/src/lib/location/__tests__/countries.test.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import {
   COUNTRY_PRIORITY,
   ISO_COUNTRIES,
@@ -6,7 +8,30 @@ import {
   resolveCountryName,
 } from '../countries'
 
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..', '..')
+const DIST_COUNTRIES = join(PACKAGE_ROOT, 'dist/lib/location/countries.js')
+const DIST_GENERATED = join(PACKAGE_ROOT, 'dist/lib/location/countries.generated.js')
+
 describe('ISO_COUNTRIES', () => {
+  it('does not import language-subtag-registry at runtime (Node ESM / production)', () => {
+    const source = readFileSync(join(__dirname, '../countries.ts'), 'utf8')
+    expect(source).not.toMatch(/language-subtag-registry/)
+    const generated = readFileSync(join(__dirname, '../countries.generated.ts'), 'utf8')
+    expect(generated).toMatch(/AUTO-GENERATED/)
+    expect(generated).toMatch(/code: "PL"/)
+    expect(generated).toMatch(/code: "DE"/)
+
+    expect(existsSync(DIST_COUNTRIES)).toBe(true)
+    expect(existsSync(DIST_GENERATED)).toBe(true)
+    const distCountries = readFileSync(DIST_COUNTRIES, 'utf8')
+    const distGenerated = readFileSync(DIST_GENERATED, 'utf8')
+    expect(distCountries).not.toMatch(/language-subtag-registry/)
+    expect(distGenerated).not.toMatch(/language-subtag-registry/)
+    expect(distCountries).toMatch(/from "\.\/countries\.generated\.js"/)
+    expect(distGenerated).toMatch(/code: "PL"/)
+    expect(distGenerated).toMatch(/code: "DE"/)
+  })
+
   it('includes Kosovo, which the language-subtag registry does not list', () => {
     const kosovo = ISO_COUNTRIES.filter((entry) => entry.code === 'XK')
     expect(kosovo).toEqual([{ code: 'XK', name: 'Kosovo' }])

package/src/lib/location/countries.generated.ts

@@ -0,0 +1,264 @@
+// AUTO-GENERATED by scripts/generate-countries.mjs — do not edit by hand.
+// Regenerate via `node packages/shared/scripts/generate-countries.mjs` or the shared package build.
+
+export const REGISTRY_COUNTRIES: Array<{ code: string; name: string }> = [
+  { code: "AC", name: "Ascension Island" },
+  { code: "AD", name: "Andorra" },
+  { code: "AE", name: "United Arab Emirates" },
+  { code: "AF", name: "Afghanistan" },
+  { code: "AG", name: "Antigua and Barbuda" },
+  { code: "AI", name: "Anguilla" },
+  { code: "AL", name: "Albania" },
+  { code: "AM", name: "Armenia" },
+  { code: "AO", name: "Angola" },
+  { code: "AQ", name: "Antarctica" },
+  { code: "AR", name: "Argentina" },
+  { code: "AS", name: "American Samoa" },
+  { code: "AT", name: "Austria" },
+  { code: "AU", name: "Australia" },
+  { code: "AW", name: "Aruba" },
+  { code: "AX", name: "Åland Islands" },
+  { code: "AZ", name: "Azerbaijan" },
+  { code: "BA", name: "Bosnia and Herzegovina" },
+  { code: "BB", name: "Barbados" },
+  { code: "BD", name: "Bangladesh" },
+  { code: "BE", name: "Belgium" },
+  { code: "BF", name: "Burkina Faso" },
+  { code: "BG", name: "Bulgaria" },
+  { code: "BH", name: "Bahrain" },
+  { code: "BI", name: "Burundi" },
+  { code: "BJ", name: "Benin" },
+  { code: "BL", name: "Saint Barthélemy" },
+  { code: "BM", name: "Bermuda" },
+  { code: "BN", name: "Brunei Darussalam" },
+  { code: "BO", name: "Bolivia" },
+  { code: "BQ", name: "Bonaire, Sint Eustatius and Saba" },
+  { code: "BR", name: "Brazil" },
+  { code: "BS", name: "Bahamas" },
+  { code: "BT", name: "Bhutan" },
+  { code: "BV", name: "Bouvet Island" },
+  { code: "BW", name: "Botswana" },
+  { code: "BY", name: "Belarus" },
+  { code: "BZ", name: "Belize" },
+  { code: "CA", name: "Canada" },
+  { code: "CC", name: "Cocos (Keeling) Islands" },
+  { code: "CD", name: "The Democratic Republic of the Congo" },
+  { code: "CF", name: "Central African Republic" },
+  { code: "CG", name: "Congo" },
+  { code: "CH", name: "Switzerland" },
+  { code: "CI", name: "Côte d'Ivoire" },
+  { code: "CK", name: "Cook Islands" },
+  { code: "CL", name: "Chile" },
+  { code: "CM", name: "Cameroon" },
+  { code: "CN", name: "China" },
+  { code: "CO", name: "Colombia" },
+  { code: "CP", name: "Clipperton Island" },
+  { code: "CQ", name: "Sark" },
+  { code: "CR", name: "Costa Rica" },
+  { code: "CU", name: "Cuba" },
+  { code: "CV", name: "Cabo Verde, Cape Verde" },
+  { code: "CW", name: "Curaçao" },
+  { code: "CX", name: "Christmas Island" },
+  { code: "CY", name: "Cyprus" },
+  { code: "CZ", name: "Czechia, Czech Republic" },
+  { code: "DE", name: "Germany" },
+  { code: "DG", name: "Diego Garcia" },
+  { code: "DJ", name: "Djibouti" },
+  { code: "DK", name: "Denmark" },
+  { code: "DM", name: "Dominica" },
+  { code: "DO", name: "Dominican Republic" },
+  { code: "DZ", name: "Algeria" },
+  { code: "EA", name: "Ceuta, Melilla" },
+  { code: "EC", name: "Ecuador" },
+  { code: "EE", name: "Estonia" },
+  { code: "EG", name: "Egypt" },
+  { code: "EH", name: "Western Sahara" },
+  { code: "ER", name: "Eritrea" },
+  { code: "ES", name: "Spain" },
+  { code: "ET", name: "Ethiopia" },
+  { code: "EU", name: "European Union" },
+  { code: "EZ", name: "Eurozone" },
+  { code: "FI", name: "Finland" },
+  { code: "FJ", name: "Fiji" },
+  { code: "FK", name: "Falkland Islands (Malvinas)" },
+  { code: "FM", name: "Federated States of Micronesia" },
+  { code: "FO", name: "Faroe Islands" },
+  { code: "FR", name: "France" },
+  { code: "GA", name: "Gabon" },
+  { code: "GB", name: "United Kingdom" },
+  { code: "GD", name: "Grenada" },
+  { code: "GE", name: "Georgia" },
+  { code: "GF", name: "French Guiana" },
+  { code: "GG", name: "Guernsey" },
+  { code: "GH", name: "Ghana" },
+  { code: "GI", name: "Gibraltar" },
+  { code: "GL", name: "Greenland" },
+  { code: "GM", name: "Gambia" },
+  { code: "GN", name: "Guinea" },
+  { code: "GP", name: "Guadeloupe" },
+  { code: "GQ", name: "Equatorial Guinea" },
+  { code: "GR", name: "Greece" },
+  { code: "GS", name: "South Georgia and the South Sandwich Islands" },
+  { code: "GT", name: "Guatemala" },
+  { code: "GU", name: "Guam" },
+  { code: "GW", name: "Guinea-Bissau" },
+  { code: "GY", name: "Guyana" },
+  { code: "HK", name: "Hong Kong" },
+  { code: "HM", name: "Heard Island and McDonald Islands" },
+  { code: "HN", name: "Honduras" },
+  { code: "HR", name: "Croatia" },
+  { code: "HT", name: "Haiti" },
+  { code: "HU", name: "Hungary" },
+  { code: "IC", name: "Canary Islands" },
+  { code: "ID", name: "Indonesia" },
+  { code: "IE", name: "Ireland" },
+  { code: "IL", name: "Israel" },
+  { code: "IM", name: "Isle of Man" },
+  { code: "IN", name: "India" },
+  { code: "IO", name: "British Indian Ocean Territory" },
+  { code: "IQ", name: "Iraq" },
+  { code: "IR", name: "Islamic Republic of Iran" },
+  { code: "IS", name: "Iceland" },
+  { code: "IT", name: "Italy" },
+  { code: "JE", name: "Jersey" },
+  { code: "JM", name: "Jamaica" },
+  { code: "JO", name: "Jordan" },
+  { code: "JP", name: "Japan" },
+  { code: "KE", name: "Kenya" },
+  { code: "KG", name: "Kyrgyzstan" },
+  { code: "KH", name: "Cambodia" },
+  { code: "KI", name: "Kiribati" },
+  { code: "KM", name: "Comoros" },
+  { code: "KN", name: "Saint Kitts and Nevis" },
+  { code: "KP", name: "Democratic People's Republic of Korea" },
+  { code: "KR", name: "Republic of Korea" },
+  { code: "KW", name: "Kuwait" },
+  { code: "KY", name: "Cayman Islands" },
+  { code: "KZ", name: "Kazakhstan" },
+  { code: "LA", name: "Lao People's Democratic Republic" },
+  { code: "LB", name: "Lebanon" },
+  { code: "LC", name: "Saint Lucia" },
+  { code: "LI", name: "Liechtenstein" },
+  { code: "LK", name: "Sri Lanka" },
+  { code: "LR", name: "Liberia" },
+  { code: "LS", name: "Lesotho" },
+  { code: "LT", name: "Lithuania" },
+  { code: "LU", name: "Luxembourg" },
+  { code: "LV", name: "Latvia" },
+  { code: "LY", name: "Libya" },
+  { code: "MA", name: "Morocco" },
+  { code: "MC", name: "Monaco" },
+  { code: "MD", name: "Moldova" },
+  { code: "ME", name: "Montenegro" },
+  { code: "MF", name: "Saint Martin (French part)" },
+  { code: "MG", name: "Madagascar" },
+  { code: "MH", name: "Marshall Islands" },
+  { code: "MK", name: "North Macedonia" },
+  { code: "ML", name: "Mali" },
+  { code: "MM", name: "Myanmar" },
+  { code: "MN", name: "Mongolia" },
+  { code: "MO", name: "Macao" },
+  { code: "MP", name: "Northern Mariana Islands" },
+  { code: "MQ", name: "Martinique" },
+  { code: "MR", name: "Mauritania" },
+  { code: "MS", name: "Montserrat" },
+  { code: "MT", name: "Malta" },
+  { code: "MU", name: "Mauritius" },
+  { code: "MV", name: "Maldives" },
+  { code: "MW", name: "Malawi" },
+  { code: "MX", name: "Mexico" },
+  { code: "MY", name: "Malaysia" },
+  { code: "MZ", name: "Mozambique" },
+  { code: "NA", name: "Namibia" },
+  { code: "NC", name: "New Caledonia" },
+  { code: "NE", name: "Niger" },
+  { code: "NF", name: "Norfolk Island" },
+  { code: "NG", name: "Nigeria" },
+  { code: "NI", name: "Nicaragua" },
+  { code: "NL", name: "Netherlands" },
+  { code: "NO", name: "Norway" },
+  { code: "NP", name: "Nepal" },
+  { code: "NR", name: "Nauru" },
+  { code: "NU", name: "Niue" },
+  { code: "NZ", name: "New Zealand" },
+  { code: "OM", name: "Oman" },
+  { code: "PA", name: "Panama" },
+  { code: "PE", name: "Peru" },
+  { code: "PF", name: "French Polynesia" },
+  { code: "PG", name: "Papua New Guinea" },
+  { code: "PH", name: "Philippines" },
+  { code: "PK", name: "Pakistan" },
+  { code: "PL", name: "Poland" },
+  { code: "PM", name: "Saint Pierre and Miquelon" },
+  { code: "PN", name: "Pitcairn" },
+  { code: "PR", name: "Puerto Rico" },
+  { code: "PS", name: "State of Palestine" },
+  { code: "PT", name: "Portugal" },
+  { code: "PW", name: "Palau" },
+  { code: "PY", name: "Paraguay" },
+  { code: "QA", name: "Qatar" },
+  { code: "RE", name: "Réunion" },
+  { code: "RO", name: "Romania" },
+  { code: "RS", name: "Serbia" },
+  { code: "RU", name: "Russian Federation" },
+  { code: "RW", name: "Rwanda" },
+  { code: "SA", name: "Saudi Arabia" },
+  { code: "SB", name: "Solomon Islands" },
+  { code: "SC", name: "Seychelles" },
+  { code: "SD", name: "Sudan" },
+  { code: "SE", name: "Sweden" },
+  { code: "SG", name: "Singapore" },
+  { code: "SH", name: "Saint Helena, Ascension and Tristan da Cunha" },
+  { code: "SI", name: "Slovenia" },
+  { code: "SJ", name: "Svalbard and Jan Mayen" },
+  { code: "SK", name: "Slovakia" },
+  { code: "SL", name: "Sierra Leone" },
+  { code: "SM", name: "San Marino" },
+  { code: "SN", name: "Senegal" },
+  { code: "SO", name: "Somalia" },
+  { code: "SR", name: "Suriname" },
+  { code: "SS", name: "South Sudan" },
+  { code: "ST", name: "Sao Tome and Principe" },
+  { code: "SV", name: "El Salvador" },
+  { code: "SX", name: "Sint Maarten (Dutch part)" },
+  { code: "SY", name: "Syrian Arab Republic" },
+  { code: "SZ", name: "Eswatini, eSwatini, Swaziland" },
+  { code: "TA", name: "Tristan da Cunha" },
+  { code: "TC", name: "Turks and Caicos Islands" },
+  { code: "TD", name: "Chad" },
+  { code: "TF", name: "French Southern Territories" },
+  { code: "TG", name: "Togo" },
+  { code: "TH", name: "Thailand" },
+  { code: "TJ", name: "Tajikistan" },
+  { code: "TK", name: "Tokelau" },
+  { code: "TL", name: "Timor-Leste" },
+  { code: "TM", name: "Turkmenistan" },
+  { code: "TN", name: "Tunisia" },
+  { code: "TO", name: "Tonga" },
+  { code: "TR", name: "Türkiye, Turkey" },
+  { code: "TT", name: "Trinidad and Tobago" },
+  { code: "TV", name: "Tuvalu" },
+  { code: "TW", name: "Taiwan, Province of China" },
+  { code: "TZ", name: "United Republic of Tanzania" },
+  { code: "UA", name: "Ukraine" },
+  { code: "UG", name: "Uganda" },
+  { code: "UM", name: "United States Minor Outlying Islands" },
+  { code: "UN", name: "United Nations" },
+  { code: "US", name: "United States" },
+  { code: "UY", name: "Uruguay" },
+  { code: "UZ", name: "Uzbekistan" },
+  { code: "VA", name: "Holy See (Vatican City State)" },
+  { code: "VC", name: "Saint Vincent and the Grenadines" },
+  { code: "VE", name: "Venezuela" },
+  { code: "VG", name: "British Virgin Islands" },
+  { code: "VI", name: "U.S. Virgin Islands" },
+  { code: "VN", name: "Viet Nam" },
+  { code: "VU", name: "Vanuatu" },
+  { code: "WF", name: "Wallis and Futuna" },
+  { code: "WS", name: "Samoa" },
+  { code: "YE", name: "Yemen" },
+  { code: "YT", name: "Mayotte" },
+  { code: "ZA", name: "South Africa" },
+  { code: "ZM", name: "Zambia" },
+  { code: "ZW", name: "Zimbabwe" },
+]

package/src/lib/location/countries.ts

@@ -1,32 +1,11 @@
-import registry from 'language-subtag-registry/data/json/registry.json'
-
-type RegistryEntry = {
-  Type: string
-  Subtag?: string
-  Description?: string[]
-  Deprecated?: string
-}
+import { REGISTRY_COUNTRIES } from './countries.generated'
 
 export type IsoCountry = {
   code: string
   name: string
 }
 
-function isIsoAlpha2(entry: RegistryEntry): entry is RegistryEntry & { Subtag: string; Description: string[] } {
-  if (entry.Type !== 'region') return false
-  if (!entry.Subtag || !/^[A-Z]{2}$/.test(entry.Subtag)) return false
-  if (entry.Deprecated) return false
-  if (!entry.Description || !entry.Description.length) return false
-  if (entry.Description[0] === 'Private use') return false
-  return true
-}
-
-const RAW_COUNTRIES: IsoCountry[] = (registry as RegistryEntry[])
-  .filter(isIsoAlpha2)
-  .map((entry) => ({
-    code: entry.Subtag,
-    name: entry.Description.join(', '),
-  }))
+const RAW_COUNTRIES: IsoCountry[] = REGISTRY_COUNTRIES
 
 // Codes in common use that the language-subtag registry does not list as region subtags.
 // XK is user-assigned rather than ISO 3166-1 assigned, so it never appears in the registry.

package/src/lib/navigation/__tests__/pageReload.test.ts

@@ -0,0 +1,58 @@
+/**
+ * These helpers exist so a boundary-crossing portal navigation re-runs the server layout that
+ * computes the portal chrome and the session. Which document API each one uses is the whole
+ * contract: `assign` keeps the current page in session history, `replace` does not, so they are
+ * the document-loading counterparts of `router.push` and `router.replace` respectively. Swapping
+ * one for the other is invisible on screen and only surfaces as a broken Back button, so pin both.
+ *
+ * This runs in the node environment on purpose: jsdom exposes `window.location` as a
+ * non-configurable getter whose `assign`/`replace` are non-writable, so the real navigation calls
+ * cannot be observed there. A synthetic `window` lets the helper bodies run for real.
+ */
+
+const assign = jest.fn()
+const replace = jest.fn()
+
+describe('page reload navigation helpers', () => {
+  let navigateWithPageReload: (path: string) => void
+  let replaceWithPageReload: (path: string) => void
+
+  beforeAll(() => {
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      writable: true,
+      value: { location: { assign, replace } },
+    })
+    // Imported after the synthetic window exists, so the module resolves against it.
+    const helpers = require('../pageReload')
+    navigateWithPageReload = helpers.navigateWithPageReload
+    replaceWithPageReload = helpers.replaceWithPageReload
+  })
+
+  afterAll(() => {
+    delete (globalThis as { window?: unknown }).window
+  })
+
+  beforeEach(() => {
+    assign.mockReset()
+    replace.mockReset()
+  })
+
+  describe('navigateWithPageReload', () => {
+    it('loads the path and keeps the current page in session history', () => {
+      navigateWithPageReload('/acme/portal/dashboard')
+
+      expect(assign).toHaveBeenCalledWith('/acme/portal/dashboard')
+      expect(replace).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('replaceWithPageReload', () => {
+    it('loads the path without leaving the redirecting page in session history', () => {
+      replaceWithPageReload('/acme/portal/login')
+
+      expect(replace).toHaveBeenCalledWith('/acme/portal/login')
+      expect(assign).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/lib/navigation/pageReload.ts

@@ -0,0 +1,43 @@
+/**
+ * Boundary-crossing navigation helpers: they reload the document instead of handing the route to
+ * the client router.
+ *
+ * The portal's `(frontend)` layout — the server component that decides the portal chrome and
+ * resolves the customer session — sits *above* the `[...slug]` segment so portal navigation does
+ * not remount the client subtree. A client-side `router.push`/`router.replace` therefore never
+ * re-runs that layout, and any navigation that crosses the public/authenticated boundary would
+ * keep rendering chrome computed for the page it came from: authenticated chrome over the login
+ * page after a logout, or logged-out chrome over the dashboard after a login.
+ *
+ * Use these helpers for every boundary-crossing navigation (login, logout, signup completion,
+ * invite acceptance, auth guards redirecting to login) so the layout re-runs and recomputes both
+ * the chrome and the session. Same-side navigation should keep using the client router.
+ *
+ * Pick the one that matches the client-router call it stands in for, so session history behaves
+ * the same way: `navigateWithPageReload` for `router.push`, `replaceWithPageReload` for
+ * `router.replace`.
+ */
+
+/** Full page load that adds a session-history entry — the document-loading counterpart of `router.push`. */
+export function navigateWithPageReload(path: string): void {
+  window.location.assign(path)
+}
+
+/**
+ * Full page load that replaces the current session-history entry — the document-loading
+ * counterpart of `router.replace`.
+ *
+ * Use this where the client-router call being replaced was a `router.replace`: an auth guard
+ * sending an unauthenticated visitor to the login page, or the portal landing page forwarding a
+ * signed-in customer to the dashboard.
+ *
+ * Note that for those call sites specifically, `navigateWithPageReload` was measured to behave
+ * identically: they redirect from an effect during page load, and a browser treats a navigation
+ * started then as a client redirect, replacing the entry rather than pushing it whichever method
+ * is used. This helper exists so the call site states which semantics it means instead of relying
+ * on that heuristic — and so a redirect that later moves behind a user gesture, where the
+ * distinction does bite, keeps the behaviour it was written with.
+ */
+export function replaceWithPageReload(path: string): void {
+  window.location.replace(path)
+}