npm - @chronogrove/ui - Versions diffs - 0.82.0 → 0.82.3 - Mend

@chronogrove/ui 0.82.0 → 0.82.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md +2 -2
package/package.json +3 -3
package/src/animated-page-background/ColorBends.js +7 -4
package/src/color-mode/constants.js +6 -0
package/src/color-mode/cross-domain-color-mode-client-config.js +33 -0
package/src/color-mode/cross-domain-color-mode-client-config.spec.js +45 -0
package/src/color-mode/cross-domain-color-mode-cookie-node.spec.js +28 -0
package/src/color-mode/cross-domain-color-mode-cookie-set-http.spec.js +42 -0
package/src/color-mode/cross-domain-color-mode-cookie-set-https.spec.js +50 -0
package/src/color-mode/cross-domain-color-mode-cookie-set-localhost.spec.js +15 -0
package/src/color-mode/cross-domain-color-mode-cookie.js +91 -0
package/src/color-mode/cross-domain-color-mode-cookie.spec.js +120 -0
package/src/color-mode/head-inline-resolution.spec.js +111 -0
package/src/color-mode/head-inline.js +104 -17
package/src/color-mode/head-inline.spec.js +68 -1
package/src/color-mode/index.js +17 -2
package/src/color-mode/registrable-domain.js +30 -0
package/src/color-mode/registrable-domain.spec.js +28 -0
package/src/color-toggle.js +3 -0
package/src/gatsby/build-theme-ui-color-mode-head-components.js +5 -4
package/src/gatsby/index.spec.js +11 -1
package/src/next/app-shell.js +12 -2
package/src/next/root-layout-head.js +6 -3

package/README.md CHANGED Viewed

@@ -12,7 +12,7 @@ pnpm add @chronogrove/ui
 Use **`pnpm publish`** for releases so `workspace:` dependencies in dependents are rewritten; see [pnpm workspaces — publishing](https://pnpm.io/workspaces#publishing-workspace-packages).
-**Shared dependencies with `gatsby-theme-chronogrove`:** both packages depend on Theme UI, Emotion, and related libraries, with versions driven by the root [pnpm catalog](../../pnpm-workspace.yaml). When you bump those catalog entries, update **`packages/ui`** and **`theme`** in the **same change** so the theme and `@chronogrove/ui` stay aligned and you avoid duplicate or mismatched installs.
+**Shared dependencies with `gatsby-theme-chronogrove`:** both packages depend on Theme UI, Emotion, **`three`** (where WebGL backgrounds or artwork import it), and related libraries, with versions driven by the root [pnpm catalog](../../pnpm-workspace.yaml). When you bump those catalog entries, update **`packages/ui`**, **`theme`**, and any other workspace `package.json` files that reference `catalog:` for the same keys in the **same change** so installs stay aligned and you avoid duplicate or mismatched trees.
 ## Subpath exports
@@ -24,7 +24,7 @@ Prefer deep imports so bundles stay lean:
 | `@chronogrove/ui/theme`                    | Default Theme UI theme object + named exports                                                                                                                                                                                                                                                                                                    |
 | `@chronogrove/ui/provider`                 | `ChronogroveThemeProvider`                                                                                                                                                                                                                                                                                                                       |
 | `@chronogrove/ui/color-mode`               | Storage key, reconcile event, SSR inline builders, `chronogroveHeadTheme` (RSC-safe), `resolveChronogroveSurfaceColors`, `useDocumentColorModeSurface`, browser sync, `reconcileThemeUiColorModeOnNavigation`                                                                                                                                    |
-| `@chronogrove/ui/animated-page-background` | **`ChronogroveAnimatedPageBackground`** — same stack as the Gatsby home: fixed `z-index: 0`, light = solid theme background, dark = **three.js** Color Bends + scroll-linked gradient overlay and parallax (`three` is a dependency of this package).                                                                                            |
+| `@chronogrove/ui/animated-page-background` | **`ChronogroveAnimatedPageBackground`** — same stack as the Gatsby home: fixed `z-index: 0`, light = solid theme background, dark = **three.js** Color Bends + scroll-linked gradient overlay and parallax (`three` is a dependency of this package). Animation timing uses **`THREE.Timer`** (not deprecated `Clock`, three.js r183+).          |
 | `@chronogrove/ui/color-bends`              | **`ColorBends`** — lower-level three.js gradient background used inside `ChronogroveAnimatedPageBackground`. Prefer the full **`animated-page-background`** or **`@chronogrove/ui/next`** shell unless you need the raw component.                                                                                                               |
 | `@chronogrove/ui/next`                     | **Next.js App Router helpers:** `ChronogroveNextRootLayoutHead` (RSC `<head>` injections), `ChronogroveNextEmotionRegistry`, `ChronogroveNextAppShell` (theme + three.js background + surface sync + soft-nav reconcile), `ChronogroveNextThemeUiColorModeRouteSync` (standalone). Requires `next` (peer, optional for the rest of the package). |
 | `@chronogrove/ui/action-card-layout`       | **`actionCardPinnedLayoutSx`** — layout `sx` for `Card variant="actionCard"` (matches GitHub pinned cards).                                                                                                                                                                                                                                      |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.82.0",
+  "version": "0.82.3",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -144,7 +144,7 @@
     }
   },
   "peerDependencies": {
-    "next": "^14.0.0 || ^15.0.0",
+    "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -174,7 +174,7 @@
     "babel-jest": "^30.3.0",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
-    "next": "^15.1.0",
+    "next": "^16.2.3",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },

package/src/animated-page-background/ColorBends.js CHANGED Viewed

@@ -178,7 +178,8 @@ export default function ColorBends({
     container.appendChild(renderer.domElement)
-    const clock = new THREE.Clock()
+    const timer = new THREE.Timer()
+    timer.connect(document)
     const handleResize = () => {
       const w = container.clientWidth || 1
@@ -197,9 +198,10 @@ export default function ColorBends({
       window.addEventListener('resize', handleResize)
     }
-    const loop = () => {
-      const dt = clock.getDelta()
-      const elapsed = clock.elapsedTime
+    const loop = time => {
+      timer.update(time)
+      const dt = timer.getDelta()
+      const elapsed = timer.getElapsed()
       material.uniforms.uTime.value = elapsed
@@ -222,6 +224,7 @@ export default function ColorBends({
     rafRef.current = requestAnimationFrame(loop)
     return () => {
+      timer.dispose()
       if (rafRef.current !== null) cancelAnimationFrame(rafRef.current)
       if (resizeObserverRef.current) resizeObserverRef.current.disconnect()
       else window.removeEventListener('resize', handleResize)

package/src/color-mode/constants.js CHANGED Viewed

@@ -1,6 +1,12 @@
 /** Theme UI localStorage key (aligned with theme-ui/color-mode). */
 export const THEME_UI_COLOR_MODE_STORAGE_KEY = 'theme-ui-color-mode'
+/** Default cookie name when `cookieName` is omitted from cross-domain color mode options. */
+export const CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME = 'chronogrove-theme-ui-color-mode'
+/** ~400 days; browser cookie eviction policies may apply earlier. */
+export const CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_MAX_AGE_SEC = 60 * 60 * 24 * 400
 /** Dispatched on route changes so hosts can reconcile React color-mode context with `localStorage`. */
 export const RECONCILE_COLOR_MODE_EVENT = 'theme-ui-reconcile-color-mode'

package/src/color-mode/cross-domain-color-mode-client-config.js ADDED Viewed

@@ -0,0 +1,33 @@
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME } from './constants.js'
+/**
+ * Browser-only config for {@link setChronogroveCrossDomainColorModeCookie} (must match the
+ * `crossDomainColorMode` passed into head inline scripts at build time). Set via
+ * {@link setChronogroveCrossDomainColorModeClientConfig} from Gatsby `onClientEntry`, Next
+ * `ChronogroveNextAppShell`, or your own bootstrap.
+ */
+let clientConfig = /** @type {{ registrableDomain?: string, cookieName?: string } | null} */ (null)
+export function setChronogroveCrossDomainColorModeClientConfig(next) {
+  if (next == null) {
+    clientConfig = null
+    return
+  }
+  if (typeof next !== 'object') {
+    return
+  }
+  const { registrableDomain, cookieName } = next
+  if (!registrableDomain || typeof registrableDomain !== 'string' || !registrableDomain.trim()) {
+    clientConfig = null
+    return
+  }
+  clientConfig = {
+    registrableDomain: registrableDomain.trim(),
+    cookieName: cookieName ?? CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+  }
+}
+export function getChronogroveCrossDomainColorModeClientConfig() {
+  return clientConfig
+}

package/src/color-mode/cross-domain-color-mode-client-config.spec.js ADDED Viewed

@@ -0,0 +1,45 @@
+/**
+ * @jest-environment jsdom
+ */
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME } from './constants.js'
+import {
+  getChronogroveCrossDomainColorModeClientConfig,
+  setChronogroveCrossDomainColorModeClientConfig
+} from './cross-domain-color-mode-client-config.js'
+describe('cross-domain-color-mode-client-config', () => {
+  afterEach(() => {
+    setChronogroveCrossDomainColorModeClientConfig(null)
+  })
+  it('stores registrableDomain and optional cookieName', () => {
+    setChronogroveCrossDomainColorModeClientConfig({
+      registrableDomain: 'example.com',
+      cookieName: 'my-mode'
+    })
+    expect(getChronogroveCrossDomainColorModeClientConfig()).toEqual({
+      registrableDomain: 'example.com',
+      cookieName: 'my-mode'
+    })
+  })
+  it('uses default cookie name when cookieName is omitted', () => {
+    setChronogroveCrossDomainColorModeClientConfig({ registrableDomain: 'example.com' })
+    expect(getChronogroveCrossDomainColorModeClientConfig()?.cookieName).toBe(
+      CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+    )
+  })
+  it('clears config for null, invalid, or empty registrableDomain', () => {
+    setChronogroveCrossDomainColorModeClientConfig({ registrableDomain: 'example.com' })
+    setChronogroveCrossDomainColorModeClientConfig(null)
+    expect(getChronogroveCrossDomainColorModeClientConfig()).toBe(null)
+    setChronogroveCrossDomainColorModeClientConfig({ registrableDomain: '  ' })
+    expect(getChronogroveCrossDomainColorModeClientConfig()).toBe(null)
+    setChronogroveCrossDomainColorModeClientConfig('oops')
+    expect(getChronogroveCrossDomainColorModeClientConfig()).toBe(null)
+  })
+})

package/src/color-mode/cross-domain-color-mode-cookie-node.spec.js ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * @jest-environment node
+ */
+import {
+  getChronogroveCrossDomainColorModeFromCookie,
+  getHostnameForChronogroveCrossDomainCookie,
+  setChronogroveCrossDomainColorModeCookie,
+  shouldUseSecureChronogroveCrossDomainCookie
+} from './cross-domain-color-mode-cookie.js'
+describe('cross-domain color mode cookie (Node / SSR)', () => {
+  it('setChronogroveCrossDomainColorModeCookie returns without throwing when document is undefined', () => {
+    expect(() => setChronogroveCrossDomainColorModeCookie('dark')).not.toThrow()
+  })
+  it('getChronogroveCrossDomainColorModeFromCookie uses empty string when document is undefined', () => {
+    expect(getChronogroveCrossDomainColorModeFromCookie()).toBe(null)
+  })
+  it('getHostnameForChronogroveCrossDomainCookie() returns empty when global window is absent', () => {
+    expect(getHostnameForChronogroveCrossDomainCookie()).toBe('')
+  })
+  it('shouldUseSecureChronogroveCrossDomainCookie() is false when global window is absent', () => {
+    expect(shouldUseSecureChronogroveCrossDomainCookie()).toBe(false)
+  })
+})

package/src/color-mode/cross-domain-color-mode-cookie-set-http.spec.js ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * @jest-environment jsdom
+ * @jest-environment-options {"url":"http://app.example.com/"}
+ */
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME } from './constants.js'
+import { setChronogroveCrossDomainColorModeCookie } from './cross-domain-color-mode-cookie.js'
+const exampleDomain = { registrableDomain: 'example.com' }
+describe('setChronogroveCrossDomainColorModeCookie (http, cross-domain enabled)', () => {
+  let lastAssignment = ''
+  let originalDescriptor
+  beforeEach(() => {
+    lastAssignment = ''
+    originalDescriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'cookie')
+    Object.defineProperty(document, 'cookie', {
+      configurable: true,
+      get() {
+        if (!lastAssignment) return ''
+        return lastAssignment.split(';')[0].trim()
+      },
+      set(value) {
+        lastAssignment = value
+      }
+    })
+  })
+  afterEach(() => {
+    if (originalDescriptor) {
+      Object.defineProperty(Document.prototype, 'cookie', originalDescriptor)
+    }
+  })
+  it('omits Secure when not on HTTPS', () => {
+    expect(window.location.protocol).toBe('http:')
+    setChronogroveCrossDomainColorModeCookie('default', exampleDomain)
+    expect(lastAssignment).toContain(`${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=default`)
+    expect(lastAssignment).not.toContain('Secure')
+  })
+})

package/src/color-mode/cross-domain-color-mode-cookie-set-https.spec.js ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * @jest-environment jsdom
+ * @jest-environment-options {"url":"https://www.example.com/path"}
+ */
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME } from './constants.js'
+import { setChronogroveCrossDomainColorModeCookie } from './cross-domain-color-mode-cookie.js'
+const exampleDomain = { registrableDomain: 'example.com' }
+describe('setChronogroveCrossDomainColorModeCookie (https, cross-domain enabled)', () => {
+  let lastAssignment = ''
+  let originalDescriptor
+  beforeEach(() => {
+    lastAssignment = ''
+    originalDescriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'cookie')
+    Object.defineProperty(document, 'cookie', {
+      configurable: true,
+      get() {
+        if (!lastAssignment) return ''
+        return lastAssignment.split(';')[0].trim()
+      },
+      set(value) {
+        lastAssignment = value
+      }
+    })
+  })
+  afterEach(() => {
+    if (originalDescriptor) {
+      Object.defineProperty(Document.prototype, 'cookie', originalDescriptor)
+    }
+  })
+  it('sets Domain, SameSite, Max-Age, and Secure on HTTPS (assignment string)', () => {
+    expect(window.location.hostname).toBe('www.example.com')
+    setChronogroveCrossDomainColorModeCookie('dark', exampleDomain)
+    expect(lastAssignment).toContain(`${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=dark`)
+    expect(lastAssignment).toContain('Domain=.example.com')
+    expect(lastAssignment).toContain('SameSite=Lax')
+    expect(lastAssignment).toContain('Max-Age=')
+    expect(lastAssignment).toContain('Secure')
+  })
+  it('ignores invalid mode values', () => {
+    setChronogroveCrossDomainColorModeCookie('not-a-mode', exampleDomain)
+    expect(lastAssignment).toBe('')
+  })
+})

package/src/color-mode/cross-domain-color-mode-cookie-set-localhost.spec.js ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * @jest-environment jsdom
+ * @jest-environment-options {"url":"http://localhost:3000/"}
+ */
+import { setChronogroveCrossDomainColorModeCookie } from './cross-domain-color-mode-cookie.js'
+describe('setChronogroveCrossDomainColorModeCookie (localhost)', () => {
+  it('does not set when hostname is not under the registrable domain', () => {
+    expect(window.location.hostname).toBe('localhost')
+    document.cookie = ''
+    setChronogroveCrossDomainColorModeCookie('dark', { registrableDomain: 'example.com' })
+    expect(document.cookie).toBe('')
+  })
+})

package/src/color-mode/cross-domain-color-mode-cookie.js ADDED Viewed

@@ -0,0 +1,91 @@
+import {
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_MAX_AGE_SEC,
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+} from './constants.js'
+import { normalizeThemeUiColorMode } from './normalize.js'
+import { isHostnameUnderRegistrableDomain, validateRegistrableDomain } from './registrable-domain.js'
+/**
+ * Read `window.location.hostname` when `location` exists (for tests, pass a stub `globalWindow`).
+ * Call with **no arguments** to use the real `window`; passing `undefined` explicitly is treated as
+ * “no window” (tests only).
+ */
+export function getHostnameForChronogroveCrossDomainCookie(globalWindow) {
+  const win = arguments.length === 0 ? (typeof window !== 'undefined' ? window : undefined) : globalWindow
+  if (win == null || !win.location) {
+    return ''
+  }
+  return win.location.hostname || ''
+}
+/** Whether to append `Secure` to the cross-domain cookie (HTTPS only). */
+export function shouldUseSecureChronogroveCrossDomainCookie(globalWindow) {
+  const win = arguments.length === 0 ? (typeof window !== 'undefined' ? window : undefined) : globalWindow
+  return Boolean(win && win.location && win.location.protocol === 'https:')
+}
+/**
+ * Read a single cookie value from a `document.cookie`-style string (for tests and SSR-safe parsing).
+ */
+export function parseChronogroveColorModeCookie(
+  cookieString,
+  cookieName = CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+) {
+  if (!cookieString) {
+    return null
+  }
+  const parts = `; ${cookieString}`.split(`; ${cookieName}=`)
+  if (parts.length < 2) {
+    return null
+  }
+  const raw = parts.pop().split(';').shift()
+  if (raw == null || raw === '') {
+    return null
+  }
+  let decoded
+  try {
+    decoded = decodeURIComponent(raw.trim())
+  } catch {
+    decoded = raw.trim()
+  }
+  return normalizeThemeUiColorMode(decoded)
+}
+export function getChronogroveCrossDomainColorModeFromCookie(
+  cookieString = typeof document !== 'undefined' ? document.cookie : ''
+) {
+  return parseChronogroveColorModeCookie(cookieString)
+}
+/**
+ * Persist color mode for other subdomains of `options.registrableDomain`. No-op without `document`,
+ * without a valid `registrableDomain`, or when the current host is not under that domain.
+ *
+ * @param {string} mode
+ * @param {{ registrableDomain: string, cookieName?: string } | null | undefined} [options]
+ */
+export function setChronogroveCrossDomainColorModeCookie(mode, options) {
+  if (typeof document === 'undefined') {
+    return
+  }
+  const normalized = normalizeThemeUiColorMode(mode)
+  if (!normalized) {
+    return
+  }
+  const registrableDomain = options && validateRegistrableDomain(options.registrableDomain)
+  if (!registrableDomain) {
+    return
+  }
+  const hostname = getHostnameForChronogroveCrossDomainCookie()
+  if (!isHostnameUnderRegistrableDomain(hostname, registrableDomain)) {
+    return
+  }
+  const cookieName = options.cookieName ?? CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+  const value = encodeURIComponent(normalized)
+  let cookie = `${cookieName}=${value}; Path=/; Max-Age=${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_MAX_AGE_SEC}; SameSite=Lax; Domain=.${registrableDomain}`
+  if (shouldUseSecureChronogroveCrossDomainCookie()) {
+    cookie += '; Secure'
+  }
+  document.cookie = cookie
+}

package/src/color-mode/cross-domain-color-mode-cookie.spec.js ADDED Viewed

@@ -0,0 +1,120 @@
+/**
+ * @jest-environment jsdom
+ */
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME } from './constants.js'
+import {
+  getChronogroveCrossDomainColorModeFromCookie,
+  getHostnameForChronogroveCrossDomainCookie,
+  parseChronogroveColorModeCookie,
+  setChronogroveCrossDomainColorModeCookie,
+  shouldUseSecureChronogroveCrossDomainCookie
+} from './cross-domain-color-mode-cookie.js'
+describe('getHostnameForChronogroveCrossDomainCookie', () => {
+  it('returns empty string when window is missing or has no location', () => {
+    expect(getHostnameForChronogroveCrossDomainCookie(undefined)).toBe('')
+    expect(getHostnameForChronogroveCrossDomainCookie(null)).toBe('')
+    expect(getHostnameForChronogroveCrossDomainCookie({})).toBe('')
+    expect(getHostnameForChronogroveCrossDomainCookie({ location: null })).toBe('')
+  })
+  it('returns hostname or empty when location exists', () => {
+    expect(getHostnameForChronogroveCrossDomainCookie({ location: { hostname: 'www.example.com' } })).toBe(
+      'www.example.com'
+    )
+    expect(getHostnameForChronogroveCrossDomainCookie({ location: { hostname: '' } })).toBe('')
+  })
+})
+describe('shouldUseSecureChronogroveCrossDomainCookie', () => {
+  it('is true only for https:', () => {
+    expect(shouldUseSecureChronogroveCrossDomainCookie(undefined)).toBe(false)
+    expect(shouldUseSecureChronogroveCrossDomainCookie({})).toBe(false)
+    expect(shouldUseSecureChronogroveCrossDomainCookie({ location: { protocol: 'http:' } })).toBe(false)
+    expect(shouldUseSecureChronogroveCrossDomainCookie({ location: { protocol: 'https:' } })).toBe(true)
+    expect(shouldUseSecureChronogroveCrossDomainCookie({ location: {} })).toBe(false)
+  })
+})
+describe('setChronogroveCrossDomainColorModeCookie', () => {
+  it('no-ops without options.registrableDomain', () => {
+    document.cookie = ''
+    setChronogroveCrossDomainColorModeCookie('dark')
+    setChronogroveCrossDomainColorModeCookie('dark', {})
+    setChronogroveCrossDomainColorModeCookie('dark', { registrableDomain: '  ' })
+    expect(document.cookie).toBe('')
+  })
+})
+describe('parseChronogroveColorModeCookie', () => {
+  it('returns normalized mode when cookie is present', () => {
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=dark`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe('dark')
+    expect(
+      parseChronogroveColorModeCookie(
+        `other=1; ${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=default`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe('default')
+  })
+  it('maps light to default', () => {
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=light`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe('default')
+  })
+  it('returns null for missing or invalid values', () => {
+    expect(parseChronogroveColorModeCookie('', CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME)).toBe(null)
+    expect(parseChronogroveColorModeCookie('other=1', CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME)).toBe(null)
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe(null)
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=nope`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe(null)
+  })
+  it('falls back to raw when decodeURIComponent throws', () => {
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=%`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe(null)
+  })
+  it('decodes URI-encoded values', () => {
+    expect(
+      parseChronogroveColorModeCookie(
+        `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=dark`,
+        CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+      )
+    ).toBe('dark')
+  })
+})
+describe('getChronogroveCrossDomainColorModeFromCookie', () => {
+  beforeEach(() => {
+    document.cookie = `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=; Path=/; Max-Age=0`
+  })
+  it('reads from document.cookie when called with no arguments', () => {
+    document.cookie = `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=dark`
+    expect(getChronogroveCrossDomainColorModeFromCookie()).toBe('dark')
+  })
+})

package/src/color-mode/head-inline-resolution.spec.js ADDED Viewed

@@ -0,0 +1,111 @@
+/**
+ * @jest-environment jsdom
+ */
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME, THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { buildInitialThemeUiColorModeResolutionInlineFragment } from './head-inline.js'
+function expireCrossDomainColorModeCookie() {
+  document.cookie = `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=; Path=/; Max-Age=0`
+}
+/**
+ * Executes the same inline fragment used in no-flash / HTML background scripts to verify
+ * cookie-vs-localStorage precedence without a full browser.
+ */
+function runResolutionFragment({ cookie, localStorageMap, prefersDark, crossDomainColorMode = null }) {
+  expireCrossDomainColorModeCookie()
+  document.cookie = cookie || ''
+  window.localStorage.clear()
+  if (localStorageMap) {
+    for (const [k, v] of Object.entries(localStorageMap)) {
+      window.localStorage.setItem(k, v)
+    }
+  }
+  window.matchMedia = jest.fn(() => ({
+    matches: Boolean(prefersDark),
+    media: '(prefers-color-scheme: dark)',
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+    onchange: null
+  }))
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(
+    THEME_UI_COLOR_MODE_STORAGE_KEY,
+    crossDomainColorMode
+  )
+  const getMode = new Function(`
+    ${fragment}
+    return mode;
+  `)
+  return getMode()
+}
+describe('buildInitialThemeUiColorModeResolutionInlineFragment', () => {
+  beforeEach(() => {
+    expireCrossDomainColorModeCookie()
+    window.localStorage.clear()
+  })
+  it('prefers cookie over localStorage when both differ', () => {
+    const mode = runResolutionFragment({
+      cookie: 'chronogrove-theme-ui-color-mode=default',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: true,
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(mode).toBe('default')
+    expect(window.localStorage.getItem(THEME_UI_COLOR_MODE_STORAGE_KEY)).toBe('default')
+  })
+  it('ignores cookie when registrableDomain is invalid (falls back to local-only logic)', () => {
+    const mode = runResolutionFragment({
+      cookie: 'chronogrove-theme-ui-color-mode=default',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: true,
+      crossDomainColorMode: { registrableDomain: 'bad..tld' }
+    })
+    expect(mode).toBe('dark')
+  })
+  it('uses localStorage when cookie is absent', () => {
+    const mode = runResolutionFragment({
+      cookie: '',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: false
+    })
+    expect(mode).toBe('dark')
+  })
+  it('falls back to prefers-color-scheme when cookie and storage are empty', () => {
+    const dark = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: true })
+    expect(dark).toBe('dark')
+    expect(window.localStorage.getItem(THEME_UI_COLOR_MODE_STORAGE_KEY)).toBe('dark')
+    window.localStorage.clear()
+    const light = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: false })
+    expect(light).toBe('default')
+  })
+  it('normalizes light in localStorage to default', () => {
+    const mode = runResolutionFragment({
+      cookie: '',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'light' },
+      prefersDark: false
+    })
+    expect(mode).toBe('default')
+  })
+  it('handles localStorage getItem throwing in legacy fragment', () => {
+    const spy = jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('blocked')
+    })
+    const mode = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: false })
+    expect(mode).toBe('default')
+    spy.mockRestore()
+  })
+})

package/src/color-mode/head-inline.js CHANGED Viewed

@@ -3,26 +3,104 @@ import {
   chronogroveThemeSurfaceColorsLight
 } from '../chronogrove-theme-surface-colors.js'
-import { THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME, THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { validateRegistrableDomain } from './registrable-domain.js'
 function q(str) {
   return JSON.stringify(str)
 }
-export function buildThemeUiNoFlashInlineScript(storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY) {
-  const key = q(storageKey)
-  return `
-    (function() {
-      try {
-        var mode = localStorage.getItem(${key});
+/**
+ * Inline JS that sets `mode` and syncs `localStorage`. When `crossDomainColorMode.registrableDomain`
+ * is set (validated), reads the shared cookie first so subdomains stay aligned.
+ *
+ * @param {string} [storageKey]
+ * @param {{ registrableDomain?: string, cookieName?: string } | null} [crossDomainColorMode]
+ */
+export function buildInitialThemeUiColorModeResolutionInlineFragment(
+  storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY,
+  crossDomainColorMode = null
+) {
+  const cookieName = crossDomainColorMode?.cookieName ?? CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+  const domainOk =
+    crossDomainColorMode &&
+    typeof crossDomainColorMode.registrableDomain === 'string' &&
+    validateRegistrableDomain(crossDomainColorMode.registrableDomain)
+  if (!domainOk) {
+    const keyOnly = q(storageKey)
+    return `
+        var __cgKey = ${keyOnly};
+        var mode;
+        try {
+          mode = localStorage.getItem(__cgKey);
+        } catch (e) {
+          mode = null;
+        }
         if (!mode) {
           var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
           mode = prefersDark ? 'dark' : 'default';
-          localStorage.setItem(${key}, mode);
         }
         if (mode === 'light') {
           mode = 'default';
         }
+        try { localStorage.setItem(__cgKey, mode); } catch (e2) {}
+  `.trim()
+  }
+  const key = q(storageKey)
+  const cname = q(cookieName)
+  return `
+        function __cgGetCookie(name) {
+          try {
+            var parts = ('; ' + document.cookie).split('; ' + name + '=');
+            if (parts.length < 2) return null;
+            var raw = parts.pop().split(';').shift() || '';
+            try { return decodeURIComponent(raw.trim()); } catch (e1) { return raw.trim(); }
+          } catch (e) { return null; }
+        }
+        function __cgNormMode(m) {
+          if (m === 'light') return 'default';
+          if (m === 'dark' || m === 'default') return m;
+          return null;
+        }
+        var __cgKey = ${key};
+        var __cgCookieMode = __cgNormMode(__cgGetCookie(${cname}));
+        var mode;
+        if (__cgCookieMode) {
+          mode = __cgCookieMode;
+          try { localStorage.setItem(__cgKey, mode); } catch (e) {}
+        } else {
+          try {
+            mode = localStorage.getItem(__cgKey);
+          } catch (e) {
+            mode = null;
+          }
+          if (!mode) {
+            var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+            mode = prefersDark ? 'dark' : 'default';
+          }
+          if (mode === 'light') {
+            mode = 'default';
+          }
+          try { localStorage.setItem(__cgKey, mode); } catch (e2) {}
+        }
+        if (mode === 'light') {
+          mode = 'default';
+        }
+  `.trim()
+}
+/**
+ * @param {string | { storageKey?: string, crossDomainColorMode?: { registrableDomain?: string, cookieName?: string } | null }} [options]
+ */
+export function buildThemeUiNoFlashInlineScript(options) {
+  const { storageKey, crossDomainColorMode } = normalizeNoFlashInlineScriptOptions(options)
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(storageKey, crossDomainColorMode)
+  return `
+    (function() {
+      try {
+        ${fragment}
         var htmlElement = document.documentElement;
         var classesToRemove = [];
         for (var i = 0; i < htmlElement.classList.length; i++) {
@@ -41,23 +119,32 @@ export function buildThemeUiNoFlashInlineScript(storageKey = THEME_UI_COLOR_MODE
   `
 }
+function normalizeNoFlashInlineScriptOptions(options) {
+  if (options == null || typeof options === 'string') {
+    return {
+      storageKey: typeof options === 'string' ? options : THEME_UI_COLOR_MODE_STORAGE_KEY,
+      crossDomainColorMode: null
+    }
+  }
+  return {
+    storageKey: options.storageKey ?? THEME_UI_COLOR_MODE_STORAGE_KEY,
+    crossDomainColorMode: options.crossDomainColorMode ?? null
+  }
+}
 export function buildHtmlBackgroundInlineScript({
   storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY,
   defaultBackgroundHex,
-  darkBackgroundHex
-}) {
-  const key = q(storageKey)
+  darkBackgroundHex,
+  crossDomainColorMode = null
+} = {}) {
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(storageKey, crossDomainColorMode)
   const lightBg = q(defaultBackgroundHex)
   const darkBg = q(darkBackgroundHex)
   return `
     (function() {
       try {
-        var mode = localStorage.getItem(${key});
-        if (!mode) {
-          var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-          mode = prefersDark ? 'dark' : 'default';
-          localStorage.setItem(${key}, mode);
-        }
+        ${fragment}
         var bgColor = mode === 'dark' ? ${darkBg} : ${lightBg};
         document.documentElement.style.backgroundColor = bgColor;
       } catch (e) {}

package/src/color-mode/head-inline.spec.js CHANGED Viewed

@@ -1,16 +1,68 @@
 import {
   buildHtmlBackgroundInlineScript,
+  buildInitialThemeUiColorModeResolutionInlineFragment,
   buildThemeUiColorModeFallbackCss,
   buildThemeUiNoFlashInlineScript
 } from './head-inline.js'
 describe('head-inline scripts', () => {
-  it('buildThemeUiNoFlashInlineScript references storage and data attribute', () => {
+  it('buildInitialThemeUiColorModeResolutionInlineFragment() uses default args (local-only)', () => {
+    const fragment = buildInitialThemeUiColorModeResolutionInlineFragment()
+    expect(fragment).not.toContain('__cgGetCookie')
+  })
+  it('buildThemeUiNoFlashInlineScript uses localStorage-only resolution when cross-domain is off', () => {
     const s = buildThemeUiNoFlashInlineScript()
     expect(s).toContain('theme-ui-color-mode')
+    expect(s).toContain('localStorage.getItem')
+    expect(s).not.toContain('__cgGetCookie')
     expect(s).toContain('data-theme-ui-color-mode')
   })
+  it('embeds cookie merge when crossDomainColorMode.registrableDomain is set', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('chronogrove-theme-ui-color-mode')
+  })
+  it('respects optional cookieName when registrableDomain is set', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'example.com', cookieName: 'my-shared-mode' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('my-shared-mode')
+  })
+  it('treats crossDomainColorMode without registrableDomain as local-only', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { cookieName: 'orphan-name' }
+    })
+    expect(s).not.toContain('__cgGetCookie')
+  })
+  it('omits cookie merge when registrableDomain is invalid', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'a..b' }
+    })
+    expect(s).not.toContain('__cgGetCookie')
+  })
+  it('accepts a custom storage key string (legacy signature)', () => {
+    const s = buildThemeUiNoFlashInlineScript('my-mode-key')
+    expect(s).toContain('my-mode-key')
+  })
+  it('accepts storageKey on the options object with cross-domain config', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      storageKey: 'custom-storage',
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('custom-storage')
+    expect(s).toContain('__cgGetCookie')
+  })
   it('buildHtmlBackgroundInlineScript embeds background hexes', () => {
     const s = buildHtmlBackgroundInlineScript({
       defaultBackgroundHex: '#aaa',
@@ -20,6 +72,21 @@ describe('head-inline scripts', () => {
     expect(s).toContain('#bbb')
   })
+  it('passes crossDomainColorMode through to the resolution fragment', () => {
+    const s = buildHtmlBackgroundInlineScript({
+      defaultBackgroundHex: '#aaa',
+      darkBackgroundHex: '#bbb',
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('#aaa')
+  })
+  it('applies the default empty options object when buildHtmlBackgroundInlineScript is called with no args', () => {
+    const s = buildHtmlBackgroundInlineScript()
+    expect(s).toContain('document.documentElement.style.backgroundColor')
+  })
   it('buildThemeUiColorModeFallbackCss sets CSS vars', () => {
     const css = buildThemeUiColorModeFallbackCss({
       defaultBackgroundHex: '#fdf8f5',

package/src/color-mode/index.js CHANGED Viewed

@@ -1,15 +1,30 @@
 export {
   THEME_UI_COLOR_MODE_STORAGE_KEY,
   RECONCILE_COLOR_MODE_EVENT,
-  CHRONOGROVE_COLOR_MODE_HEAD_PRIORITY_KEYS
+  CHRONOGROVE_COLOR_MODE_HEAD_PRIORITY_KEYS,
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME,
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_MAX_AGE_SEC
 } from './constants.js'
+export {
+  getHostnameForChronogroveCrossDomainCookie,
+  shouldUseSecureChronogroveCrossDomainCookie,
+  parseChronogroveColorModeCookie,
+  getChronogroveCrossDomainColorModeFromCookie,
+  setChronogroveCrossDomainColorModeCookie
+} from './cross-domain-color-mode-cookie.js'
+export {
+  setChronogroveCrossDomainColorModeClientConfig,
+  getChronogroveCrossDomainColorModeClientConfig
+} from './cross-domain-color-mode-client-config.js'
+export { validateRegistrableDomain, isHostnameUnderRegistrableDomain } from './registrable-domain.js'
 export { normalizeThemeUiColorMode } from './normalize.js'
 export { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
 export { chronogroveHeadTheme } from './chronogrove-head-theme.js'
 export {
   buildThemeUiNoFlashInlineScript,
   buildHtmlBackgroundInlineScript,
-  buildThemeUiColorModeFallbackCss
+  buildThemeUiColorModeFallbackCss,
+  buildInitialThemeUiColorModeResolutionInlineFragment
 } from './head-inline.js'
 export { resolveThemeUiColorMode, syncThemeUiColorMode, scheduleThemeUiColorModeSync } from './browser-sync.js'
 export { reconcileThemeUiColorModeOnNavigation } from './spa-navigation.js'

package/src/color-mode/registrable-domain.js ADDED Viewed

@@ -0,0 +1,30 @@
+/**
+ * Public suffix / site registrable domain used for `Domain=` on shared cookies (e.g. `example.com`,
+ * not `www.example.com`). Must be safe to embed in a Set-Cookie line.
+ */
+export function validateRegistrableDomain(registrableDomain) {
+  if (typeof registrableDomain !== 'string') {
+    return null
+  }
+  const t = registrableDomain.trim().toLowerCase()
+  if (!t || t.includes('..') || !/^[a-z0-9.-]+$/.test(t)) {
+    return null
+  }
+  return t
+}
+/**
+ * True when `hostname` is the apex or a subdomain of `registrableDomain` (e.g. `www.example.com`
+ * under `example.com`). Rejects lookalikes like `notexample.com`.
+ */
+export function isHostnameUnderRegistrableDomain(hostname, registrableDomain) {
+  const base = validateRegistrableDomain(registrableDomain)
+  if (!base) {
+    return false
+  }
+  if (!hostname || typeof hostname !== 'string') {
+    return false
+  }
+  const h = hostname.trim().toLowerCase()
+  return h === base || h.endsWith(`.${base}`)
+}

package/src/color-mode/registrable-domain.spec.js ADDED Viewed

@@ -0,0 +1,28 @@
+import { isHostnameUnderRegistrableDomain, validateRegistrableDomain } from './registrable-domain.js'
+describe('validateRegistrableDomain', () => {
+  it('normalizes and rejects unsafe values', () => {
+    expect(validateRegistrableDomain(' Example.COM ')).toBe('example.com')
+    expect(validateRegistrableDomain('')).toBe(null)
+    expect(validateRegistrableDomain('a..b')).toBe(null)
+    expect(validateRegistrableDomain('bad;path')).toBe(null)
+  })
+})
+describe('isHostnameUnderRegistrableDomain', () => {
+  it('matches apex and subdomains', () => {
+    expect(isHostnameUnderRegistrableDomain('www.example.com', 'example.com')).toBe(true)
+    expect(isHostnameUnderRegistrableDomain('example.com', 'example.com')).toBe(true)
+  })
+  it('rejects hosts outside the registrable domain', () => {
+    expect(isHostnameUnderRegistrableDomain('notexample.com', 'example.com')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('localhost', 'example.com')).toBe(false)
+  })
+  it('rejects invalid inputs', () => {
+    expect(isHostnameUnderRegistrableDomain('', 'example.com')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('www.example.com', '')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('www.example.com', 'bad..')).toBe(false)
+  })
+})

package/src/color-toggle.js CHANGED Viewed

@@ -2,6 +2,8 @@ import React, { useEffect } from 'react'
 import { useColorMode } from 'theme-ui'
 import { Expand } from '@theme-toggles/react'
 import { scheduleThemeUiColorModeSync } from './color-mode/browser-sync.js'
+import { getChronogroveCrossDomainColorModeClientConfig } from './color-mode/cross-domain-color-mode-client-config.js'
+import { setChronogroveCrossDomainColorModeCookie } from './color-mode/cross-domain-color-mode-cookie.js'
 import isDarkMode from './helpers/isDarkMode.js'
 export default function ColorToggle() {
@@ -13,6 +15,7 @@ export default function ColorToggle() {
   // attribute makes toggles appear to do nothing. Run after ancestor effects so localStorage matches.
   useEffect(() => {
     scheduleThemeUiColorModeSync()
+    setChronogroveCrossDomainColorModeCookie(colorMode, getChronogroveCrossDomainColorModeClientConfig() ?? undefined)
   }, [colorMode])
   return (

package/src/gatsby/build-theme-ui-color-mode-head-components.js CHANGED Viewed

@@ -11,15 +11,16 @@ import {
  * React head elements for Theme UI color mode: no-flash script, HTML background script, fallback CSS.
  * Compose with your own meta tags (e.g. Emotion insertion point) in `onRenderBody`.
  *
- * @param {{ theme: object }} options — Theme UI theme object (same as `ThemeUIProvider`)
+ * @param {{ theme: object, crossDomainColorMode?: { registrableDomain?: string, cookieName?: string } | null }} options — Theme UI theme object (same as `ThemeUIProvider`). Optional `crossDomainColorMode` enables subdomain cookie sync (must match the same object passed to `setChronogroveCrossDomainColorModeClientConfig` in the browser).
  * @returns {import('react').ReactElement[]}
  */
-export function buildThemeUiColorModeHeadComponents({ theme }) {
+export function buildThemeUiColorModeHeadComponents({ theme, crossDomainColorMode = null }) {
   const surface = resolveChronogroveSurfaceColors(theme)
-  const colorModeScript = buildThemeUiNoFlashInlineScript()
+  const colorModeScript = buildThemeUiNoFlashInlineScript({ crossDomainColorMode })
   const htmlBackgroundScript = buildHtmlBackgroundInlineScript({
     defaultBackgroundHex: surface.defaultBackgroundHex,
-    darkBackgroundHex: surface.darkBackgroundHex
+    darkBackgroundHex: surface.darkBackgroundHex,
+    crossDomainColorMode
   })
   const colorModeFallbackCSS = buildThemeUiColorModeFallbackCss({
     defaultBackgroundHex: surface.defaultBackgroundHex,

package/src/gatsby/index.spec.js CHANGED Viewed

@@ -28,7 +28,8 @@ describe('@chronogrove/ui/gatsby', () => {
       const { container: colorModeScriptContainer } = render(head[0])
       const colorModeScriptTag = colorModeScriptContainer.querySelector('script')
-      expect(colorModeScriptTag).toHaveTextContent(/localStorage\.getItem\(['"]theme-ui-color-mode['"]\)/)
+      expect(colorModeScriptTag).toHaveTextContent(/localStorage\.getItem\(__cgKey\)/)
+      expect(colorModeScriptTag.textContent).not.toContain('__cgGetCookie')
       expect(colorModeScriptTag).toHaveTextContent(/data-theme-ui-color-mode/)
       const { container: htmlBgScriptContainer } = render(head[1])
@@ -43,6 +44,15 @@ describe('@chronogrove/ui/gatsby', () => {
       expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-background:/)
       expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-text:/)
     })
+    it('embeds cookie merge when crossDomainColorMode.registrableDomain is set', () => {
+      const head = buildThemeUiColorModeHeadComponents({
+        theme: chronogroveTheme,
+        crossDomainColorMode: { registrableDomain: 'example.com' }
+      })
+      const { container } = render(head[0])
+      expect(container.querySelector('script').textContent).toContain('__cgGetCookie')
+    })
   })
   describe('onPreRenderHTMLSortThemeUiColorModeFirst', () => {

package/src/next/app-shell.js CHANGED Viewed

@@ -1,9 +1,11 @@
 'use client'
+import { useEffect } from 'react'
 import { Box } from '@theme-ui/components'
 import { ChronogroveAnimatedPageBackground } from '../animated-page-background/index.js'
-import { useDocumentColorModeSurface } from '../color-mode/index.js'
+import { setChronogroveCrossDomainColorModeClientConfig, useDocumentColorModeSurface } from '../color-mode/index.js'
 import { ChronogroveThemeProvider } from '../provider.js'
 import chronogroveTheme from '../theme.js'
@@ -19,8 +21,16 @@ function DocumentColorModeSurface() {
  * Default Next.js App Router shell: Theme UI provider, three.js Color Bends background (same as
  * Gatsby home), document surface sync, and soft-navigation color-mode reconcile. Wrap with
  * {@link ChronogroveNextEmotionRegistry} in `layout.jsx` outside this component.
+ *
+ * Pass the same `crossDomainColorMode` as {@link ChronogroveNextRootLayoutHead} so toggles write the
+ * shared cookie (optional).
  */
-export function ChronogroveNextAppShell({ children, theme = chronogroveTheme }) {
+export function ChronogroveNextAppShell({ children, theme = chronogroveTheme, crossDomainColorMode = null }) {
+  useEffect(() => {
+    setChronogroveCrossDomainColorModeClientConfig(crossDomainColorMode)
+    return () => setChronogroveCrossDomainColorModeClientConfig(null)
+  }, [crossDomainColorMode?.cookieName, crossDomainColorMode?.registrableDomain])
   return (
     <ChronogroveThemeProvider theme={theme}>
       <ChronogroveAnimatedPageBackground />

package/src/next/root-layout-head.js CHANGED Viewed

@@ -10,13 +10,16 @@ import {
  * Server Component fragment for the root `<head>`: Emotion insertion point, Theme UI no-flash
  * script, HTML background script, and fallback CSS (same composition as
  * `buildThemeUiColorModeHeadComponents` for Gatsby).
+ *
+ * @param {{ crossDomainColorMode?: { registrableDomain?: string, cookieName?: string } | null }} [props]
  */
-export function ChronogroveNextRootLayoutHead() {
+export function ChronogroveNextRootLayoutHead({ crossDomainColorMode = null } = {}) {
   const surface = resolveChronogroveSurfaceColors(chronogroveHeadTheme)
-  const colorModeScript = buildThemeUiNoFlashInlineScript()
+  const colorModeScript = buildThemeUiNoFlashInlineScript({ crossDomainColorMode })
   const htmlBackgroundScript = buildHtmlBackgroundInlineScript({
     defaultBackgroundHex: surface.defaultBackgroundHex,
-    darkBackgroundHex: surface.darkBackgroundHex
+    darkBackgroundHex: surface.darkBackgroundHex,
+    crossDomainColorMode
   })
   const colorModeFallbackCSS = buildThemeUiColorModeFallbackCss({
     defaultBackgroundHex: surface.defaultBackgroundHex,