@weaverse/hydrogen 5.17.1 → 5.19.0

package/src/utils/studio-script-src.ts

@@ -0,0 +1,162 @@
+/** Rendering mode and host details used to select a Studio bridge script. */
+export interface StudioMode {
+  /** Whether the storefront is running inside the visual editor. */
+  isDesignMode?: boolean
+  /** Whether a component preview is being rendered. */
+  isPreviewMode?: boolean
+  /** Whether a saved page revision is being previewed. */
+  isRevisionPreview?: boolean
+  /** Trusted origin serving Studio bridge assets. */
+  weaverseHost: string
+  /** Studio asset version appended to the script URL. */
+  weaverseVersion: string
+}
+
+const DEFAULT_WEAVERSE_HOST = 'https://studio.weaverse.io'
+
+/**
+ * Weaverse-controlled apex domains the Studio bridge may be served from
+ * (matched on the host itself and any subdomain).
+ */
+const TRUSTED_STUDIO_DOMAINS = ['weaverse.io', 'weaverse.dev']
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname === '127.0.0.1' ||
+    hostname.endsWith('.localhost')
+  )
+}
+
+export interface TrustedStudioHostOptions {
+  /**
+   * Also trust loopback hosts (`localhost` / `127.0.0.1` / `*.localhost`) over
+   * http or https.
+   *
+   * Only safe when the **storefront itself** is loopback (genuine local-builder
+   * dev). A production https page can still load a loopback script — loopback is
+   * a "potentially trustworthy" origin and is not blocked as mixed content — so
+   * honoring a query-supplied loopback host on a public storefront would let a
+   * crafted link run whatever a visitor's local service serves inside the
+   * storefront origin. MUST stay off on the server, where it is an SSRF vector
+   * for page/theme fetches.
+   */
+  allowLoopback?: boolean
+}
+
+/**
+ * Whether `host` is an origin we trust to serve the Studio bridge script (or,
+ * server-side, to resolve page/theme data).
+ *
+ * The bridge executes inside the storefront document and the host can drive
+ * server-side fetches, so a host taken from an attacker-controllable source —
+ * e.g. a crafted `?weaverseHost=` query — is both an XSS and an SSRF vector.
+ * Callers MUST reject untrusted hosts before acting on them. Trusts
+ * `weaverse.io`/`weaverse.dev` and their subdomains over https; loopback is
+ * opt-in (see {@link TrustedStudioHostOptions.allowLoopback}).
+ */
+export function isTrustedStudioHost(
+  host: string,
+  options?: TrustedStudioHostOptions
+): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(host)
+  } catch {
+    return false
+  }
+  let { hostname, protocol } = parsed
+  // Loopback (opt-in) is the only place http is allowed — a local builder
+  // serves the bridge over http and there is no cleartext-downgrade risk to a
+  // private address. Every other trusted host must be https so server-side
+  // page/theme fetches are never downgraded to cleartext.
+  if (options?.allowLoopback && isLoopbackHostname(hostname)) {
+    return protocol === 'http:' || protocol === 'https:'
+  }
+  if (protocol !== 'https:') {
+    return false
+  }
+  return TRUSTED_STUDIO_DOMAINS.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+  )
+}
+
+/**
+ * Build the Studio bridge script URL for the current mode, or `null` when the
+ * storefront is not being previewed inside Weaverse Studio.
+ *
+ * This is the single gate that keeps the bridge off production storefronts:
+ * a normal visitor's URL carries none of the design/preview markers, so the
+ * result is `null` and no script is ever requested.
+ *
+ * Shared by the page-scoped `useStudio` (which also binds the page for
+ * editing) and the root-level `useStudioConnect` (which only needs the script
+ * to load so Studio's `checkWeaversePage()` handshake can answer on routes
+ * with no Weaverse content).
+ */
+export function getStudioScriptSrc(mode: StudioMode): string | null {
+  let {
+    isDesignMode,
+    isPreviewMode,
+    isRevisionPreview,
+    weaverseHost,
+    weaverseVersion,
+  } = mode
+  let base = `${weaverseHost}/static/studio/hydrogen`
+  let version = `?v=${weaverseVersion}`
+  if (isRevisionPreview || isPreviewMode) {
+    return `${base}/preview.js${version}`
+  }
+  if (isDesignMode) {
+    return `${base}/index.js${version}`
+  }
+  return null
+}
+
+/**
+ * Resolve the Studio bridge script URL from a URL query string — the markers
+ * Studio attaches when it drives the preview iframe (`isDesignMode`,
+ * `isPreviewMode`, `__revisionId`, `weaverseHost`, `weaverseVersion`) — or
+ * `null` outside Studio.
+ *
+ * `storefrontHostname` is the document's own hostname: a loopback Studio host
+ * is only honored when the storefront itself is loopback (genuine local-builder
+ * dev), so a crafted public link can't load a script from a visitor's loopback
+ * service into the storefront origin.
+ *
+ * The `weaverseHost` query is attacker-controllable, so a host that is not a
+ * {@link isTrustedStudioHost trusted origin} resolves to `null` (no bridge) —
+ * it is never silently replaced with production Studio, which would otherwise
+ * inject the wrong bridge for self-hosted/staging deployments. Such deployments
+ * (a non-`weaverse.io` `WEAVERSE_HOST`) therefore don't load the root bridge on
+ * content-less routes; the page-scoped {@link getStudioScriptSrc} via
+ * `useStudio` still uses the configured host on content routes.
+ *
+ * Pure (no DOM) so the root-level connect's production gate stays unit-testable
+ * and needs no loader data.
+ */
+export function resolveStudioScriptSrc(
+  search: string,
+  storefrontHostname = ''
+): string | null {
+  let params = new URLSearchParams(search)
+  // Match the server's getRequestQueries(), which keeps the LAST value of a
+  // duplicated key. Studio appends its own control params, so a pre-existing
+  // (stale/untrusted) `weaverseHost` earlier in the URL must not win here, or
+  // the root bridge would be skipped while the loader uses the later host.
+  let last = (key: string) => params.getAll(key).at(-1)
+  let host = last('weaverseHost')
+  if (host) {
+    let allowLoopback = isLoopbackHostname(storefrontHostname)
+    if (!isTrustedStudioHost(host, { allowLoopback })) {
+      return null
+    }
+  }
+  return getStudioScriptSrc({
+    isDesignMode: last('isDesignMode') === 'true',
+    isPreviewMode: last('isPreviewMode') === 'true',
+    isRevisionPreview: params.has('__revisionId'),
+    weaverseHost: host || DEFAULT_WEAVERSE_HOST,
+    weaverseVersion: last('weaverseVersion') || '',
+  })
+}

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

@@ -0,0 +1,57 @@
+import type { WeaverseHydrogenParams } from '../types'
+import type { WeaverseHydrogen } from '../WeaverseHydrogenRoot'
+
+/**
+ * Apply a fresh loader payload to a reused Weaverse instance.
+ *
+ * With requestInfo normalized to the browser URL, same-URL revalidations
+ * (cart mutations, `useRevalidator()`, locale-neutral re-fetches) reuse the
+ * cached `window.__weaverses[pageId]` instance instead of constructing a new
+ * one — which preserves section state, but would silently drop the fresh
+ * `data`/`dataContext` the loaders just returned. Sync them here.
+ *
+ * Design mode is excluded by the caller: Studio owns the instance data there
+ * (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.
+ */
+export function syncReusedInstance(
+  weaverse: WeaverseHydrogen,
+  params: WeaverseHydrogenParams
+) {
+  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)
+
+  if (contextChanged) {
+    // Assign before notifying any item store: components resolve data
+    // connectors against `weaverse.dataContext` at render time, so the
+    // fresh context must be in place when re-renders flush.
+    weaverse.dataContext = params.dataContext ?? null
+  }
+  if (dataChanged) {
+    // State-preserving: existing item stores receive `setData` (and emit),
+    // missing ones are created — no full instance teardown.
+    weaverse.setProjectData(params.data)
+  } else if (contextChanged) {
+    // Context-only change: memoized item components subscribe to their item
+    // store snapshot, and snapshot identity follows the `_store` reference —
+    // a bare `triggerUpdate()` would notify with an identical snapshot and
+    // `useSyncExternalStore` would skip the re-render. `setData({})` swaps
+    // the store reference so connectors re-resolve against the new context.
+    for (const { id } of params.data?.items || []) {
+      weaverse.itemInstances.get(id)?.setData({})
+    }
+  }
+  if (dataChanged || contextChanged) {
+    weaverse.triggerUpdate()
+  }
+}

package/src/utils/theme-text-store.ts

@@ -0,0 +1 @@
+export { ThemeTextStore, TranslationStore } from './translation-store'

package/src/utils/translation-store.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal mutable store for design-mode static text overrides.
+ *
+ * useSyncExternalStore-compatible. Passed into TranslationProvider which
+ * subscribes internally and merges overrides into merchantOverrides.
+ * The studio bridge calls updateOverrides() via weaverse.internal.translationStore
+ * (also exposed as the deprecated weaverse.internal.themeTextStore alias).
+ *
+ * Shape: flat Record<string, string> — dot-notation keys map to values
+ * (e.g. "cart.title" → "Shopping Cart").
+ */
+export class TranslationStore {
+  /** Current flat translation overrides keyed by dot-path. */
+  overrides: Record<string, string> = {}
+  private listeners: Set<() => void> = new Set()
+
+  /** Replaces all overrides and notifies subscribers. */
+  setOverrides = (overrides: Record<string, string>) => {
+    this.overrides = { ...overrides }
+    this.emit()
+  }
+
+  /** Merges changed overrides and notifies subscribers. */
+  updateOverrides = (newOverrides: Record<string, string>) => {
+    this.overrides = { ...this.overrides, ...newOverrides }
+    this.emit()
+  }
+
+  /** Returns the current client snapshot for `useSyncExternalStore`. */
+  getSnapshot = () => this.overrides
+
+  /** Returns the current server snapshot for `useSyncExternalStore`. */
+  getServerSnapshot = () => this.overrides
+
+  /** Subscribes to override changes and returns an unsubscribe callback. */
+  subscribe = (callback: () => void) => {
+    this.listeners.add(callback)
+    return () => {
+      this.listeners.delete(callback)
+    }
+  }
+
+  private emit = () => {
+    for (const listener of Array.from(this.listeners)) {
+      try {
+        listener()
+      } catch (error) {
+        console.error('TranslationStore: Listener error', error)
+      }
+    }
+  }
+}
+
+/**
+ * Legacy constructor alias retained for existing theme text integrations.
+ * @deprecated Use {@link TranslationStore} instead. This alias remains available
+ * for backward compatibility.
+ */
+export const ThemeTextStore = TranslationStore
+/**
+ * Legacy type alias retained for existing theme text integrations.
+ * @deprecated Use {@link TranslationStore} instead. This alias remains available
+ * for backward compatibility.
+ */
+export type ThemeTextStore = TranslationStore

package/src/utils/use-studio.ts

@@ -0,0 +1,168 @@
+import { loadScript } from '@weaverse/react'
+import { useEffect } from 'react'
+import {
+  useLocation,
+  useNavigate,
+  useNavigation,
+  useRevalidator,
+} from 'react-router'
+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'
+
+const STUDIO_READY_POLL_MS = 50
+const STUDIO_READY_TIMEOUT_MS = 5000
+
+/**
+ * Resolve once `window.weaverseStudio` is available, or `null` on timeout.
+ * The studio script sets the global when it *executes*; `loadScript` can
+ * resolve earlier for tags it did not create (e.g. SSR-injected markup),
+ * so never assume readiness right after the script promise settles.
+ */
+function waitForStudio(): Promise<Window['weaverseStudio'] | null> {
+  return new Promise((resolve) => {
+    let startedAt = Date.now()
+    function check() {
+      if (hasWeaverseStudio(window)) {
+        return resolve(window.weaverseStudio)
+      }
+      if (Date.now() - startedAt >= STUDIO_READY_TIMEOUT_MS) {
+        console.warn('[Weaverse] Studio script did not initialize in time')
+        return resolve(null)
+      }
+      setTimeout(check, STUDIO_READY_POLL_MS)
+    }
+    check()
+  })
+}
+
+/**
+ * Load the Studio bridge script on every design/preview render so Studio's
+ * `checkWeaversePage()` handshake is answered instead of timing out — crucially
+ * on routes where the page-scoped {@link useStudio} never mounts: 404s, error
+ * boundaries, and non-Weaverse routes. The bridge registers its RPC endpoint
+ * and `window.weaverseStudio` the moment the script executes, independent of any
+ * page binding. Without this, a content-less route never loads the script and
+ * Studio reports a false "Connection lost" instead of "this page has no Weaverse
+ * content set up".
+ *
+ * `loadScript` is idempotent, so on content routes this coexists with the
+ * page-scoped {@link useStudio} (same src) — that hook still binds the page via
+ * `init`. Gating this on whether a route "has Weaverse data" is deliberately
+ * avoided: route matches can't tell whether the page-scoped bridge actually
+ * mounts (an `ErrorBoundary` replacing a data route, or data passed via the
+ * `data` prop), and suppressing the script there would reintroduce the timeout
+ * this fixes. Loading the script is harmless; it only registers the responder.
+ *
+ * Known limitation: on a route whose `weaverseData` is a deferred Promise, the
+ * script can load before the page streams in, so `checkWeaversePage()` may
+ * briefly observe `NOT_WEAVERSE_PAGE`. The complete fix is a "loading" state in
+ * `checkWeaversePage` so the handshake retries rather than latching — that lives
+ * in the Studio script, not here. Tracked in Weaverse/builder#2515.
+ *
+ * Mounted via {@link withWeaverse}, which must be the root route's `Layout`
+ * export so the bridge renders even when a route's `ErrorBoundary` replaces the
+ * page. Outside Studio (no design/preview params) it is a no-op.
+ */
+export function useStudioConnect() {
+  let { search } = useLocation()
+  useEffect(() => {
+    // Loopback Studio hosts are only honored when the storefront itself is
+    // loopback (see resolveStudioScriptSrc), so pass the document's hostname.
+    let hostname = typeof window === 'undefined' ? '' : window.location.hostname
+    let src = resolveStudioScriptSrc(search, hostname)
+    if (src) {
+      loadScript(src).catch(console.error)
+    }
+  }, [search])
+}
+
+export function useStudio(weaverse: WeaverseHydrogen) {
+  let { revalidate } = useRevalidator()
+  let navigation = useNavigation()
+  let { pathname, search } = useLocation()
+  let navigate = useNavigate()
+  let themeSettingsStore = useThemeSettingsStore()
+  let { translationStore, themeTextStore, merchantOverrides } = useTranslation()
+  let {
+    isDesignMode,
+    weaverseHost,
+    weaverseVersion,
+    isPreviewMode,
+    isRevisionPreview,
+  } = weaverse
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: only revalidate on pathname/search changes
+  useEffect(() => {
+    if (navigation.state !== 'idle') {
+      return
+    }
+    let src = getStudioScriptSrc({
+      isDesignMode,
+      isPreviewMode,
+      isRevisionPreview,
+      weaverseHost,
+      weaverseVersion,
+    })
+    if (!src) {
+      return
+    }
+    if (isRevisionPreview || isPreviewMode) {
+      loadScript(src).catch(console.error)
+    } else {
+      weaverse.internal = {
+        ...weaverse.internal,
+        navigate,
+        revalidate,
+        merchantOverrides,
+        themeSettingsStore,
+        translationStore,
+        // Deprecated alias for existing Studio bridge integrations.
+        themeTextStore,
+      }
+      loadScript(src)
+        .then(waitForStudio)
+        .then((studio) => studio?.init(weaverse))
+        .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/src/utils/use-theme-settings-store.ts

@@ -0,0 +1,160 @@
+import { isBrowser } from '@weaverse/react'
+import { createContext, useContext, useEffect, useRef } from 'react'
+import { useRouteLoaderData } from 'react-router'
+import type {
+  HydrogenThemeSchema,
+  HydrogenThemeSettings,
+  PublicEnv,
+} from '../types'
+
+/** Root-loader theme data used to initialize a {@link ThemeSettingsStore}. */
+export interface WeaverseThemeData {
+  /** Storefront-safe environment values, when available. */
+  publicEnv?: PublicEnv
+  /** Theme schema exposed to Studio, when available. */
+  schema?: HydrogenThemeSchema
+  /** Published theme setting values. */
+  theme: HydrogenThemeSettings
+}
+
+/** Mutable, subscribable store for theme settings received from the root loader. */
+export class ThemeSettingsStore {
+  /** Current merged theme setting values. */
+  settings: HydrogenThemeSettings = {}
+  /** Theme schema exposed to Studio, when available. */
+  schema?: HydrogenThemeSchema
+  /** Storefront-safe environment values, when available. */
+  publicEnv?: PublicEnv
+  private listeners: Set<() => void> = new Set()
+  private hasWarnedListenerCount = false
+  private isDestroyed = false
+
+  /** Creates a theme settings store from root-loader theme data. */
+  constructor(data: WeaverseThemeData) {
+    const { theme, schema, publicEnv } = data || {}
+    this.settings = { ...theme }
+    this.schema = schema
+    this.publicEnv = publicEnv
+    if (isBrowser) {
+      window.__weaverseThemeSettingsStore = this
+    }
+  }
+
+  /** Merges setting changes into the current snapshot and notifies subscribers. */
+  updateThemeSettings = (newSettings: HydrogenThemeSettings) => {
+    if (this.isDestroyed) {
+      console.warn('ThemeSettingsStore: Cannot update destroyed store')
+      return
+    }
+
+    this.settings = {
+      ...this.settings,
+      ...newSettings,
+    }
+    this.emit()
+  }
+
+  /** Returns the current client snapshot for `useSyncExternalStore`. */
+  getSnapshot = () => this.settings
+
+  /** Returns the current server snapshot for `useSyncExternalStore`. */
+  getServerSnapshot = () => this.settings
+
+  /** Subscribes to setting changes and returns an unsubscribe callback. */
+  subscribe = (callback: () => void) => {
+    if (this.isDestroyed) {
+      console.warn('ThemeSettingsStore: Cannot subscribe to destroyed store')
+      return () => {}
+    }
+
+    this.listeners.add(callback)
+
+    if (!this.hasWarnedListenerCount && this.listeners.size > 500) {
+      this.hasWarnedListenerCount = true
+      console.warn(
+        `ThemeSettingsStore: ${this.listeners.size} listeners detected. ` +
+          'This may indicate a performance issue. Consider using fewer useThemeSettings() calls.'
+      )
+    }
+
+    return () => {
+      this.listeners.delete(callback)
+    }
+  }
+
+  private emit = () => {
+    if (this.isDestroyed) {
+      return
+    }
+
+    const currentListeners = Array.from(this.listeners)
+
+    for (const listener of currentListeners) {
+      try {
+        listener()
+      } catch (error) {
+        console.error('ThemeSettingsStore: Listener error', error)
+      }
+    }
+  }
+
+  /** Clears subscribers and detaches the browser-global store reference. */
+  destroy = () => {
+    if (this.isDestroyed) {
+      return
+    }
+
+    this.listeners.clear()
+    this.isDestroyed = true
+
+    if (isBrowser && window.__weaverseThemeSettingsStore === this) {
+      window.__weaverseThemeSettingsStore = undefined
+    }
+  }
+}
+
+export const ThemeSettingsStoreContext =
+  createContext<ThemeSettingsStore | null>(null)
+ThemeSettingsStoreContext.displayName = 'ThemeSettingsStoreContext'
+
+export function useCreateThemeSettingsStore(): ThemeSettingsStore {
+  const data = useRouteLoaderData('root') as {
+    weaverseTheme: WeaverseThemeData
+  }
+  const storeRef = useRef<ThemeSettingsStore | null>(null)
+
+  if (!storeRef.current) {
+    storeRef.current = new ThemeSettingsStore(data?.weaverseTheme)
+  }
+
+  const theme = data?.weaverseTheme?.theme
+  useEffect(() => {
+    if (storeRef.current && theme) {
+      storeRef.current.updateThemeSettings(theme)
+    }
+  }, [theme])
+
+  return storeRef.current
+}
+
+export function useThemeSettingsStore(): ThemeSettingsStore {
+  const fromContext = useContext(ThemeSettingsStoreContext)
+  const data = useRouteLoaderData('root') as {
+    weaverseTheme: WeaverseThemeData
+  }
+  const fallbackRef = useRef<ThemeSettingsStore | null>(null)
+
+  if (!(fallbackRef.current || fromContext)) {
+    fallbackRef.current = new ThemeSettingsStore(data?.weaverseTheme)
+  }
+
+  const store = fromContext ?? fallbackRef.current!
+  const theme = data?.weaverseTheme?.theme
+  useEffect(() => {
+    if (!fromContext && theme) {
+      store.updateThemeSettings(theme)
+    }
+  }, [fromContext, store, theme])
+
+  return store
+}