fix(locale): gate browser detection on window and tolerate a missing languages list

Node >= 21 exposes a global `navigator` reporting the machine's own language,
so gating detection on `navigator` let a non-browser boot of the client tree
resolve to `en` instead of the documented fallback; `window` is the browser
test. `navigator.languages` is spec-required but absent on some embedders and
older WebViews, where spreading it would throw at boot, so the walk tolerates
its absence and `navigator.language` covers that host.

The per-spec pin boilerplate collapses into one suite-level
`usePinnedBrowserLanguages('zh-CN')`, which owns the rationale in
dsh-client-test-runtime, and the English-browser e2e scenario now clears the
console warnings channel too — its page has no closing inventory spec.

packages/client/locale/src/client/index.ts

@@ -315,13 +315,20 @@ function restorePreference(): LocaleId | undefined {
 /**
  * The first shipped locale the browser asks for, matched on the primary
  * subtag so every regional variant lands on its language (`zh-Hans-CN` -> zh,
- * `en-GB` -> en). `navigator.language` trails the ordered `languages` list
- * because a browser may expose only the former.
+ * `en-GB` -> en). `window` is the browser test, not `navigator`: Node exposes
+ * a global `navigator` reporting the machine's own language, which would
+ * otherwise decide the locale for non-browser runs (node e2e booting the
+ * client tree). `navigator.language` trails the ordered `languages` list and
+ * covers its absence on hosts that expose only the single tag.
  */
 function detectBrowserLocale(): LocaleId | undefined {
-  // Non-browser runs (node e2e booting the client tree) have no navigator.
-  if (typeof navigator === 'undefined') return undefined
-  for (const tag of [...navigator.languages, navigator.language]) {
+  if (typeof window === 'undefined') return undefined
+  /* oxlint-disable-next-line typescript/no-unnecessary-condition --
+   * The DOM lib types `languages` as always present; embedders and older
+   * WebViews ship a Navigator without it, and spreading undefined would
+   * throw at boot. Same environment-boundary distrust as the localStorage
+   * guards below. */
+  for (const tag of [...(navigator.languages ?? []), navigator.language]) {
     const primary = tag.toLowerCase().split('-')[0]
     const match = LOCALES.find(locale => locale.id === primary)
     if (match) return match.id

packages/client/locale/tests/locale.spec.ts

@@ -11,7 +11,13 @@ const make = (): { ctx: Context; svc: LocaleService; events: LocaleSnapshot[] }
   return { ctx, svc: new LocaleService(ctx), events }
 }
 
-/** Pin the browser environment a fresh service reads its initial locale from. */
+/**
+ * Pin the browser environment a fresh service reads its initial locale from.
+ * This package's own specs stub the globals directly instead of using
+ * `usePinnedBrowserLanguages` (dsh-client-test-runtime): they need the shapes
+ * that helper deliberately cannot express — a missing `languages` list, a
+ * list decoupled from `language`, and a non-browser run with no `window`.
+ */
 const stubLanguages = (...tags: string[]): void => {
   vi.stubGlobal('navigator', { languages: tags, language: tags[0] ?? '' })
 }
@@ -158,18 +164,24 @@ describe('LocaleService', () => {
     // An unshipped language walks the list to the first one this app ships.
     stubLanguages('fr-FR', 'en-US')
     expect(make().svc.getLocale().active).toBe('en')
-    // Only `language` populated (browsers that expose no ordered list).
+    // Only `language` populated: an empty ordered list, and a host that
+    // exposes no `languages` property at all.
     vi.stubGlobal('navigator', { languages: [], language: 'en-US' })
     expect(make().svc.getLocale().active).toBe('en')
+    vi.stubGlobal('navigator', { language: 'en-US' })
+    expect(make().svc.getLocale().active).toBe('en')
     // No shipped language anywhere in the browser's preferences: zh remains
     // the product default rather than an arbitrary near-match.
     stubLanguages('fr-FR', 'de')
     expect(make().svc.getLocale().active).toBe('zh')
   })
 
-  it('runs without localStorage or navigator (node boots): defaults on read, no-op on write', () => {
+  it('runs outside a browser (node boots): the fallback decides, the machine language does not, writes no-op', () => {
     vi.stubGlobal('localStorage', undefined)
-    vi.stubGlobal('navigator', undefined)
+    vi.stubGlobal('window', undefined)
+    // Node exposes its own global navigator; without a window it must not
+    // reach the resolution at all.
+    stubLanguages('en-US')
     const { svc } = make()
     expect(svc.getLocale().active).toBe('zh')
     svc.setLocale('en')

packages/client/test-runtime/src/index.ts

@@ -38,7 +38,7 @@ export { TestWorkspaces } from './workspaces.ts'
 export { conversationSnapshot, workspaceListState } from './fixtures.ts'
 export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
 export { makeTranslate } from './translate.ts'
-export { pinBrowserLanguages } from './locale-env.ts'
+export { usePinnedBrowserLanguages } from './locale-env.ts'
 
 /** Erased register face for the internal root call (the public declare seam holds the typing). */
 type ErasedRegister = (options: object, component: unknown) => () => void

packages/client/test-runtime/src/locale-env.ts

@@ -5,21 +5,25 @@
  * the product's Chinese copy states the browser it assumes instead of
  * inheriting the machine's.
  */
+import { afterEach, beforeEach } from 'vitest'
 
 /**
- * Override `navigator.languages`/`navigator.language` for the current spec.
+ * Pin `navigator.languages`/`navigator.language` for every test in the
+ * calling file (or describe block), restoring the environment's own values
+ * afterwards. Call at suite level, like the other vitest hooks.
  * @param primary - most preferred BCP 47 tag; also becomes `navigator.language`.
  * @param rest - further tags in preference order.
- * @returns restore function handing the properties back to the environment.
  */
-export function pinBrowserLanguages(primary: string, ...rest: string[]): () => void {
-  Object.defineProperty(navigator, 'languages', { value: [primary, ...rest], configurable: true })
-  Object.defineProperty(navigator, 'language', { value: primary, configurable: true })
-  return () => {
+export function usePinnedBrowserLanguages(primary: string, ...rest: string[]): void {
+  beforeEach(() => {
+    Object.defineProperty(navigator, 'languages', { value: [primary, ...rest], configurable: true })
+    Object.defineProperty(navigator, 'language', { value: primary, configurable: true })
+  })
+  afterEach(() => {
     // Deleting the own properties uncovers the environment's own accessors
     // again (Navigator declares both readonly, hence the erased receiver).
     const own = navigator as unknown as Record<string, unknown>
     delete own.languages
     delete own.language
-  }
+  })
 }

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -14,8 +14,8 @@
 // guards would mask. Rendering-path acceptance lives in
 // chat-toolview-slot.spec.tsx.
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { SlotTestRuntime, pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { describe, expect, it, vi } from 'vitest'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import type { SessionBehaviorOverrides } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
@@ -27,9 +27,7 @@ import type { createChatStore } from '../src/client/stores.ts'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const ROOT = 'root-1' as SessionId
 

packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx

@@ -24,14 +24,12 @@ import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { SlotTestRuntime, pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const SID = 's1' as SessionId
 

packages/client/ui-conversation/tests/chat-apply.spec.tsx

@@ -8,8 +8,8 @@
 // machinery spec (chat-toolview-slot.spec.tsx) and the shell e2e; this spec
 // stops at the assembly surface.
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { SlotTestRuntime, pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { describe, expect, it, vi } from 'vitest'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
@@ -17,9 +17,7 @@ import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const ROOT = 'root-1' as SessionId
 const CHILD = 'child-1' as SessionId

packages/client/ui-models/tests/apply.spec.ts

@@ -1,19 +1,17 @@
 /** Models section registration: declaration-aware deferral, the locale-following label thunk, and HMR recovery. */
 import { Context } from 'cordis'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, refreshIfLoaded } from '@deepseek-ai/dsh-client-ui-models/client'
 import { ModelsSection } from '../src/client/ModelsSection.tsx'
 import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 async function bench() {
   const ctx = new Context()

packages/client/ui-settings-general/tests/apply.spec.ts

@@ -1,19 +1,17 @@
 /** Ownerless-copy registrations: the four seats, the dictionaries, thunked labels, and HMR recovery. */
 import { Context } from 'cordis'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client'
 import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
 import { GeneralSection } from '../src/client/GeneralSection.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 /** The four seats this plugin fills (slot name → expected component). */
 const SEATS = [

packages/client/ui-sidebar/tests/sidebar-snapshot.spec.tsx

@@ -8,17 +8,15 @@
  * holes (sidebar.workspaces / sidebar.settings) have no registrant here, so
  * the snapshots pin the shell chrome itself.
  */
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, waitFor } from '@testing-library/react'
-import { SlotTestRuntime, pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 afterEach(cleanup)
 

packages/client/ui-slash/tests/apply.spec.ts

@@ -6,9 +6,9 @@
  * sessionId, and unregisters on fiber teardown.
  */
 import { Context } from 'cordis'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { createScope, scopeOf, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject, SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
@@ -16,9 +16,7 @@ import type { MenuViewInjected } from '@deepseek-ai/dsh-client-ui-slash/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const sid = (k: string): SessionId => k as SessionId
 

packages/client/ui-theme/tests/apply.spec.ts

@@ -2,10 +2,10 @@
  * locale service, declaration-aware Appearance row registration, snapshot
  * projection into the row store, and HMR collapse recovery. */
 import { Context } from 'cordis'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-ui-theme/client'
 import type { AppearanceRowInjected, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { AppearanceRow } from '../src/client/AppearanceRow.tsx'
@@ -13,9 +13,7 @@ import type { createAppearanceRowStore } from '../src/client/settings-store.ts'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const SLOT = 'settings.general.item'
 

packages/client/ui-workspace/tests/apply.spec.ts

@@ -1,8 +1,8 @@
 import { Context } from 'cordis'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-workspace/client'
 import type { WorkspaceBrowserInjected, WorkspacePickerInjected } from '@deepseek-ai/dsh-client-ui-workspace/client'
 import { WorkspaceBrowser } from '../src/client/WorkspaceBrowser.tsx'
@@ -10,9 +10,7 @@ import { WorkspacePicker } from '../src/client/WorkspacePicker.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 async function bench() {
   const ctx = new Context()

packages/client/ui-workspace/tests/rename-assembly.spec.tsx

@@ -14,15 +14,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import type { ISession, SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { SlotTestRuntime, pinBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-workspace/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
-let restoreLanguages: () => void
-beforeEach(() => { restoreLanguages = pinBrowserLanguages('zh-CN') })
-afterEach(() => { restoreLanguages() })
+usePinnedBrowserLanguages('zh-CN')
 
 const SID = 's1' as SessionId