@weaverse/hydrogen 5.17.1 → 5.18.0

package/src/weaverse-client.ts

@@ -0,0 +1,1179 @@
+import {
+  CacheCustom,
+  createWithCache,
+  type HydrogenEnv,
+  type I18nBase,
+} from '@shopify/hydrogen'
+import type {
+  CachingStrategy,
+  CustomPageEntry,
+  FetchProjectPayload,
+  FetchProjectRequestBody,
+  HydrogenComponent,
+  HydrogenComponentData,
+  HydrogenPageData,
+  LoadPageParams,
+  PageType,
+  ProjectIdValidationResult,
+  ThemeSettingsResponse,
+  WeaverseClientArgs,
+  WeaverseLoaderData,
+  WeaverseProjectConfigs,
+  WeaverseStudioQueries,
+  WithCacheFetchResponse,
+} from './types'
+import {
+  hasError,
+  isFetchProjectPayload,
+  isProjectIdFunction,
+  WeaverseError,
+} from './types'
+import {
+  generateDataFromSchema,
+  getPreviewData,
+  getRequestQueries,
+  getWeaverseConfigs,
+} from './utils'
+import { normalizePageUrl } from './utils/normalize-page-url'
+
+/**
+ * Cache duration constants (in seconds).
+ * These values optimize CDN hit rates while maintaining fresh content.
+ */
+const CACHE_DURATIONS = {
+  /** Short browser freshness for content that can change in Builder */
+  SHORT: 60,
+  /** Shared cache freshness for anonymous storefront traffic */
+  SHARED_SHORT: 300,
+  /** Long stale window so slow Builder responses do not block storefront rendering */
+  LONG: 86_400,
+  /** Extra freshness for sitemap-like index data */
+  STATIC: 3600,
+} as const
+
+/**
+ * Network timeout for fetch requests (in milliseconds).
+ * Default is 10 seconds to balance reliability and user experience.
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000
+
+/**
+ * Bounded retry for the public API fetch. A single slow/cold origin response,
+ * a transient 5xx, or a network blip would otherwise make loadPage return null
+ * — rendering the "Please add new section" placeholder or throwing a 404 in
+ * the route. Two attempts (one retry) is enough: by the time the first attempt
+ * times out, the edge proxy's single-flight leader has usually populated its
+ * versioned cache, so the retry lands on a warm HIT.
+ */
+const MAX_FETCH_ATTEMPTS = 2
+const FETCH_RETRY_BACKOFF_MS = 300
+
+/**
+ * Retry only transient failures: request timeouts, network errors, and origin
+ * 5xx. A 4xx is deterministic (e.g. a genuine 404) — retrying just wastes time.
+ */
+function isRetryableFetchError(error: unknown): boolean {
+  if (!(error instanceof WeaverseError)) {
+    return false
+  }
+  if (error.code === 'TIMEOUT_ERROR' || error.code === 'NETWORK_ERROR') {
+    return true
+  }
+  return error.code === 'FETCH_ERROR' && (error.statusCode ?? 0) >= 500
+}
+
+/**
+ * Weaverse API version path
+ */
+const API_PATH = 'v1' as const
+
+/**
+ * Default cache strategy for Weaverse API requests.
+ * Optimized for CDN performance with 23-hour stale content tolerance.
+ */
+const DEFAULT_CACHE_STRATEGY: CachingStrategy = {
+  maxAge: CACHE_DURATIONS.SHORT,
+  sMaxAge: CACHE_DURATIONS.SHARED_SHORT,
+  staleWhileRevalidate: CACHE_DURATIONS.LONG,
+  staleIfError: CACHE_DURATIONS.LONG,
+} as const
+
+/** Builder API resource whose freshness policy should be used for a request. */
+export type BuilderApiCacheTarget =
+  | 'custom-pages'
+  | 'merchant-overrides'
+  | 'project'
+  | 'theme-settings'
+
+/** Fetch options accepted by {@link WeaverseClient.fetchWithCache}. */
+export interface WeaverseFetchWithCacheOptions extends RequestInit {
+  /** Builder API resource whose default freshness policy should be used. */
+  cacheTarget?: BuilderApiCacheTarget
+  /** Explicit Hydrogen caching strategy overriding the resource default. */
+  strategy?: CachingStrategy
+}
+
+/** Pagination and locale options for {@link WeaverseClient.fetchCustomPages}. */
+export interface FetchCustomPagesOptions {
+  /** Maximum number of custom pages requested per API page. */
+  limit?: number
+  /** Locale whose published custom pages should be returned. */
+  locale?: string
+}
+
+const SMART_CACHE_STRATEGIES: Record<BuilderApiCacheTarget, CachingStrategy> = {
+  project: DEFAULT_CACHE_STRATEGY,
+  'theme-settings': DEFAULT_CACHE_STRATEGY,
+  'merchant-overrides': DEFAULT_CACHE_STRATEGY,
+  'custom-pages': {
+    maxAge: CACHE_DURATIONS.SHORT,
+    sMaxAge: CACHE_DURATIONS.STATIC,
+    staleWhileRevalidate: CACHE_DURATIONS.LONG,
+    staleIfError: CACHE_DURATIONS.LONG,
+  },
+} as const
+
+/**
+ * Request-scoped client for loading Weaverse pages and theme settings in Hydrogen.
+ *
+ * Create one client from the Hydrogen app context, then call
+ * {@link WeaverseClient.loadPage} from route loaders and
+ * {@link WeaverseClient.loadThemeSettings} from the root loader.
+ */
+export class WeaverseClient {
+  /** Builder API version used by this client. */
+  API = API_PATH
+  /** Stable project configuration shared by page requests. */
+  basePageConfigs: Omit<WeaverseProjectConfigs, 'requestInfo'>
+  /** Stable request body fields shared by page requests. */
+  basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>
+  /** Resolved project and rendering-mode configuration. */
+  configs: WeaverseProjectConfigs
+  /** Hydrogen cache wrapper used for Builder API requests. */
+  withCache: ReturnType<typeof createWithCache>
+
+  /** Incoming request associated with this client instance. */
+  request: WeaverseClientArgs['request']
+  /** Hydrogen customer-account client, when configured. */
+  customerAccount: WeaverseClientArgs['customerAccount']
+  /** Hydrogen Storefront API client and locale context. */
+  storefront: WeaverseClientArgs['storefront']
+  /** Components registered for page rendering and component loaders. */
+  components: WeaverseClientArgs['components']
+  /** Theme schema used for defaults and Studio editing. */
+  themeSchema: WeaverseClientArgs['themeSchema']
+  /** Hydrogen runtime environment variables. */
+  env: WeaverseClientArgs['env']
+  /** Cache storage supplied by the Hydrogen runtime. */
+  cache: WeaverseClientArgs['cache']
+  /** Background execution hook supplied by the Oxygen runtime. */
+  waitUntil: WeaverseClientArgs['waitUntil']
+
+  // Performance optimizations
+  private readonly parsedUrl: URL
+  private readonly componentsByType: Map<string, HydrogenComponent>
+
+  // Configuration
+  private readonly fetchTimeoutMs: number
+
+  /** Creates a request-scoped client from the Hydrogen app context. */
+  constructor(args: WeaverseClientArgs) {
+    // Assign required dependencies
+    this.request = args.request
+    this.storefront = args.storefront
+    this.customerAccount = args.customerAccount
+    this.components = args.components
+    this.themeSchema = args.themeSchema
+    this.env = args.env
+    this.cache = args.cache
+    this.waitUntil = args.waitUntil
+
+    // Performance optimizations
+    this.parsedUrl = new URL(args.request.url)
+    this.componentsByType = this.buildComponentLookupMap(args.components)
+
+    // Configuration
+    this.fetchTimeoutMs = args.fetchTimeoutMs || DEFAULT_FETCH_TIMEOUT_MS
+
+    // Initialize cache and configs
+    this.initializeCache(args)
+    this.initializeConfigs(args)
+  }
+
+  /**
+   * Initialize Hydrogen cache with proper configuration.
+   * Logs warning if waitUntil is missing.
+   */
+  private initializeCache(args: WeaverseClientArgs): void {
+    if (!args.waitUntil) {
+      console.warn(
+        '⚠️ WeaverseClient: waitUntil not provided, background operations may not complete'
+      )
+    }
+
+    this.withCache = createWithCache({
+      cache: args.cache,
+      waitUntil: args.waitUntil || (() => Promise.resolve()),
+      request: args.request,
+    })
+  }
+
+  /**
+   * Initialize configs with projectId resolution and fail-fast validation.
+   * Throws WeaverseError if projectId cannot be resolved.
+   */
+  private initializeConfigs(args: WeaverseClientArgs): void {
+    // Get base configs once to avoid duplicate calls
+    const baseConfigs = getWeaverseConfigs(
+      args.request,
+      args.env as HydrogenEnv
+    )
+
+    // Resolve projectId with multi-project support
+    const resolvedProjectId = this.resolveProjectIdSync(
+      args.projectId,
+      args.request,
+      args.env as HydrogenEnv,
+      baseConfigs
+    )
+
+    // Fail-fast validation: throw if projectId is empty
+    if (!resolvedProjectId || resolvedProjectId.trim() === '') {
+      throw new WeaverseError(
+        'Failed to initialize WeaverseClient: No valid projectId found. ' +
+          'Set WEAVERSE_PROJECT_ID environment variable or provide projectId parameter.',
+        'MISSING_PROJECT_ID'
+      )
+    }
+
+    // Initialize configs with resolved projectId
+    this.configs = {
+      ...baseConfigs,
+      projectId: resolvedProjectId,
+    }
+
+    // Initialize base configurations
+    this.basePageConfigs = {
+      projectId: this.configs.projectId,
+      weaverseHost: this.configs.weaverseHost,
+      weaverseApiBase: this.configs.weaverseApiBase,
+      weaverseApiKey: this.configs.weaverseApiKey,
+      weaverseVersion: this.configs.weaverseVersion,
+      isDesignMode: this.configs.isDesignMode,
+      isPreviewMode: this.configs.isPreviewMode,
+      isRevisionPreview: this.configs.isRevisionPreview,
+    }
+
+    this.basePageRequestBody = {
+      isDesignMode: this.configs.isDesignMode,
+      i18n: args.storefront.i18n,
+      projectId: this.configs.projectId,
+    }
+
+    // Freeze configs to prevent accidental mutations
+    Object.freeze(this.configs)
+    Object.freeze(this.basePageConfigs)
+    Object.freeze(this.basePageRequestBody)
+  }
+
+  /**
+   * Build component lookup map for O(1) access by type.
+   * Significantly improves performance for large component lists.
+   */
+  private buildComponentLookupMap(
+    components: HydrogenComponent[]
+  ): Map<string, HydrogenComponent> {
+    return new Map(components.map((comp) => [comp.schema?.type, comp]))
+  }
+
+  /**
+   * Extract comprehensive error information from unknown error type.
+   * Preserves error context, codes, and stack traces for debugging.
+   *
+   * @param error - Unknown error to extract information from
+   * @returns Structured error information with message, code, stack, and context
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   // ... operation
+   * } catch (error) {
+   *   const errorInfo = this.extractErrorInfo(error)
+   *   console.error('Operation failed:', errorInfo.message, errorInfo.context)
+   * }
+   * ```
+   */
+  private extractErrorInfo(error: unknown): {
+    message: string
+    code?: string
+    stack?: string
+    context?: Record<string, unknown>
+  } {
+    if (error instanceof WeaverseError) {
+      return {
+        message: error.message,
+        code: error.code,
+        context: error.context,
+        stack: error.stack,
+      }
+    }
+
+    if (error instanceof Error) {
+      return {
+        message: error.message,
+        stack: error.stack,
+      }
+    }
+
+    return {
+      message: String(error),
+    }
+  }
+
+  /**
+   * Extract error message only (for backward compatibility).
+   * Use extractErrorInfo() for more detailed error information.
+   *
+   * @deprecated Use extractErrorInfo() instead to preserve error context
+   */
+  private extractErrorMessage(error: unknown): string {
+    return this.extractErrorInfo(error).message
+  }
+
+  /**
+   * Validates projectId format (alphanumeric, hyphens, underscores only).
+   * Returns detailed validation result with error message.
+   *
+   * @param projectId - Project identifier to validate
+   * @returns Validation result with error message if invalid
+   */
+  private validateProjectId(projectId: string): ProjectIdValidationResult {
+    if (!projectId || projectId.trim() === '') {
+      return {
+        valid: false,
+        error: 'Project ID cannot be empty',
+      }
+    }
+
+    // Only allow alphanumeric characters, hyphens, and underscores
+    const validPattern = /^[a-zA-Z0-9_-]+$/
+    if (!validPattern.test(projectId)) {
+      return {
+        valid: false,
+        error: `Invalid format: "${projectId}". Only alphanumeric characters, hyphens, and underscores are allowed.`,
+      }
+    }
+
+    return { valid: true }
+  }
+
+  /**
+   * Resolves projectId with multi-project architecture support.
+   * Uses priority chain to determine the correct project ID.
+   *
+   * @param projectId - Project identifier (string, function, or undefined)
+   * @param request - HTTP request for context access
+   * @param env - Hydrogen environment with variables
+   * @param baseConfigs - Pre-fetched base configs to avoid duplicate calls
+   * @returns Resolved project ID string (empty string if none found)
+   */
+  private resolveProjectIdSync(
+    projectId: string | (() => string) | (() => Promise<string>) | undefined,
+    request: Request,
+    env: HydrogenEnv,
+    baseConfigs?: WeaverseProjectConfigs
+  ): string {
+    return (
+      this.resolveFromQueryParams(request) ||
+      this.resolveFromFunction(projectId) ||
+      this.resolveFromString(projectId) ||
+      this.resolveFromEnvironment(baseConfigs, request, env) ||
+      ''
+    )
+  }
+
+  /**
+   * Priority 1: Resolve projectId from URL query parameters.
+   * Used for design mode and preview mode overrides.
+   */
+  private resolveFromQueryParams(request: Request): string | null {
+    const queries = getRequestQueries<WeaverseStudioQueries>(request)
+    return queries.weaverseProjectId || null
+  }
+
+  /**
+   * Priority 2: Resolve projectId from function parameter.
+   * Detects and rejects async functions with helpful error.
+   */
+  private resolveFromFunction(
+    projectId: string | (() => string) | (() => Promise<string>) | undefined
+  ): string | null {
+    if (!isProjectIdFunction(projectId)) {
+      return null
+    }
+
+    // Check if it's an async function BEFORE calling
+    if (projectId.constructor.name === 'AsyncFunction') {
+      throw new WeaverseError(
+        'Async projectId functions must be awaited before passing to WeaverseClient. ' +
+          'Use: projectId: await getProjectAsync() instead of: projectId: getProjectAsync',
+        'ASYNC_PROJECT_ID'
+      )
+    }
+
+    try {
+      const result = projectId()
+
+      // Safety net: check if result is a Promise
+      if (result instanceof Promise) {
+        throw new WeaverseError(
+          'Async projectId functions must be awaited before passing to WeaverseClient. ' +
+            'Use: projectId: await getProjectAsync() instead of: projectId: getProjectAsync',
+          'ASYNC_PROJECT_ID'
+        )
+      }
+
+      if (result && result.trim() !== '') {
+        const trimmed = result.trim()
+        const validation = this.validateProjectId(trimmed)
+
+        if (validation.valid) {
+          return trimmed
+        }
+
+        // Throw on validation failure - fail-fast for explicit projectId
+        throw new WeaverseError(
+          validation.error || 'Invalid projectId format',
+          'INVALID_PROJECT_ID'
+        )
+      }
+    } catch (err) {
+      // Re-throw WeaverseError (async function errors, validation errors)
+      if (err instanceof WeaverseError) {
+        throw err
+      }
+
+      // Wrap unexpected errors
+      throw new WeaverseError(
+        `Failed to evaluate projectId function: ${err instanceof Error ? err.message : String(err)}`,
+        'PROJECT_ID_FUNCTION_ERROR',
+        undefined,
+        { cause: err instanceof Error ? err.stack : String(err) }
+      )
+    }
+
+    return null
+  }
+
+  /**
+   * Priority 3: Resolve projectId from explicit string parameter.
+   */
+  private resolveFromString(
+    projectId: string | (() => string) | (() => Promise<string>) | undefined
+  ): string | null {
+    if (typeof projectId !== 'string') {
+      return null
+    }
+
+    const trimmed = projectId.trim()
+    if (trimmed === '') {
+      return null
+    }
+
+    const validation = this.validateProjectId(trimmed)
+    if (validation.valid) {
+      return trimmed
+    }
+
+    // Throw on validation failure - fail-fast for explicit projectId
+    throw new WeaverseError(
+      validation.error || 'Invalid projectId format',
+      'INVALID_PROJECT_ID'
+    )
+  }
+
+  /**
+   * Priority 4: Resolve projectId from environment variables.
+   */
+  private resolveFromEnvironment(
+    baseConfigs: WeaverseProjectConfigs | undefined,
+    request: Request,
+    env: HydrogenEnv
+  ): string | null {
+    const configs = baseConfigs || getWeaverseConfigs(request, env)
+
+    if (configs.projectId && configs.projectId.trim() !== '') {
+      return configs.projectId.trim()
+    }
+
+    return null
+  }
+
+  /**
+   * Helper method for direct fetching in design mode.
+   * Returns same format as withCache.fetch for consistency.
+   * Includes 10-second timeout to prevent hanging requests.
+   */
+  private readonly fetchOnce = async <T>(
+    url: string,
+    options: RequestInit,
+    timeoutMs: number
+  ): Promise<WithCacheFetchResponse<T>> => {
+    const controller = new AbortController()
+    const timeoutId: ReturnType<typeof setTimeout> | undefined = setTimeout(
+      () => controller.abort(),
+      timeoutMs
+    )
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new WeaverseError(
+          `HTTP ${response.status}: ${response.statusText}`,
+          'FETCH_ERROR',
+          response.status,
+          { url, errorText }
+        )
+      }
+
+      const data = (await response.json()) as T
+      return { data, response }
+    } catch (err) {
+      if (err instanceof WeaverseError) {
+        throw err
+      }
+
+      if (err.name === 'AbortError') {
+        throw new WeaverseError(
+          `Request timeout after ${timeoutMs}ms`,
+          'TIMEOUT_ERROR',
+          undefined,
+          { url, timeoutMs }
+        )
+      }
+
+      throw new WeaverseError(
+        'Network error during fetch',
+        'NETWORK_ERROR',
+        undefined,
+        { url, cause: err instanceof Error ? err.message : String(err) }
+      )
+    } finally {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId)
+      }
+    }
+  }
+
+  private readonly directFetch = async <T>(
+    url: string,
+    options: RequestInit = {},
+    timeoutMs = this.fetchTimeoutMs
+  ): Promise<WithCacheFetchResponse<T>> => {
+    let lastError: unknown
+    for (let attempt = 1; attempt <= MAX_FETCH_ATTEMPTS; attempt++) {
+      try {
+        return await this.fetchOnce<T>(url, options, timeoutMs)
+      } catch (err) {
+        lastError = err
+        if (attempt >= MAX_FETCH_ATTEMPTS || !isRetryableFetchError(err)) {
+          throw err
+        }
+        await new Promise((resolve) =>
+          setTimeout(resolve, FETCH_RETRY_BACKOFF_MS * attempt)
+        )
+      }
+    }
+    throw lastError
+  }
+
+  // Helper method for building API URLs consistently
+  private getApiUrl(endpoint: string): string {
+    const { weaverseApiBase } = this.configs
+    return `${weaverseApiBase}/api/public/${endpoint}`
+  }
+
+  private isExternalPublicApiUrl(url: string): boolean {
+    const { weaverseApiBase, weaverseHost } = this.configs
+    return (
+      weaverseApiBase !== weaverseHost &&
+      url.startsWith(`${weaverseApiBase}/api/public/`)
+    )
+  }
+
+  /**
+   * Fetch data with caching support for both design mode and production.
+   * Uses direct fetch in design mode, Hydrogen's withCache in production.
+   * Automatically includes projectId in cache key for multi-project isolation.
+   *
+   * @param url - The URL to fetch from
+   * @param options - Fetch options including optional cache strategy
+   * @returns Promise resolving to the fetched data
+   *
+   * @example
+   * ```typescript
+   * const data = await weaverse.fetchWithCache<MyData>(
+   *   'https://api.example.com/data',
+   *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
+   * )
+   * ```
+   */
+  public fetchWithCache = async <T = unknown>(
+    url: string,
+    options: WeaverseFetchWithCacheOptions = {}
+  ): Promise<T> => {
+    const { cacheTarget, strategy: strategyOverride, ...fetchOptions } = options
+    const strategy =
+      strategyOverride ||
+      CacheCustom(
+        cacheTarget
+          ? SMART_CACHE_STRATEGIES[cacheTarget]
+          : DEFAULT_CACHE_STRATEGY
+      )
+
+    // Update cache key to include method, body content, and projectId for multi-project isolation
+    // Prefix for easier debugging in cache systems
+    const cacheKey = [
+      'weaverse-fetch',
+      url,
+      options.method || 'GET',
+      fetchOptions.body,
+      this.configs.projectId,
+      cacheTarget || 'default',
+    ]
+
+    let result: WithCacheFetchResponse<T>
+
+    // Bypass the shared Hydrogen subrequest cache for design/revision modes
+    // and for the Cloudflare public API proxy. The proxy owns freshness with
+    // versioned cache keys; keeping Hydrogen's URL/body cache in front would
+    // keep serving a stale response even after Builder bumps api.weaverse.io's
+    // project version.
+    if (
+      this.configs.isDesignMode ||
+      this.configs.isRevisionPreview ||
+      this.isExternalPublicApiUrl(url)
+    ) {
+      result = await this.directFetch<T>(url, fetchOptions)
+    } else {
+      // Use withCache.fetch for better integration with Hydrogen's caching system
+      result = (await this.withCache.fetch(url, fetchOptions, {
+        cacheKey,
+        cacheStrategy: strategy,
+        shouldCacheResponse: (response: any): boolean => {
+          // Cache any non-error response (for both Weaverse API and third-party APIs)
+          return (
+            !hasError(response) && response !== null && response !== undefined
+          )
+        },
+        displayName: 'Weaverse API',
+      })) as WithCacheFetchResponse<T>
+    }
+
+    return result.data
+  }
+
+  /**
+   * Load theme settings from Weaverse API with fallback to schema defaults.
+   * Merges remote settings with local theme schema and handles design mode serialization.
+   *
+   * @param strategy - Optional cache strategy override
+   * @returns Promise resolving to theme settings response
+   *
+   * @example
+   * ```typescript
+   * const settings = await weaverse.loadThemeSettings()
+   * const primaryColor = settings.theme.colors?.primary
+   * ```
+   */
+  loadThemeSettings = async (
+    strategy?: CachingStrategy
+  ): Promise<ThemeSettingsResponse> => {
+    const defaultThemeSettings = generateDataFromSchema(this.themeSchema)
+    try {
+      const { configs } = this
+      const { projectId, isDesignMode } = configs
+      if (!projectId) {
+        throw new Error('Missing Weaverse projectId!')
+      }
+
+      const url = this.getApiUrl('project_configs')
+
+      const body = JSON.stringify({ isDesignMode, projectId })
+
+      // Fetch theme settings and merchant overrides in parallel
+      const [data, merchantOverrides] = await Promise.all([
+        this.fetchWithCache<ThemeSettingsResponse>(url, {
+          method: 'POST',
+          cacheTarget: 'theme-settings',
+          strategy,
+          body,
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            'Accept-Encoding': 'gzip, deflate, br',
+          },
+        }),
+        this.fetchMerchantOverrides(strategy),
+      ])
+
+      let result = data
+
+      // Validate that data is a proper object, not corrupted/compressed content
+      if (typeof result !== 'object' || result === null) {
+        console.warn(
+          'Invalid theme settings response format, using defaults:',
+          {
+            type: typeof result,
+            isString: typeof result === 'string',
+            length:
+              typeof result === 'string' ? (result as string).length : 'N/A',
+            preview:
+              typeof result === 'string'
+                ? `${(result as string).slice(0, 50)}...`
+                : String(result),
+          }
+        )
+        result = { theme: defaultThemeSettings }
+      }
+
+      if (this.themeSchema?.settings || this.themeSchema?.inspector) {
+        // Ensure result.theme exists and is an object before merging
+        if (!result.theme || typeof result.theme !== 'object') {
+          result.theme = defaultThemeSettings
+        } else {
+          result.theme = {
+            ...defaultThemeSettings,
+            ...result.theme,
+          }
+        }
+      }
+
+      // Always include staticContent from themeSchema.i18n
+      const staticContent = this.themeSchema?.i18n?.staticContent
+      if (staticContent) {
+        result.staticContent = staticContent
+      }
+
+      // Include merchant overrides (locale-specific translations from DB)
+      if (merchantOverrides) {
+        result.merchantOverrides = merchantOverrides
+      }
+
+      if (this.configs.isDesignMode) {
+        result = {
+          ...result,
+          schema:
+            this.themeSchema && typeof this.themeSchema === 'object'
+              ? {
+                  ...this.themeSchema,
+                  settings: this.themeSchema?.settings?.map((group) => ({
+                    ...group,
+                    inputs: group?.inputs?.map((input) => {
+                      if (typeof input?.condition === 'function') {
+                        return {
+                          ...input,
+                          condition: input.condition.toString(),
+                        }
+                      }
+                      return input
+                    }),
+                  })),
+                }
+              : undefined,
+          publicEnv: this.configs.publicEnv,
+        }
+      }
+      return result
+    } catch (error) {
+      const errorMessage = 'Unable to load theme settings'
+      const errorDetails = this.extractErrorMessage(error)
+
+      console.error(errorMessage, errorDetails)
+
+      return {
+        theme: defaultThemeSettings,
+        staticContent: this.themeSchema?.i18n?.staticContent,
+        _error: errorDetails,
+        _loadFailed: true,
+      }
+    }
+  }
+
+  /**
+   * Fetch locale-specific merchant overrides from the translation API.
+   * Returns a nested JSON object with translated values.
+   * Falls back to empty object on error to avoid blocking theme rendering.
+   */
+  private fetchMerchantOverrides = async (
+    strategy?: CachingStrategy
+  ): Promise<Record<string, unknown> | undefined> => {
+    try {
+      const { projectId, weaverseHost } = this.configs
+      const i18n = this.storefront.i18n
+
+      // Skip entirely when the theme hasn't opted into i18n. Merchant overrides
+      // are locale-specific translations; a theme with no `i18n` schema has no
+      // translatable surface, so the fetch would always come back empty. Gating
+      // here keeps non-i18n storefronts from making a translation API call on
+      // every SSR — same `themeSchema.i18n` condition that guards `staticContent`.
+      if (!this.themeSchema?.i18n) {
+        return
+      }
+
+      if (!(projectId && weaverseHost)) {
+        return
+      }
+
+      // Build locale code from storefront i18n (e.g. "en-us")
+      const language = (i18n?.language || 'en').toLowerCase()
+      const country = (i18n?.country || 'us').toLowerCase()
+      const locale = `${language}-${country}`
+
+      const url = `${weaverseHost}/api/translation/static?projectId=${projectId}&locale=${locale}`
+
+      const overrides = await this.fetchWithCache<Record<string, unknown>>(
+        url,
+        {
+          method: 'GET',
+          cacheTarget: 'merchant-overrides',
+          strategy,
+          headers: {
+            Accept: 'application/json',
+          },
+        }
+      )
+
+      // Validate it's a proper object
+      if (typeof overrides === 'object' && overrides !== null) {
+        return overrides
+      }
+
+      return
+    } catch (error) {
+      // Don't let merchant overrides failure block theme rendering
+      console.warn(
+        'Unable to load merchant overrides, using theme defaults:',
+        this.extractErrorMessage(error)
+      )
+      return
+    }
+  }
+
+  /**
+   * Generate fallback page with default structure when page data is unavailable.
+   * Used internally when API returns no page or when page needs default content.
+   *
+   * @param message - Custom message to display in the fallback page
+   * @returns HydrogenPageData with single main component containing the message
+   */
+  generateFallbackPage = (message: string): HydrogenPageData => {
+    const rootId = crypto.randomUUID()
+    return {
+      id: `fallback_page_${Date.now()}`,
+      rootId,
+      name: 'Default Page',
+      items: [
+        {
+          type: 'main',
+          id: rootId,
+          data: { dangerouslySetInnerHTML: { __html: message } },
+        },
+      ],
+    }
+  }
+
+  /**
+   * Fetch all published custom pages for sitemap generation.
+   * Paginates automatically, never throws, returns accumulated results on partial failure.
+   */
+  async fetchCustomPages(
+    opts?: FetchCustomPagesOptions
+  ): Promise<CustomPageEntry[]> {
+    const { weaverseApiBase, projectId } = this.configs
+    const entries: CustomPageEntry[] = []
+    const MAX_PAGES = 100
+
+    let cursor: string | null = null
+
+    for (let i = 0; i < MAX_PAGES; i++) {
+      const params = new URLSearchParams()
+      if (opts?.locale) {
+        params.set('locale', opts.locale)
+      }
+      if (opts?.limit) {
+        params.set('limit', String(opts.limit))
+      }
+      if (cursor) {
+        params.set('cursor', cursor)
+      }
+
+      const qs = params.toString()
+      const url = `${weaverseApiBase}/api/public/v1/projects/${projectId}/custom-pages${qs ? `?${qs}` : ''}`
+
+      try {
+        const result = await this.fetchWithCache<{
+          data: CustomPageEntry[]
+          nextCursor: string | null
+        }>(url, { cacheTarget: 'custom-pages' })
+        entries.push(...(result.data || []))
+
+        if (!result.nextCursor) {
+          return entries
+        }
+        cursor = result.nextCursor
+      } catch (err: any) {
+        const status = err?.status
+        const msg = err?.message || String(err)
+        console.warn(
+          entries.length === 0
+            ? `[Weaverse] Failed to fetch custom pages: ${msg}${status ? ` (HTTP ${status})` : ''}`
+            : `[Weaverse] Custom pages pagination interrupted: ${msg}`
+        )
+        return entries
+      }
+    }
+
+    console.warn(
+      '[Weaverse] Custom pages pagination cap reached (100 iterations)'
+    )
+    return entries
+  }
+
+  /**
+   * Load page data from Weaverse API with optional route-level project override.
+   * Fetches page content, executes component loaders, and handles empty items fallback.
+   *
+   * @param params - Optional page loading parameters
+   * @param params.type - Page type (INDEX, PAGE, PRODUCT, COLLECTION, etc.)
+   * @param params.handle - Page handle for dynamic routes
+   * @param params.locale - Locale override
+   * @param params.projectId - Route-level project ID override (for multi-project)
+   * @param params.strategy - Custom cache strategy override
+   * @returns Promise resolving to page data or null on error
+   *
+   * @example
+   * ```typescript
+   * // Basic usage
+   * const data = await weaverse.loadPage()
+   *
+   * // With page type
+   * const data = await weaverse.loadPage({ type: 'INDEX' })
+   *
+   * // Route-level project override
+   * const data = await weaverse.loadPage({
+   *   type: 'PAGE',
+   *   handle: 'about',
+   *   projectId: 'campaign-project-123'
+   * })
+   * ```
+   */
+  loadPage = async (
+    params: LoadPageParams = {}
+  ): Promise<WeaverseLoaderData | null> => {
+    try {
+      const { request, storefront, basePageRequestBody, basePageConfigs } = this
+      const {
+        projectId: clientProjectId,
+        weaverseHost,
+        isPreviewMode,
+        sectionType,
+      } = this.configs
+
+      // Validate route-level projectId if provided
+      if (params.projectId !== undefined) {
+        if (typeof params.projectId !== 'string') {
+          console.error(
+            'Route-level projectId validation failed: must be a string. ' +
+              `Received: ${typeof params.projectId}`
+          )
+          return null
+        }
+
+        const validation = this.validateProjectId(params.projectId)
+        if (!validation.valid) {
+          console.error(
+            `Route-level projectId validation failed: ${validation.error}`
+          )
+          return null
+        }
+      }
+
+      // Override client-level projectId with route-level projectId if provided
+      const effectiveProjectId = params.projectId || clientProjectId
+
+      if (isPreviewMode) {
+        return getPreviewData(sectionType || '', this.components, weaverseHost)
+      }
+
+      if (!effectiveProjectId) {
+        throw new Error('Missing Weaverse projectId!')
+      }
+
+      const { strategy, ...pageLoadParams } = params
+      const body: {
+        projectId: string
+        url: string
+        i18n?: I18nBase
+        params?: {
+          type?: PageType
+          locale?: string
+          handle?: string
+        }
+        isDesignMode?: boolean
+      } = {
+        ...basePageRequestBody,
+        projectId: effectiveProjectId, // Use effective (potentially overridden) projectId
+        params: pageLoadParams,
+        // Stripped to pathname + Weaverse params — tracking params would
+        // fragment the subrequest cache key (see normalizePageUrl).
+        url: normalizePageUrl(request.url),
+      }
+
+      const reqInit: RequestInit = {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          'Accept-Encoding': 'gzip, deflate, br',
+          'X-Visitor-UA': request.headers.get('user-agent') || '',
+        },
+      }
+      const url = this.getApiUrl('project')
+
+      const projectData: FetchProjectPayload =
+        await this.fetchWithCache<FetchProjectPayload>(url, {
+          ...reqInit,
+          cacheTarget: 'project',
+          strategy,
+        })
+
+      if (hasError(projectData)) {
+        throw new Error(projectData.error)
+      }
+
+      // Extract what we can from the response using type guard
+      // If validation fails, use fallback data instead of throwing
+      let page: HydrogenPageData | undefined
+      let project: WeaverseLoaderData['project'] | undefined
+      let pageAssignment: WeaverseLoaderData['pageAssignment'] | undefined
+
+      if (isFetchProjectPayload(projectData)) {
+        // Valid response - extract normally
+        page = projectData.page
+        project = projectData.project
+        pageAssignment = projectData.pageAssignment
+      } else {
+        console.warn(
+          'Invalid project data structure received from API, using fallback data',
+          { projectId: effectiveProjectId }
+        )
+        // Try to extract what we can from the malformed response
+        const responseData = projectData as any
+        page = responseData?.page
+        project = responseData?.project
+        pageAssignment = responseData?.pageAssignment
+      }
+
+      if (!project) {
+        console.warn('Weaverse project not found. Id:', effectiveProjectId)
+        project = {
+          id: effectiveProjectId,
+          name: 'Weaverse project not found.',
+          weaverseShopId: '',
+        }
+      }
+
+      if (!page) {
+        page = this.generateFallbackPage(
+          '<div style="text-align: center;">Please add new section to start.</div>'
+        )
+      }
+
+      if (page?.items?.length === 0) {
+        page.items.push({
+          type: 'main',
+          id: page.rootId || crypto.randomUUID(),
+          data: {},
+        })
+      }
+
+      if (page?.items) {
+        const items = page.items
+        page.items = await Promise.all(items.map(this.execComponentLoader))
+      }
+      return {
+        page,
+        project,
+        pageAssignment,
+        configs: {
+          ...basePageConfigs,
+          requestInfo: {
+            i18n: storefront.i18n,
+            queries: getRequestQueries<WeaverseStudioQueries>(request),
+            pathname: this.parsedUrl.pathname,
+            search: this.parsedUrl.search,
+          },
+        },
+      }
+    } catch (error) {
+      const errorMessage = '❌ Page load failed'
+      const errorContext: Record<string, unknown> = {
+        url: this.request.url,
+        projectId: params.projectId || this.configs.projectId,
+      }
+
+      if (error instanceof WeaverseError) {
+        console.error(errorMessage, {
+          code: error.code,
+          message: error.message,
+          ...errorContext,
+          ...error.context,
+        })
+      } else if (error instanceof Error) {
+        console.error(errorMessage, {
+          message: error.message,
+          stack: error.stack,
+          ...errorContext,
+        })
+      } else {
+        console.error(errorMessage, {
+          error: String(error),
+          ...errorContext,
+        })
+      }
+
+      return null
+    }
+  }
+
+  /** Executes the registered loader for one component and attaches its result. */
+  execComponentLoader = async (item: HydrogenComponentData) => {
+    const { data = {}, type, id } = item
+    const component = this.componentsByType.get(type)
+    const loader = component?.loader
+    if (typeof loader === 'function' && component) {
+      try {
+        return {
+          ...item,
+          loaderData: await Promise.resolve(
+            loader({
+              data: { ...generateDataFromSchema(component.schema), ...data },
+              weaverse: this,
+            })
+          ),
+        }
+      } catch (error) {
+        console.warn('❌ Item loader run failed.', type, id, error)
+        return item
+      }
+    }
+    return item
+  }
+}