@weaverse/next 0.1.0-alpha.9 → 1.0.1

package/src/renderer.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+import { WeaverseRoot } from '@weaverse/react'
+import { memo, useContext, useEffect, useLayoutEffect, useMemo } from 'react'
+import type { JSX } from 'react/jsx-runtime'
+import { WeaverseNextContext } from './provider'
+import { createWeaverseNextRuntime } from './runtime'
+import type {
+  WeaverseNextClient,
+  WeaverseNextLoaderData,
+  WeaverseNextPageData,
+} from './types'
+import { WeaverseNextStudio } from './use-weaverse-next-studio'
+
+const EMPTY_DATA_CONTEXT: Record<string, unknown> = {}
+const useIsomorphicLayoutEffect =
+  typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+function getRenderablePage(
+  data: WeaverseNextLoaderData | null | undefined
+): (WeaverseNextPageData & { rootId: string }) | null {
+  let page = data?.page
+  if (!page) {
+    return null
+  }
+  let rootId =
+    page.rootId ??
+    page.items.find((item) => item.type === 'main')?.id ??
+    page.items[0]?.id ??
+    page.id
+  return { ...page, rootId }
+}
+
+/** Page payload, client, and connector data accepted by the Next renderer. */
+export interface WeaverseNextRendererProps {
+  /** Client to render from. Defaults to the provider's client. */
+  client?: WeaverseNextClient
+  /** Page payload to render. Defaults to `client.data`. */
+  data?: WeaverseNextLoaderData | null
+  /** Data-connector context for `{{...}}` template replacement. */
+  dataContext?: Record<string, unknown>
+}
+
+/**
+ * Render a serialized Weaverse page tree through `@weaverse/react` primitives.
+ *
+ * Reads the client/page data supplied by {@link WeaverseNextProvider} when no
+ * props are passed, or accepts an explicit `client` + `data` for standalone use. Builds a
+ * framework-neutral `Weaverse` core instance (no React Router hooks) and hands
+ * it to the shared `WeaverseRoot`.
+ */
+export const WeaverseNextRenderer = memo(function WeaverseNextRendererComponent(
+  props: WeaverseNextRendererProps
+): JSX.Element | null {
+  let context = useContext(WeaverseNextContext)
+  let client = props.client ?? context?.client
+  let data = props.data ?? client?.data ?? null
+  let dataContext =
+    props.dataContext ?? client?.dataContext ?? EMPTY_DATA_CONTEXT
+
+  let page = useMemo(() => getRenderablePage(data), [data])
+
+  let weaverse = useMemo(() => {
+    if (!page) {
+      return null
+    }
+
+    return createWeaverseNextRuntime({
+      client,
+      data: { ...(data as WeaverseNextLoaderData), page },
+      dataContext,
+      merchantOverrides: context?.merchantOverrides,
+      themeSettingsStore: context?.themeSettingsStore,
+      translationStore: context?.translationStore,
+    })
+  }, [
+    client,
+    page,
+    data,
+    dataContext,
+    context?.merchantOverrides,
+    context?.themeSettingsStore,
+    context?.translationStore,
+  ])
+
+  useIsomorphicLayoutEffect(() => {
+    weaverse?.flushRenderPhaseUpdates()
+  }, [weaverse])
+
+  if (!weaverse) {
+    return null
+  }
+
+  return (
+    <>
+      <WeaverseRoot context={weaverse} />
+      <WeaverseNextStudio runtime={weaverse} />
+    </>
+  )
+})

package/src/request-info.ts

@@ -0,0 +1,124 @@
+import type {
+  WeaverseNextRequestContext,
+  WeaverseNextRequestInfo,
+} from './types'
+
+function toUrl(value: string | URL): URL {
+  return typeof value === 'string' ? new URL(value, 'http://localhost') : value
+}
+
+function getSearchParamsFromContext(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams)
+  }
+
+  if (context?.url) {
+    let url = toUrl(context.url)
+    return new URLSearchParams(url.searchParams)
+  }
+
+  return new URLSearchParams()
+}
+
+/**
+ * Put the request's market prefix (`i18n.pathPrefix`, e.g. `/de-de`) on a
+ * pathname that does not carry it yet.
+ *
+ * A Next app builds its request context from the route path, and with
+ * locale-segmented routes that path is usually unprefixed. Studio's address
+ * bar follows `requestInfo.pathname`, so without the prefix it snaps back to
+ * the default market after every navigation. A path that already carries the
+ * prefix, and the default market's empty prefix, pass through unchanged.
+ */
+export function withPathPrefix(
+  pathname: string,
+  i18n?: WeaverseNextRequestContext['i18n']
+): string {
+  let raw = typeof i18n?.pathPrefix === 'string' ? i18n.pathPrefix : ''
+  // Split rather than regex-trim: `pathPrefix` is caller input, and an anchored
+  // `/\/+$/` backtracks polynomially on long runs of slashes.
+  let segments = raw.split('/').filter(Boolean)
+  let prefix = segments.length > 0 ? `/${segments.join('/')}` : ''
+  if (
+    prefix === '' ||
+    pathname === prefix ||
+    pathname.startsWith(`${prefix}/`)
+  ) {
+    return pathname
+  }
+  return pathname === '/' ? prefix : `${prefix}${pathname}`
+}
+
+function getPathnameFromContext(context?: WeaverseNextRequestContext): string {
+  if (context?.pathname) {
+    return withPathPrefix(context.pathname, context.i18n)
+  }
+
+  if (context?.url) {
+    let url = toUrl(context.url)
+    return withPathPrefix(url.pathname || '/', context.i18n)
+  }
+
+  return '/'
+}
+
+function coerceQueryValue(value: string): string | boolean {
+  if (value === 'true') {
+    return true
+  }
+  if (value === 'false') {
+    return false
+  }
+  return value
+}
+
+function toQueryRecord(
+  searchParams: URLSearchParams
+): Record<string, string | boolean> {
+  let queries: Record<string, string | boolean> = {}
+  for (let [key, value] of searchParams.entries()) {
+    queries[key] = coerceQueryValue(value)
+  }
+  return queries
+}
+
+const TRANSIENT_STUDIO_PARAMS = new Set([
+  'weaverseDraftItem',
+  // Legacy name from the original design-mode draft-item spike. Keep it out of
+  // runtime requestInfo too, in case an older Builder bundle is in front of a
+  // newer Next storefront.
+  '__weaverseDraftItem',
+])
+
+function getRequestInfoSearchParams(
+  context?: WeaverseNextRequestContext
+): URLSearchParams {
+  let searchParams = new URLSearchParams(getSearchParamsFromContext(context))
+  for (let key of TRANSIENT_STUDIO_PARAMS) {
+    searchParams.delete(key)
+  }
+  return searchParams
+}
+
+/**
+ * Build the Hydrogen-like request info shape consumed by the Studio bridge.
+ * Duplicate query keys keep the last value, matching `URLSearchParams` iteration
+ * assignment and Hydrogen's practical query-object behavior.
+ */
+export function buildWeaverseNextRequestInfo(
+  context?: WeaverseNextRequestContext
+): WeaverseNextRequestInfo {
+  let searchParams = getRequestInfoSearchParams(context)
+  let search = searchParams.toString()
+
+  return {
+    pathname: getPathnameFromContext(context),
+    search: search ? `?${search}` : '',
+    queries: toQueryRecord(searchParams),
+    ...(context?.i18n ? { i18n: context.i18n } : {}),
+    ...(context?.pageType ? { pageType: context.pageType } : {}),
+    ...(context?.handle ? { handle: context.handle } : {}),
+  }
+}

package/src/revalidate-item.ts

@@ -0,0 +1,211 @@
+import type { PageType } from '@weaverse/schema'
+import { PageTypeSchema } from '@weaverse/schema'
+import type {
+  WeaverseNextComponentData,
+  WeaverseNextI18n,
+  WeaverseNextRequestInfo,
+} from './types'
+
+/** Default App Router endpoint used for Studio item-loader revalidation. */
+export const DEFAULT_REVALIDATE_ENDPOINT = '/api/weaverse/revalidate'
+
+const MAX_ROUTE_CONTEXT_HANDLE_LENGTH = 512
+
+/**
+ * Server-owned and transient controls stripped from the revalidation route
+ * context on both sides of the trust boundary. Compared case-insensitively, so
+ * every entry is stored lowercased. Client sanitization keeps normal traffic
+ * clean; the route handler repeats this deny-list as the security boundary.
+ *
+ * - Server-owned: a crafted `?weaverseProjectId=`/`?weaverseHost=` must never
+ *   influence server config resolution (see `getWeaverseNextConfigs`), and
+ *   credential-shaped params never ride along in route context.
+ * - Transient: draft-item and RSC transport params never describe route identity.
+ */
+export const DENIED_ROUTE_CONTEXT_PARAMS = [
+  'weaverseprojectid',
+  'weaversehost',
+  'weaverseapikey',
+  'weaverseapibase',
+  'weaversepublicapibase',
+  'weaverseversion',
+  'projectid',
+  'weaversedraftitem',
+  '__weaversedraftitem',
+  '_rsc',
+]
+
+/** i18n fields allowed to cross the browser boundary. */
+export const ROUTE_CONTEXT_I18N_KEYS = [
+  'country',
+  'label',
+  'language',
+  'locale',
+  'pathPrefix',
+] as const
+
+/**
+ * JSON-safe route subset that may cross the browser boundary alongside the
+ * draft item. Never carries headers, cookies, auth, env, project ID, Studio
+ * host, API keys/bases, commerce clients, the request context, runtime, or
+ * client. `search` is canonical (preserves duplicate keys); the derived
+ * `queries` record is intentionally omitted.
+ */
+export interface WeaverseNextRevalidateRouteContext {
+  /** Route handle used for page assignment. */
+  handle?: string
+  /** Public locale and market identity allowed across the browser boundary. */
+  i18n?: Pick<
+    WeaverseNextI18n,
+    'country' | 'label' | 'language' | 'locale' | 'pathPrefix'
+  >
+  /** Weaverse page type resolved by the active route. */
+  pageType?: PageType
+  /** Canonical same-origin route pathname. */
+  pathname: string
+  /** Sanitized serialized query string, including the leading `?` when set. */
+  search: string
+}
+
+/**
+ * Minimal runtime surface the in-place apply needs. Structural (not the
+ * concrete `WeaverseNextRuntime` class) so unit tests can drive it with a
+ * plain mock. `requestInfo` stays optional: a real `WeaverseNextRuntime`
+ * always supplies it, but when absent the client omits `routeContext` and the
+ * legacy `{ draftItem }` request is preserved.
+ */
+export interface RevalidateItemRuntimeLike {
+  /** Live item stores keyed by Weaverse item ID. */
+  itemInstances: Map<
+    string,
+    {
+      /** Merge refreshed loader data into the live item store. */
+      setData: (update: Record<string, unknown>) => unknown
+    }
+  >
+  /** Active route identity used to construct the optional revalidation payload. */
+  requestInfo?: WeaverseNextRequestInfo
+}
+
+/**
+ * Strip denied (server-owned/transient) controls from a `search` string and
+ * re-serialize it. Preserves ordinary application queries, duplicate keys,
+ * encoded Unicode, and mode controls (`isDesignMode`, `isPreviewMode`,
+ * `__revisionId`, `sectionType`). Returns `''` or a `?`-prefixed string.
+ */
+export function sanitizeRouteContextSearch(search: string): string {
+  let params = new URLSearchParams(search)
+  let denied = new Set(DENIED_ROUTE_CONTEXT_PARAMS)
+  for (let key of [...new Set(params.keys())]) {
+    if (denied.has(key.toLowerCase())) {
+      params.delete(key)
+    }
+  }
+  let serialized = params.toString()
+  return serialized ? `?${serialized}` : ''
+}
+
+/**
+ * Build the sanitized {@link WeaverseNextRevalidateRouteContext} from the
+ * active runtime's request info. Returns `undefined` without a usable pathname
+ * so the caller omits `routeContext` and keeps the legacy request. This is not
+ * the security boundary — the route handler re-validates and re-sanitizes.
+ */
+export function buildWeaverseNextRevalidateRouteContext(
+  requestInfo?: WeaverseNextRequestInfo
+): WeaverseNextRevalidateRouteContext | undefined {
+  if (
+    !requestInfo ||
+    typeof requestInfo.pathname !== 'string' ||
+    !requestInfo.pathname
+  ) {
+    return
+  }
+
+  let routeContext: WeaverseNextRevalidateRouteContext = {
+    pathname: requestInfo.pathname,
+    search: sanitizeRouteContextSearch(requestInfo.search ?? ''),
+  }
+
+  let { i18n } = requestInfo
+  if (i18n && typeof i18n === 'object') {
+    let picked: Record<string, string> = {}
+    for (let key of ROUTE_CONTEXT_I18N_KEYS) {
+      let value = i18n[key]
+      if (typeof value === 'string') {
+        picked[key] = value
+      }
+    }
+    if (Object.keys(picked).length) {
+      routeContext.i18n = picked
+    }
+  }
+
+  if (
+    requestInfo.pageType &&
+    PageTypeSchema.safeParse(requestInfo.pageType).success
+  ) {
+    routeContext.pageType = requestInfo.pageType
+  }
+
+  if (
+    typeof requestInfo.handle === 'string' &&
+    requestInfo.handle &&
+    requestInfo.handle.length <= MAX_ROUTE_CONTEXT_HANDLE_LENGTH
+  ) {
+    routeContext.handle = requestInfo.handle
+  }
+
+  return routeContext
+}
+
+/**
+ * Studio per-item loader revalidation: POST the unsaved draft item (and, when
+ * the runtime exposes route context, a sanitized `routeContext`) to the app's
+ * revalidate route (see `createWeaverseNextRevalidateHandler`) and apply the
+ * returned `loaderData` to the live item instance in place.
+ *
+ * No `router.refresh()` is involved, so the RSC tree is never re-applied — no
+ * page remount, no scroll reset, and the draft payload never touches the URL.
+ *
+ * Throws on any failure (missing route, non-OK response, unknown item) so the
+ * Builder Studio bridge can detect the miss and fall back to its legacy
+ * refresh-based revalidation for this window.
+ */
+export async function revalidateWeaverseNextItem(
+  runtime: RevalidateItemRuntimeLike,
+  draftItem: WeaverseNextComponentData,
+  endpoint: string = DEFAULT_REVALIDATE_ENDPOINT
+): Promise<void> {
+  let instance = runtime.itemInstances.get(draftItem.id)
+  if (!instance) {
+    throw new Error(
+      `[weaverse-next] No live item instance for "${draftItem.id}".`
+    )
+  }
+
+  // Snapshot route identity at revalidation start so a later navigation cannot
+  // retarget this in-flight request. Omit `routeContext` for legacy runtimes.
+  let routeContext = buildWeaverseNextRevalidateRouteContext(
+    runtime.requestInfo
+  )
+  let body = routeContext ? { draftItem, routeContext } : { draftItem }
+
+  let response = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!response.ok) {
+    throw new Error(
+      `[weaverse-next] Revalidate endpoint responded ${response.status}.`
+    )
+  }
+
+  let { loaderData } = (await response.json()) as { loaderData?: unknown }
+  // The item's settings were already mutated by the Studio edit; only the
+  // loader payload needs applying. `setData` merges and notifies subscribers,
+  // and the new `loaderData` identity is what Builder's revalidation poll
+  // observes for completion.
+  instance.setData({ loaderData: loaderData ?? null })
+}

package/src/root-provider.tsx

@@ -0,0 +1,180 @@
+'use client'
+
+import type { SchemaType } from '@weaverse/schema'
+import {
+  createContext,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react'
+import {
+  getSchemaStaticContent,
+  WeaverseNextContext,
+  type WeaverseNextContextValue,
+} from './provider'
+import { createWeaverseNextThemeSettingsStore } from './theme-settings-store'
+import type { TranslateFunction } from './translate'
+import { TranslationProvider } from './translation-context'
+import { TranslationStore } from './translation-store'
+import type {
+  WeaverseNextThemeSchema,
+  WeaverseNextThemeSettingsStore,
+} from './types'
+
+/** Root-scoped theme and translation stores adopted by route providers. */
+export interface WeaverseNextRootContextValue {
+  /** Active-locale static-text overrides shared with route-level providers. */
+  merchantOverrides?: Record<string, unknown>
+  /** Theme default locale JSON shared with route-level providers. */
+  staticContent: Record<string, unknown>
+  /** Root-scoped external store shared with route-level providers. */
+  themeSettingsStore: WeaverseNextThemeSettingsStore
+  /** Single live design-mode static-text override store for the whole session. */
+  translationStore: TranslationStore
+}
+
+/**
+ * Ambient root-scoped context. Route-level `WeaverseNextProvider` reads this to
+ * adopt the shared theme settings store instead of creating its own.
+ */
+export const WeaverseNextRootContext =
+  createContext<WeaverseNextRootContextValue | null>(null)
+
+/** Root theme and translation data shared across the App Router tree. */
+export interface WeaverseNextRootProviderProps {
+  /** Application subtree, including global and route-level components. */
+  children: ReactNode
+  /** Root-loaded theme settings (published-mode fetch, no design-mode context). */
+  initialThemeSettings?: Record<string, unknown>
+  /** Active-locale static-text overrides from `loadThemeSettings().merchantOverrides`. */
+  merchantOverrides?: Record<string, unknown>
+  /** Public environment values exposed to the theme-settings store. */
+  publicEnv?: Record<string, string | undefined>
+  /**
+   * Theme default locale JSON (`loadThemeSettings().staticContent`). Falls back
+   * to `themeSchema.i18n.staticContent` when omitted.
+   */
+  staticContent?: Record<string, unknown>
+  /** Optional external translation function (host i18n); highest priority in `t()`. */
+  t?: TranslateFunction
+  /** Theme schema associated with the initial settings. */
+  themeSchema?: SchemaType | WeaverseNextThemeSchema
+}
+
+/**
+ * Root-scoped client boundary that owns the single `WeaverseNextThemeSettingsStore`
+ * for the whole app session, matching Hydrogen's `withWeaverse()` root store.
+ * Mount once in `app/layout.tsx`, above `Header`/`Footer`/global modules and any
+ * route-level `WeaverseNextProvider`.
+ *
+ * Also renders `WeaverseNextContext` with a minimal value so `useThemeSettings()`
+ * works for components mounted directly under this provider, even without a
+ * route-level `WeaverseNextProvider` above them.
+ *
+ * @example
+ * ```tsx
+ * <WeaverseNextRootProvider initialThemeSettings={theme.theme} themeSchema={theme.schema}>
+ *   <Header />
+ *   {children}
+ *   <Footer />
+ * </WeaverseNextRootProvider>
+ * ```
+ */
+export function WeaverseNextRootProvider(props: WeaverseNextRootProviderProps) {
+  let {
+    children,
+    initialThemeSettings,
+    merchantOverrides,
+    staticContent,
+    t,
+    themeSchema,
+    publicEnv,
+  } = props
+
+  // `useRef`, not `useMemo`: a parent re-render must never replace this store —
+  // it is the single instance Studio's `updateThemeSettings()` mutates in place.
+  let storeRef = useRef<WeaverseNextThemeSettingsStore | null>(null)
+  if (!storeRef.current) {
+    storeRef.current = createWeaverseNextThemeSettingsStore({
+      publicEnv,
+      schema: themeSchema,
+      settings: initialThemeSettings,
+    })
+  }
+  let themeSettingsStore = storeRef.current
+
+  // Same `useRef` rationale as the theme store: one live static-text store for
+  // the whole session, which Builder's `updateStaticText()` RPC mutates in place
+  // via `runtime.internal.translationStore`. A parent re-render must never swap
+  // it, or design-mode overrides would be lost.
+  let translationStoreRef = useRef<TranslationStore | null>(null)
+  if (!translationStoreRef.current) {
+    translationStoreRef.current = new TranslationStore()
+  }
+  let translationStore = translationStoreRef.current
+
+  // If `initialThemeSettings` changes after mount (e.g. root revalidation),
+  // update the existing store in place instead of replacing it. This is an
+  // effect because external store updates are side effects; the initial render
+  // is already seeded synchronously by store construction above.
+  let appliedThemeSettingsRef = useRef(initialThemeSettings)
+  useEffect(() => {
+    if (
+      initialThemeSettings &&
+      appliedThemeSettingsRef.current !== initialThemeSettings
+    ) {
+      themeSettingsStore.updateThemeSettings(initialThemeSettings)
+      appliedThemeSettingsRef.current = initialThemeSettings
+    }
+  }, [initialThemeSettings, themeSettingsStore])
+
+  // Prefer an explicit `staticContent` prop (from `loadThemeSettings()`); fall
+  // back to `themeSchema.i18n.staticContent`. Both resolve to referentially
+  // stable objects, so memoizing the context values below stays effective.
+  let resolvedStaticContent =
+    staticContent ?? getSchemaStaticContent(themeSchema)
+
+  // `themeSettingsStore` / `translationStore` are `useRef`-stable, so memoizing
+  // on them (rather than recreating these plain objects every render) keeps
+  // `useThemeSettings()` / `useTranslation()` consumers (Header, Footer, ...)
+  // from re-rendering on every root re-render.
+  let rootContextValue = useMemo<WeaverseNextRootContextValue>(
+    () => ({
+      merchantOverrides,
+      staticContent: resolvedStaticContent,
+      themeSettingsStore,
+      translationStore,
+    }),
+    [
+      merchantOverrides,
+      resolvedStaticContent,
+      themeSettingsStore,
+      translationStore,
+    ]
+  )
+  let contextValue = useMemo<WeaverseNextContextValue>(
+    () => ({
+      merchantOverrides,
+      themeSettings: themeSettingsStore.getSnapshot(),
+      themeSettingsStore,
+      translationStore,
+    }),
+    [merchantOverrides, themeSettingsStore, translationStore]
+  )
+
+  return (
+    <WeaverseNextRootContext.Provider value={rootContextValue}>
+      <WeaverseNextContext.Provider value={contextValue}>
+        <TranslationProvider
+          merchantOverrides={merchantOverrides}
+          staticContent={resolvedStaticContent}
+          t={t}
+          translationStore={translationStore}
+        >
+          {children}
+        </TranslationProvider>
+      </WeaverseNextContext.Provider>
+    </WeaverseNextRootContext.Provider>
+  )
+}