@weaverse/hydrogen 6.1.2 → 6.2.0

package/src/next/server.ts

@@ -0,0 +1,67 @@
+/**
+ * Server-only Weaverse APIs for Next.js App Router server components and route
+ * handlers.
+ *
+ * When migrating from Hydrogen's `context.weaverse`, create a request-scoped
+ * client with {@link createWeaverseNextServerClient}, then call `loadPage()` or
+ * `loadThemeSettings()`. Keep rendering providers and components imported from
+ * the root `@weaverse/hydrogen/next` entrypoint.
+ *
+ * @packageDocumentation
+ */
+
+export type { WeaverseNextRevalidateRouteContext } from './revalidate-item'
+export {
+  formatWeaverseNextSeoMetadata,
+  getWeaverseNextSeoMetadata,
+  type NextOpenGraph,
+  type NextTwitter,
+  type WeaverseNextSeoInput,
+  type WeaverseNextSeoMetadata,
+  type WeaverseNextSeoPageContainer,
+} from './seo'
+export {
+  getWeaverseNextConfigs,
+  type ResolveConfigsOptions,
+} from './server/configs'
+export {
+  normalizeNextPageUrl,
+  resolveRequestUrl,
+} from './server/normalize-page-url'
+export {
+  createWeaverseNextRevalidateHandler,
+  type WeaverseNextRevalidateHandler,
+  type WeaverseNextRevalidateHandlerConfig,
+  type WeaverseNextRevalidateRequestBody,
+} from './server/revalidate-handler'
+export { createWeaverseNextServerClient } from './server/server-client'
+export type {
+  WeaverseNextBaseConfigs,
+  WeaverseNextCacheConfig,
+  WeaverseNextClient,
+  WeaverseNextCommerceContext,
+  WeaverseNextComponent,
+  WeaverseNextComponentData,
+  WeaverseNextComponentLoaderArgs,
+  WeaverseNextComponentProps,
+  WeaverseNextConfigs,
+  WeaverseNextCustomPageEntry,
+  WeaverseNextFetchCustomPagesOptions,
+  WeaverseNextFetchOptions,
+  WeaverseNextI18n,
+  WeaverseNextLoaderData,
+  WeaverseNextLoadPageInput,
+  WeaverseNextPageAssignment,
+  WeaverseNextPageData,
+  WeaverseNextProjectId,
+  WeaverseNextRequestContext,
+  WeaverseNextServerClient,
+  WeaverseNextServerClientConfig,
+  WeaverseNextServerLoadPageInput,
+  WeaverseNextStorefront,
+  WeaverseNextThemeSchema,
+  WeaverseNextThemeSchemaGroup,
+  WeaverseNextThemeSchemaInput,
+  WeaverseNextThemeSettingsOptions,
+  WeaverseNextThemeSettingsResponse,
+} from './types'

package/src/next/studio-bridge.tsx

@@ -0,0 +1,82 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import {
+  bindWeaverseNextStudioRuntime,
+  type WeaverseNextRuntime,
+} from './runtime'
+import type { WeaverseNextRuntimeInternal } from './types'
+
+const STUDIO_BIND_RETRY_INTERVAL_MS = 50
+const STUDIO_BIND_MAX_ATTEMPTS = 100
+
+/** Runtime and host callbacks attached to the Builder Studio bridge. */
+export interface WeaverseNextStudioBridgeProps {
+  /** Preview navigation callback. */
+  navigate?: WeaverseNextRuntimeInternal['navigate']
+  /** Whole-route refresh callback used as a legacy fallback. */
+  revalidate?: WeaverseNextRuntimeInternal['revalidate']
+  /** Preferred per-item loader revalidation callback. */
+  revalidateItem?: WeaverseNextRuntimeInternal['revalidateItem']
+  /** Browser runtime to initialize or refresh in Studio. */
+  runtime: WeaverseNextRuntime
+}
+
+/** Page-level Studio runtime binder. */
+export function WeaverseNextStudioBridge(props: WeaverseNextStudioBridgeProps) {
+  let { runtime, navigate, revalidate, revalidateItem } = props
+  let lastRuntimeRef = useRef(runtime)
+  let lastRuntimeDataRef = useRef(runtime.data)
+  let lastRequestInfoRef = useRef(runtime.requestInfo)
+
+  useEffect(() => {
+    if (navigate) {
+      runtime.internal.navigate = navigate
+    }
+    if (revalidate) {
+      runtime.internal.revalidate = revalidate
+    }
+    if (revalidateItem) {
+      runtime.internal.revalidateItem = revalidateItem
+    }
+
+    if (bindWeaverseNextStudioRuntime(runtime) || !runtime.isDesignMode) {
+      return
+    }
+
+    let attempts = 0
+    let interval = window.setInterval(() => {
+      attempts += 1
+      if (
+        bindWeaverseNextStudioRuntime(runtime) ||
+        attempts >= STUDIO_BIND_MAX_ATTEMPTS
+      ) {
+        window.clearInterval(interval)
+      }
+    }, STUDIO_BIND_RETRY_INTERVAL_MS)
+
+    return () => window.clearInterval(interval)
+  }, [runtime, navigate, revalidate, revalidateItem])
+
+  useEffect(() => {
+    if (lastRuntimeRef.current !== runtime) {
+      lastRuntimeRef.current = runtime
+      lastRuntimeDataRef.current = runtime.data
+      lastRequestInfoRef.current = runtime.requestInfo
+      return
+    }
+
+    if (
+      lastRuntimeDataRef.current === runtime.data &&
+      lastRequestInfoRef.current === runtime.requestInfo
+    ) {
+      return
+    }
+
+    lastRuntimeDataRef.current = runtime.data
+    lastRequestInfoRef.current = runtime.requestInfo
+    bindWeaverseNextStudioRuntime(runtime)
+  }, [runtime, runtime.data, runtime.requestInfo])
+
+  return null
+}

package/src/next/studio-connect.tsx

@@ -0,0 +1,88 @@
+'use client'
+
+import { useEffect } from 'react'
+import { resolveWeaverseNextStudioScriptSrc } from './studio-script-src'
+import type { WeaverseNextRequestContext } from './types'
+
+const loadedScriptSrcs = new Set<string>()
+
+function loadScript(src: string) {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  if (loadedScriptSrcs.has(src)) {
+    return
+  }
+
+  let existing = document.querySelector(`script[src="${src}"]`)
+  if (existing) {
+    loadedScriptSrcs.add(src)
+    return
+  }
+
+  let script = document.createElement('script')
+  script.async = true
+  script.src = src
+  document.head.appendChild(script)
+  loadedScriptSrcs.add(src)
+}
+
+/** Trust context used while loading the Studio bridge script. */
+export interface LoadWeaverseNextStudioScriptOptions {
+  /** Storefront hostname; required to permit loopback Studio origins. */
+  storefrontHostname?: string
+}
+
+/**
+ * Resolve and append the Next Studio bridge script for the given request
+ * context, deduping by src. SSR-safe (no-op without `document`) so it can run
+ * unconditionally from a root layout/error boundary before any page tree or
+ * runtime exists — e.g. App Router `not-found.tsx` / `error.tsx` routes.
+ */
+export function loadWeaverseNextStudioScript(
+  context?: WeaverseNextRequestContext,
+  options: LoadWeaverseNextStudioScriptOptions = {}
+) {
+  let resolvedContext = context
+  if (!resolvedContext && typeof window !== 'undefined') {
+    resolvedContext = {
+      searchParams: new URLSearchParams(window.location.search),
+      url: window.location.href,
+    }
+  }
+
+  let src = resolveWeaverseNextStudioScriptSrc(resolvedContext, {
+    storefrontHostname:
+      options.storefrontHostname ??
+      (typeof window === 'undefined' ? undefined : window.location.hostname),
+  })
+  if (src) {
+    loadScript(src)
+  }
+}
+
+/** Props for the root-level Studio script connector. */
+export interface WeaverseNextStudioConnectProps {
+  /** Explicit request context used to resolve Studio mode and host. */
+  context?: WeaverseNextRequestContext
+  /** Storefront hostname; required to permit loopback Studio origins. */
+  storefrontHostname?: string
+}
+
+/**
+ * Root-level Studio script connector for Next client boundaries. Mount once
+ * near the app root (e.g. root layout) so it also covers routes that never
+ * render `WeaverseNextRenderer`, such as `not-found.tsx` / `error.tsx`.
+ */
+export function WeaverseNextStudioConnect(
+  props: WeaverseNextStudioConnectProps
+) {
+  useEffect(() => {
+    loadWeaverseNextStudioScript(props.context, {
+      storefrontHostname: props.storefrontHostname,
+    })
+  }, [props.context, props.storefrontHostname])
+
+  return null
+}

package/src/next/studio-router.ts

@@ -0,0 +1,85 @@
+import type { WeaverseNextRuntimeInternal } from './types'
+
+/**
+ * Minimal structural shape of the Next App Router returned by `useRouter()`
+ * (`next/navigation`) that the Studio bridge needs. Declared locally — rather
+ * than importing `AppRouterInstance` from `next` — so the adapter stays a pure
+ * function that unit tests can drive with a plain mock and never pulls
+ * `next/navigation` into the test graph.
+ */
+export interface WeaverseNextRouterLike {
+  /** Add a route to browser history. */
+  push: (
+    href: string,
+    options?: {
+      /** Whether to scroll to the top after navigation. */
+      scroll?: boolean
+    }
+  ) => void
+  /** Refresh the current App Router route and server data. */
+  refresh: () => void
+  /** Replace the current browser-history entry. */
+  replace: (
+    href: string,
+    options?: {
+      /** Whether to scroll to the top after navigation. */
+      scroll?: boolean
+    }
+  ) => void
+}
+
+/** Resolved Studio navigation/revalidation callbacks for a Next runtime. */
+export interface WeaverseNextStudioInternals {
+  /** Navigate Studio's preview with React Router-compatible options. */
+  navigate: NonNullable<WeaverseNextRuntimeInternal['navigate']>
+  /** Refresh the current App Router route. */
+  revalidate: NonNullable<WeaverseNextRuntimeInternal['revalidate']>
+}
+
+/** Controls how Studio navigation maps to the Next App Router. */
+export interface CreateWeaverseNextStudioInternalsOptions {
+  /** Use `router.replace` instead of `router.push` for navigation. */
+  replace?: boolean
+}
+
+function shouldResetScroll(
+  options?: { preventScrollReset?: boolean } | Record<string, unknown>
+): boolean {
+  if (!options || typeof options !== 'object') {
+    return true
+  }
+  return !(options as { preventScrollReset?: boolean }).preventScrollReset
+}
+
+/**
+ * Build Studio `navigate` / `revalidate` callbacks from a Next App Router.
+ *
+ * Maps Hydrogen's React Router semantics onto Next App Router:
+ * - `navigate(to, { preventScrollReset })` → `router.push(to, { scroll })`,
+ *   where `scroll` is the inverse of `preventScrollReset`. Studio passes
+ *   `preventScrollReset` for in-place edits so the preview viewport is kept,
+ *   matching React Router's `navigate({ preventScrollReset })`.
+ * - `revalidate()` → `router.refresh()`, the App Router's loader-backed refresh
+ *   and the closest equivalent to React Router's `useRevalidator`.
+ *
+ * Pure (no React, no `next/navigation`) so it is unit-testable with a mock
+ * router; the {@link WeaverseNextRouterLike} contract is the only coupling.
+ */
+export function createWeaverseNextStudioInternals(
+  router: WeaverseNextRouterLike,
+  options: CreateWeaverseNextStudioInternalsOptions = {}
+): WeaverseNextStudioInternals {
+  return {
+    navigate: (to, navigateOptions) => {
+      let scroll = shouldResetScroll(navigateOptions)
+      if (options.replace) {
+        router.replace(to, { scroll })
+      } else {
+        router.push(to, { scroll })
+      }
+    },
+    revalidate: () => {
+      router.refresh()
+    },
+  }
+}

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

@@ -0,0 +1,128 @@
+import type { WeaverseNextRequestContext } from './types'
+
+/**
+ * Weaverse-controlled apex domains the Studio bridge may be served from
+ * (matched on the host itself and any subdomain), mirroring Hydrogen's
+ * `TRUSTED_STUDIO_DOMAINS`.
+ */
+const TRUSTED_STUDIO_DOMAINS = ['weaverse.io', 'weaverse.dev']
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname === '127.0.0.1' ||
+    hostname.endsWith('.localhost')
+  )
+}
+
+function normalizeOrigin(value: string | null): string | null {
+  if (!value) {
+    return null
+  }
+
+  try {
+    return new URL(value).origin
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether `origin` is one we trust to serve the Studio bridge script. Matches
+ * Hydrogen's `isTrustedStudioHost`: trusts `weaverse.io` / `weaverse.dev` and
+ * their subdomains over https, plus loopback (`localhost` / `*.localhost` /
+ * `127.0.0.1`) — but only when the storefront itself is loopback (genuine
+ * local-builder dev). Loopback is the only place http is allowed; every other
+ * trusted host must be https. Arbitrary origins are rejected.
+ */
+function isTrustedStudioOrigin(
+  origin: string,
+  storefrontHostname: string
+): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(origin)
+  } catch {
+    return false
+  }
+
+  let { hostname, protocol } = parsed
+  if (isLoopbackHostname(storefrontHostname) && isLoopbackHostname(hostname)) {
+    return protocol === 'http:' || protocol === 'https:'
+  }
+
+  if (protocol !== 'https:') {
+    return false
+  }
+
+  return TRUSTED_STUDIO_DOMAINS.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+  )
+}
+
+function toSearchParams(context?: WeaverseNextRequestContext): URLSearchParams {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams)
+  }
+
+  if (context?.url) {
+    let url =
+      typeof context.url === 'string'
+        ? new URL(context.url, 'http://localhost')
+        : context.url
+    return new URLSearchParams(url.searchParams)
+  }
+
+  return new URLSearchParams()
+}
+
+function last(searchParams: URLSearchParams, key: string): string | null {
+  let values = searchParams.getAll(key)
+  return values.length ? (values.at(-1) ?? null) : null
+}
+
+/** Trust context used when resolving a Studio bridge script URL. */
+export interface ResolveWeaverseNextStudioScriptSrcOptions {
+  /** Storefront hostname; required to permit loopback Studio origins. */
+  storefrontHostname?: string
+}
+
+/**
+ * Resolve the Studio script URL from request/search context. `@weaverse/hydrogen/next`
+ * uses the dedicated Next bridge path served by Builder.
+ */
+export function resolveWeaverseNextStudioScriptSrc(
+  context?: WeaverseNextRequestContext,
+  options: ResolveWeaverseNextStudioScriptSrcOptions = {}
+): string | null {
+  let searchParams = toSearchParams(context)
+
+  let isDesignMode =
+    context?.isDesignMode ?? last(searchParams, 'isDesignMode') === 'true'
+  let isPreviewMode =
+    context?.isPreviewMode ?? last(searchParams, 'isPreviewMode') === 'true'
+  let isRevisionPreview =
+    context?.isRevisionPreview ?? Boolean(last(searchParams, '__revisionId'))
+
+  if (!(isDesignMode || isPreviewMode || isRevisionPreview)) {
+    return null
+  }
+
+  let origin = normalizeOrigin(last(searchParams, 'weaverseHost'))
+  if (!origin) {
+    return null
+  }
+
+  let storefrontHostname = options.storefrontHostname ?? ''
+  if (!isTrustedStudioOrigin(origin, storefrontHostname)) {
+    return null
+  }
+
+  // Builder section-preview URLs carry both isDesignMode and isPreviewMode;
+  // the preview iframe waits for `preview-size`, which only preview.js emits,
+  // so preview/revision mode takes precedence (matching Hydrogen).
+  let bundle = isPreviewMode || isRevisionPreview ? 'preview.js' : 'index.js'
+  let version = last(searchParams, 'weaverseVersion')
+  let url = `${origin}/static/studio/next/${bundle}`
+  return version ? `${url}?v=${encodeURIComponent(version)}` : url
+}

package/src/next/theme-settings-store.ts

@@ -0,0 +1,47 @@
+import type { SchemaType } from '@weaverse/schema'
+import type {
+  WeaverseNextThemeSchema,
+  WeaverseNextThemeSettingsStore,
+} from './types'
+
+/** Initial values for a root-scoped theme-settings store. */
+export interface CreateWeaverseNextThemeSettingsStoreOptions {
+  /** Public environment values exposed alongside the store. */
+  publicEnv?: Record<string, string | undefined>
+  /** Theme schema associated with the settings. */
+  schema?: SchemaType | WeaverseNextThemeSchema
+  /** Initial setting values. */
+  settings?: Record<string, unknown>
+}
+
+/**
+ * Small external store shape compatible with the Studio bridge and React's
+ * `useSyncExternalStore` contract. The bridge calls `updateThemeSettings` during
+ * live theme edits, so keep that method name stable.
+ */
+export function createWeaverseNextThemeSettingsStore(
+  options: CreateWeaverseNextThemeSettingsStoreOptions = {}
+): WeaverseNextThemeSettingsStore {
+  let listeners = new Set<() => void>()
+  let store: WeaverseNextThemeSettingsStore = {
+    publicEnv: options.publicEnv,
+    schema: options.schema,
+    settings: { ...(options.settings ?? {}) },
+    getServerSnapshot: () => store.settings,
+    getSnapshot: () => store.settings,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    updateThemeSettings: (next: Record<string, unknown>) => {
+      store.settings = { ...store.settings, ...next }
+      for (let listener of listeners) {
+        listener()
+      }
+    },
+  }
+
+  return store
+}

package/src/next/translation-context.tsx

@@ -0,0 +1,182 @@
+'use client'
+
+import { useSafeExternalStore } from '@weaverse/react'
+import { createContext, type ReactNode, useContext, useMemo } from 'react'
+import { createTranslate, type TranslateFunction } from '../utils/translate'
+import type { TranslationStore } from '../utils/translation-store'
+
+// ---------------------------------------------------------------------------
+// Context & Provider
+// ---------------------------------------------------------------------------
+
+/** Translation function and live override stores exposed by `useTranslation`. */
+export interface TranslationValue {
+  /** Active-locale translated keys loaded from the storefront API. */
+  merchantOverrides: Record<string, unknown> | null
+  /**
+   * Translate a key with optional variable interpolation.
+   *
+   * Priority chain (highest wins):
+   * 1. External `t`        (passed into `WeaverseNextRootProvider` / `TranslationProvider`)
+   * 2. Design overrides   (live Builder edits from `TranslationStore`)
+   * 3. `merchantOverrides` (DB/API overrides for the current locale)
+   * 4. `staticContent`     (theme default JSON)
+   * 5. The key itself      (fallback)
+   *
+   * @example
+   * t('cart.title')                           // => "Cart"
+   * t('badge.sale', { percentage: 15 })       // => "-15% Off"
+   */
+  t: TranslateFunction
+  /**
+   * Legacy name for the live design-mode translation store.
+   *
+   * @deprecated Migrate to {@link TranslationValue.translationStore}. This
+   * alias points at the same store instance.
+   */
+  themeTextStore: TranslationStore | null
+  /** Exposed so the runtime/Studio bridge can attach it to `internal`. */
+  translationStore: TranslationStore | null
+}
+
+const TranslationContext = createContext<TranslationValue | null>(null)
+TranslationContext.displayName = 'WeaverseNextTranslationContext'
+
+/** Sources and content rendered by {@link TranslationProvider}. */
+export interface TranslationProviderProps {
+  /** React subtree that can call `useTranslation`. */
+  children: ReactNode
+  /** Active-locale static-text overrides loaded from Weaverse. */
+  merchantOverrides?: Record<string, unknown>
+  /** Default-locale static content from the theme schema. */
+  staticContent: Record<string, unknown>
+  /**
+   * Optional external translation function.
+   * When provided it becomes the **highest-priority** source:
+   * if it returns a non-empty string that differs from the raw key,
+   * that value is used; otherwise the internal resolution chain continues.
+   */
+  t?: TranslateFunction
+  /**
+   * Legacy prop name for the live translation store.
+   *
+   * @deprecated Migrate to {@link TranslationProviderProps.translationStore}.
+   * Still accepted for backward compatibility; ignored when `translationStore`
+   * is also provided.
+   */
+  themeTextStore?: TranslationStore | null
+  /** Optional store for live design-mode text overrides from the builder. */
+  translationStore?: TranslationStore | null
+}
+
+// No-op fallback for useSafeExternalStore when store is null (production).
+// Module-level constants — stable references, zero allocation per render.
+const EMPTY: Record<string, string> = {}
+const NOOP_SUBSCRIBE = () => () => {
+  // No-op unsubscribe for production/static renders without a translation store.
+}
+const NOOP_SNAPSHOT = () => EMPTY
+
+/**
+ * Provider that wraps the app to expose the `t()` function.
+ *
+ * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
+ * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `translationStore`   – optional store for live design-mode text overrides
+ *   (the deprecated `themeTextStore` prop is accepted as a fallback)
+ */
+export function TranslationProvider({
+  staticContent,
+  merchantOverrides,
+  t: externalT,
+  translationStore,
+  themeTextStore,
+  children,
+}: TranslationProviderProps) {
+  // Canonical store, falling back to the deprecated `themeTextStore` prop.
+  let store = translationStore ?? themeTextStore ?? null
+
+  // Subscribe to design-mode overrides. No-op when store is null (production).
+  let designOverrides = useSafeExternalStore(
+    store?.subscribe ?? NOOP_SUBSCRIBE,
+    store?.getSnapshot ?? NOOP_SNAPSHOT,
+    store?.getServerSnapshot ?? NOOP_SNAPSHOT
+  )
+
+  let value = useMemo<TranslationValue>(
+    () => ({
+      t: createTranslate({
+        staticContent,
+        merchantOverrides,
+        designOverrides,
+        externalT,
+      }),
+      translationStore: store,
+      // Deprecated alias — same instance, kept for backward compatibility.
+      themeTextStore: store,
+      merchantOverrides: merchantOverrides ?? null,
+    }),
+    [staticContent, merchantOverrides, designOverrides, externalT, store]
+  )
+
+  return (
+    <TranslationContext.Provider value={value}>
+      {children}
+    </TranslationContext.Provider>
+  )
+}
+
+/**
+ * Hook to access the translation `t()` function.
+ *
+ * Must be used inside a component wrapped by `WeaverseNextRootProvider` or
+ * `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   let { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+export function useTranslation(): TranslationValue {
+  let ctx = useContext(TranslationContext)
+  if (!ctx) {
+    throw new Error(
+      'useTranslation must be used within <TranslationProvider>. Wrap your app with <WeaverseNextRootProvider>.'
+    )
+  }
+  return ctx
+}
+
+// ---------------------------------------------------------------------------
+// Deprecated aliases (backward compatibility — kept exported indefinitely)
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy name for {@link TranslationProvider}.
+ *
+ * @deprecated Replace `ThemeTextProvider` with {@link TranslationProvider};
+ * the props and runtime behavior are unchanged.
+ */
+export const ThemeTextProvider = TranslationProvider
+/**
+ * Legacy name for {@link useTranslation}.
+ *
+ * @deprecated Replace `useThemeText` with {@link useTranslation}; the return
+ * value is unchanged.
+ */
+export const useThemeText = useTranslation
+/**
+ * Legacy name for {@link TranslationValue}.
+ *
+ * @deprecated Import {@link TranslationValue} instead.
+ */
+export type ThemeTextValue = TranslationValue
+/**
+ * Legacy name for {@link TranslationProviderProps}.
+ *
+ * @deprecated Import {@link TranslationProviderProps} instead.
+ */
+export type ThemeTextProviderProps = TranslationProviderProps