@weaverse/next 0.1.0-alpha.8 → 1.0.0

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,182 @@
+'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,
+  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>
+  )
+}