@weaverse/hydrogen 5.20.0 → 5.20.2

package/dist/types/utils/is-same-loader-payload.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Structural comparison used to detect whether a reused Weaverse instance
+ * must adopt a fresh loader payload.
+ *
+ * `JSON.stringify` cannot do this job on the client:
+ *
+ * - Route loader data reaches `dataContext` unserialized, so deferred values
+ *   are still `Promise`s. React 19 development builds hang an enumerable,
+ *   self-referencing `_debugInfo` off those promises, and stringifying one
+ *   throws `TypeError: Converting circular structure to JSON` during render
+ *   (issue #511).
+ * - In production every promise stringifies to `{}`, so a *fresh* deferred
+ *   value looks unchanged and the reused instance keeps serving the previous
+ *   render's promise. Tokenizing promises to a constant (`'[[promise]]'`) has
+ *   the same defect — it is stable by construction, therefore blind to
+ *   identity.
+ *
+ * Semantics, chosen deliberately:
+ *
+ * - **Promises/thenables are atomic**: compared by identity, never traversed.
+ *   A fresh promise is a change; the same promise is not. Debug metadata is
+ *   invisible to the comparison.
+ * - **Opaque objects are atomic**: anything that is not a plain object, an
+ *   array, or `toJSON`-serializable (`Map`, `Set`, `URL`, `RegExp`, streams,
+ *   async iterators, cross-realm promises, class instances) is compared by
+ *   identity. `JSON.stringify` flattens all of them to `{}`, which would
+ *   silently collapse two distinct async values into "unchanged".
+ * - **Cyclic graphs are compared coinductively**: a pair already being
+ *   compared is assumed equal, so equal self/mutual cycles are equal while a
+ *   differing leaf anywhere still reports a change. Nothing throws.
+ * - **JSON-visible fields only**: `undefined`/function/symbol properties are
+ *   omitted from objects and read as `null` in arrays, and NaN/±Infinity read
+ *   as `null` — matching the previous `JSON.stringify` behavior for plain wire
+ *   payloads. Key order is irrelevant, which removes the old "false mismatch
+ *   costs a re-render" caveat.
+ */
+/** Compares two loader payloads for JSON-visible structural equality. */
+export declare function isSameLoaderPayload(left: unknown, right: unknown): boolean;
+//# sourceMappingURL=is-same-loader-payload.d.ts.map

package/dist/types/utils/is-same-loader-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-same-loader-payload.d.ts","sourceRoot":"","sources":["../../../src/utils/is-same-loader-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAiH1E"}

package/dist/types/utils/sync-reused-instance.d.ts

@@ -13,9 +13,11 @@ import type { WeaverseHydrogen } from '../WeaverseHydrogenRoot';
  * (unsaved drafts must not be clobbered) and applies updates via
  * `refreshStudio` instead.
  *
- * Change detection uses JSON comparison — loader payloads are
- * wire-serialized, so key order is stable between runs; a false mismatch
- * only costs one extra re-render.
+ * Change detection uses {@link isSameLoaderPayload}: a structural comparison
+ * that treats promises/thenables and other opaque objects as atomic values
+ * compared by identity, and tolerates cyclic graphs. `dataContext` carries
+ * live route loader data — including unresolved deferred promises whose React
+ * development metadata is cyclic — so it cannot be JSON-serialized here.
  */
 export declare function syncReusedInstance(weaverse: WeaverseHydrogen, params: WeaverseHydrogenParams): void;
 //# sourceMappingURL=sync-reused-instance.d.ts.map

package/dist/types/utils/sync-reused-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-reused-instance.d.ts","sourceRoot":"","sources":["../../../src/utils/sync-reused-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,sBAAsB,QAkC/B"}
+{"version":3,"file":"sync-reused-instance.d.ts","sourceRoot":"","sources":["../../../src/utils/sync-reused-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAG/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,sBAAsB,QAkC/B"}

package/dist/types/utils/use-studio.d.ts

@@ -29,5 +29,4 @@ import type { WeaverseHydrogen } from '../index';
  */
 export declare function useStudioConnect(): void;
 export declare function useStudio(weaverse: WeaverseHydrogen): void;
-export declare function usePixel(context: WeaverseHydrogen): void;
 //# sourceMappingURL=use-studio.d.ts.map

package/dist/types/utils/use-studio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-studio.d.ts","sourceRoot":"","sources":["../../../src/utils/use-studio.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAoChD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,SAW/B;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,QAkDnD;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,QA6BjD"}
+{"version":3,"file":"use-studio.d.ts","sourceRoot":"","sources":["../../../src/utils/use-studio.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AA+BhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,SAW/B;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,QAiDnD"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@weaverse/hydrogen",
   "author": "Weaverse Team",
   "description": "Components, hooks, and utilities for building Shopify Hydrogen websites with Weaverse",
-  "version": "5.20.0",
+  "version": "5.20.2",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/types/index.d.ts",
@@ -46,8 +46,8 @@
   "dependencies": {
     "@shopify/hydrogen": ">=2025.5",
     "@shopify/remix-oxygen": "3",
-    "@weaverse/react": "5.20.0",
-    "@weaverse/schema": "0.13.1",
+    "@weaverse/react": "5.20.2",
+    "@weaverse/schema": "0.14.0",
     "react": ">=19",
     "react-dom": ">=19",
     "react-error-boundary": "^6",

package/src/utils/is-same-loader-payload.ts

@@ -0,0 +1,187 @@
+/**
+ * Structural comparison used to detect whether a reused Weaverse instance
+ * must adopt a fresh loader payload.
+ *
+ * `JSON.stringify` cannot do this job on the client:
+ *
+ * - Route loader data reaches `dataContext` unserialized, so deferred values
+ *   are still `Promise`s. React 19 development builds hang an enumerable,
+ *   self-referencing `_debugInfo` off those promises, and stringifying one
+ *   throws `TypeError: Converting circular structure to JSON` during render
+ *   (issue #511).
+ * - In production every promise stringifies to `{}`, so a *fresh* deferred
+ *   value looks unchanged and the reused instance keeps serving the previous
+ *   render's promise. Tokenizing promises to a constant (`'[[promise]]'`) has
+ *   the same defect — it is stable by construction, therefore blind to
+ *   identity.
+ *
+ * Semantics, chosen deliberately:
+ *
+ * - **Promises/thenables are atomic**: compared by identity, never traversed.
+ *   A fresh promise is a change; the same promise is not. Debug metadata is
+ *   invisible to the comparison.
+ * - **Opaque objects are atomic**: anything that is not a plain object, an
+ *   array, or `toJSON`-serializable (`Map`, `Set`, `URL`, `RegExp`, streams,
+ *   async iterators, cross-realm promises, class instances) is compared by
+ *   identity. `JSON.stringify` flattens all of them to `{}`, which would
+ *   silently collapse two distinct async values into "unchanged".
+ * - **Cyclic graphs are compared coinductively**: a pair already being
+ *   compared is assumed equal, so equal self/mutual cycles are equal while a
+ *   differing leaf anywhere still reports a change. Nothing throws.
+ * - **JSON-visible fields only**: `undefined`/function/symbol properties are
+ *   omitted from objects and read as `null` in arrays, and NaN/±Infinity read
+ *   as `null` — matching the previous `JSON.stringify` behavior for plain wire
+ *   payloads. Key order is irrelevant, which removes the old "false mismatch
+ *   costs a re-render" caveat.
+ */
+
+/** `JSON.stringify` drops these from objects and nulls them inside arrays. */
+function isJsonOmitted(value: unknown): boolean {
+  return (
+    value === undefined ||
+    typeof value === 'function' ||
+    typeof value === 'symbol'
+  )
+}
+
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+}
+
+/** Duck-typed so cross-realm promises and hand-rolled thenables also match. */
+function isThenable(value: Record<string, unknown>): boolean {
+  return typeof value.then === 'function'
+}
+
+function isPlainObject(value: Record<string, unknown>): boolean {
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/** Returns the `toJSON()` projection, or the value itself when there is none. */
+function toJsonValue(value: Record<string, unknown>): unknown {
+  return typeof value.toJSON === 'function'
+    ? (value.toJSON as () => unknown)()
+    : value
+}
+
+/** Maps NaN/±Infinity to `null`, matching how `JSON.stringify` renders them. */
+function toFiniteOrNull(value: unknown): unknown {
+  return typeof value === 'number' && !Number.isFinite(value) ? null : value
+}
+
+/** Compares two loader payloads for JSON-visible structural equality. */
+export function isSameLoaderPayload(left: unknown, right: unknown): boolean {
+  // Pairs currently being compared, flattened as [a0, b0, a1, b1, ...].
+  // Re-entering a pair means a cycle closed on both sides; assuming equality
+  // there is what makes equal cyclic graphs compare equal (bisimulation)
+  // while a differing leaf anywhere still reports a change.
+  //
+  // Scoped to the active path rather than every visited pair, so memory stays
+  // proportional to graph depth (single digits for loader payloads) instead of
+  // node count, and the common all-equal walk allocates one array.
+  //
+  // Tradeoff: a graph that shares one subtree through many nested parents
+  // re-walks it per path. Wire-serialized loader payloads are trees, so this
+  // does not arise; memoizing equal pairs instead measured ~2x slower on a
+  // realistic 400-item page, which is the case that actually runs per render.
+  const activePairs: object[] = []
+
+  function isSame(rawA: unknown, rawB: unknown): boolean {
+    if (Object.is(rawA, rawB)) {
+      return true
+    }
+    // `JSON.stringify` renders NaN/±Infinity as `null`; normalizing here keeps
+    // a non-finite number equal to the `null` a previous wire payload carried.
+    const a = toFiniteOrNull(rawA)
+    const b = toFiniteOrNull(rawB)
+    if (a === b) {
+      // Also accepts 0/-0, which `JSON.stringify` renders identically.
+      return true
+    }
+    if (!(isObjectLike(a) && isObjectLike(b))) {
+      return false
+    }
+    if (isThenable(a) || isThenable(b)) {
+      // Identity comparison above already failed: distinct async values.
+      return false
+    }
+    for (let index = 0; index < activePairs.length; index += 2) {
+      if (activePairs[index] === a && activePairs[index + 1] === b) {
+        return true
+      }
+    }
+
+    activePairs.push(a, b)
+    try {
+      return isSameOpenPair(a, b)
+    } finally {
+      activePairs.length -= 2
+    }
+  }
+
+  function isSameOpenPair(
+    a: Record<string, unknown>,
+    b: Record<string, unknown>
+  ): boolean {
+    const aJson = toJsonValue(a)
+    const bJson = toJsonValue(b)
+    if (aJson !== a || bJson !== b) {
+      return isSame(aJson, bJson)
+    }
+
+    if (Array.isArray(a) !== Array.isArray(b)) {
+      return false
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+      return isSameArray(a, b)
+    }
+    if (!(isPlainObject(a) && isPlainObject(b))) {
+      // Opaque object with no JSON projection — identity is the only honest
+      // signal, and it already failed.
+      return false
+    }
+    return isSameObject(a, b)
+  }
+
+  function isSameArray(a: unknown[], b: unknown[]): boolean {
+    if (a.length !== b.length) {
+      return false
+    }
+    for (let index = 0; index < a.length; index++) {
+      const aItem = isJsonOmitted(a[index]) ? null : a[index]
+      const bItem = isJsonOmitted(b[index]) ? null : b[index]
+      if (!isSame(aItem, bItem)) {
+        return false
+      }
+    }
+    return true
+  }
+
+  function isSameObject(
+    a: Record<string, unknown>,
+    b: Record<string, unknown>
+  ): boolean {
+    let aKeyCount = 0
+    for (const key of Object.keys(a)) {
+      if (isJsonOmitted(a[key])) {
+        continue
+      }
+      aKeyCount++
+      // A JSON-visible value never compares equal to an omitted one, so a
+      // missing/undefined counterpart falls out of `isSame` as a change.
+      if (!isSame(a[key], b[key])) {
+        return false
+      }
+    }
+    let bKeyCount = 0
+    for (const key of Object.keys(b)) {
+      if (!isJsonOmitted(b[key])) {
+        bKeyCount++
+      }
+    }
+    return aKeyCount === bKeyCount
+  }
+
+  return isSame(left, right)
+}

package/src/utils/sync-reused-instance.ts

@@ -1,5 +1,6 @@
 import type { WeaverseHydrogenParams } from '../types'
 import type { WeaverseHydrogen } from '../WeaverseHydrogenRoot'
+import { isSameLoaderPayload } from './is-same-loader-payload'
 
 /**
  * Apply a fresh loader payload to a reused Weaverse instance.
@@ -14,9 +15,11 @@ import type { WeaverseHydrogen } from '../WeaverseHydrogenRoot'
  * (unsaved drafts must not be clobbered) and applies updates via
  * `refreshStudio` instead.
  *
- * Change detection uses JSON comparison — loader payloads are
- * wire-serialized, so key order is stable between runs; a false mismatch
- * only costs one extra re-render.
+ * Change detection uses {@link isSameLoaderPayload}: a structural comparison
+ * that treats promises/thenables and other opaque objects as atomic values
+ * compared by identity, and tolerates cyclic graphs. `dataContext` carries
+ * live route loader data — including unresolved deferred promises whose React
+ * development metadata is cyclic — so it cannot be JSON-serialized here.
  */
 export function syncReusedInstance(
   weaverse: WeaverseHydrogen,
@@ -25,11 +28,11 @@ export function syncReusedInstance(
   weaverse.requestInfo = params.requestInfo
   weaverse.internal = params.internal
 
-  let dataChanged =
-    JSON.stringify(weaverse.data) !== JSON.stringify(params.data)
-  let contextChanged =
-    JSON.stringify(weaverse.dataContext ?? null) !==
-    JSON.stringify(params.dataContext ?? null)
+  let dataChanged = !isSameLoaderPayload(weaverse.data, params.data)
+  let contextChanged = !isSameLoaderPayload(
+    weaverse.dataContext ?? null,
+    params.dataContext ?? null
+  )
 
   if (contextChanged) {
     // Assign before notifying any item store: components resolve data

package/src/utils/use-studio.ts

@@ -9,11 +9,6 @@ import {
 import { useTranslation } from '../hooks/translation-context'
 import type { WeaverseHydrogen } from '../index'
 import { hasWeaverseStudio } from '../types'
-import {
-  observeNavigation,
-  registerPixelInstance,
-  shouldFirePixel,
-} from './pixel'
 import { getStudioScriptSrc, resolveStudioScriptSrc } from './studio-script-src'
 import { useThemeSettingsStore } from './use-theme-settings-store'
 
@@ -133,36 +128,4 @@ export function useStudio(weaverse: WeaverseHydrogen) {
         .catch(console.error)
     }
   }, [pathname, search, navigation.state])
-  usePixel(weaverse)
-}
-
-export function usePixel(context: WeaverseHydrogen) {
-  let { projectId, pageId, isDesignMode, weaverseHost } = context
-  let { key: navigationKey } = useLocation()
-  // Observe every navigation so a persistent layout-level instance forgets
-  // the previous navigation's fired pages on a real key change — but NOT on
-  // an in-place remount that keeps the same history entry (e.g. the
-  // `data={null}` suppress/restore path), which must not double-count.
-  useEffect(() => {
-    if (!(projectId && pageId) || isDesignMode) {
-      return
-    }
-    observeNavigation(navigationKey)
-  }, [navigationKey, projectId, pageId, isDesignMode])
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: fire once on mount
-  useEffect(() => {
-    if (!(projectId && pageId) || isDesignMode) {
-      return
-    }
-    // Register BEFORE deciding to fire: the navigation state must live at
-    // least as long as some Weaverse instance is mounted (see pixel.ts).
-    let unregister = registerPixelInstance()
-    if (shouldFirePixel(navigationKey, pageId)) {
-      let img = new Image()
-      img.onload = () => img.remove()
-      img.src = `${weaverseHost}/api/public/px?projectId=${projectId}&pageId=${pageId}`
-    }
-    return unregister
-  }, [])
 }

package/dist/types/utils/pixel.d.ts

@@ -1,16 +0,0 @@
-/**
- * Record the navigation key seen by a mounted instance. A change of key is a
- * real navigation and forgets the previous navigation's fired pages; an
- * unchanged key (an in-place remount / suppress-restore on the same history
- * entry) leaves them intact, so the page is not double-counted.
- */
-export declare function observeNavigation(navigationKey: string): void;
-export declare function shouldFirePixel(navigationKey: string, pageId: string): boolean;
-/**
- * Track a mounted Weaverse instance; returns the unmount cleanup. When the
- * last instance unmounts, the navigation state is forgotten so a Back that
- * restores the same history entry counts again even if no instance survived
- * to observe the detour.
- */
-export declare function registerPixelInstance(): () => void;
-//# sourceMappingURL=pixel.d.ts.map

package/dist/types/utils/pixel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pixel.d.ts","sourceRoot":"","sources":["../../../src/utils/pixel.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAK7D;AAED,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,IAAI,CASlD"}

package/src/utils/pixel.ts

@@ -1,71 +0,0 @@
-// One pixel per page per navigation. A few facts shape the dedup:
-//
-// 1. Co-located instances: nested compositions mount multiple Weaverse
-//    instances on one URL; each page is counted at most once.
-// 2. The pixel FIRE effect runs once per instance mount (see `usePixel`), so
-//    an instance never re-fires on its own — a navigation is a fresh mount.
-// 3. `location.key` is stable per history entry. A back/forward POP restores
-//    the entry's ORIGINAL key, and an in-place remount on the same entry
-//    (e.g. the `data={null}` suppress/restore path in WeaverseHydrogenRoot)
-//    keeps that same key. A REAL navigation is therefore a key CHANGE.
-//
-// `firedPageIds` is the set of pages already counted for the current
-// navigation. It is forgotten in two ways:
-//   - On a key TRANSITION reported by ANY mounted instance via
-//     `observeNavigation` (driven by a per-navigation effect). A persistent
-//     layout-level instance keeps observing across a detour through a
-//     non-Weaverse route (cart, search, account), so a Back to the original
-//     entry is recognised as a new navigation and the page re-counts — while
-//     an in-place suppress/restore (no key change) does NOT re-count.
-//   - When the LAST instance unmounts (`registerPixelInstance`), covering the
-//     detour case where no instance survives to observe the key round-trip
-//     (a page with no persistent layout going to /cart and back).
-//
-// Known tradeoff: React StrictMode's dev-only mount→cleanup→mount cycle
-// resets state and double-fires in development — parity with the pre-dedupe
-// behavior; production semantics are unaffected.
-let currentNavigationKey: string | null = null
-let firedPageIds = new Set<string>()
-let mountedInstances = 0
-
-/**
- * Record the navigation key seen by a mounted instance. A change of key is a
- * real navigation and forgets the previous navigation's fired pages; an
- * unchanged key (an in-place remount / suppress-restore on the same history
- * entry) leaves them intact, so the page is not double-counted.
- */
-export function observeNavigation(navigationKey: string): void {
-  if (navigationKey !== currentNavigationKey) {
-    currentNavigationKey = navigationKey
-    firedPageIds.clear()
-  }
-}
-
-export function shouldFirePixel(
-  navigationKey: string,
-  pageId: string
-): boolean {
-  observeNavigation(navigationKey)
-  if (firedPageIds.has(pageId)) {
-    return false
-  }
-  firedPageIds.add(pageId)
-  return true
-}
-
-/**
- * Track a mounted Weaverse instance; returns the unmount cleanup. When the
- * last instance unmounts, the navigation state is forgotten so a Back that
- * restores the same history entry counts again even if no instance survived
- * to observe the detour.
- */
-export function registerPixelInstance(): () => void {
-  mountedInstances += 1
-  return () => {
-    mountedInstances -= 1
-    if (mountedInstances === 0) {
-      currentNavigationKey = null
-      firedPageIds.clear()
-    }
-  }
-}