@weaverse/hydrogen 5.23.0 → 6.0.0-beta.0

package/src/weaverse-client.ts

@@ -1,32 +1,30 @@
-import {
-  CacheCustom,
-  createWithCache,
-  type HydrogenEnv,
-  type I18nBase,
-} from '@shopify/hydrogen'
+import { Cache, createFetchWithCache } from '@shopify/hydrogen'
 import type {
   CachingStrategy,
   CustomPageEntry,
   FetchProjectPayload,
   FetchProjectRequestBody,
-  HydrogenComponent,
-  HydrogenComponentData,
-  HydrogenPageData,
   LoadPageParams,
   PageType,
   ProjectIdValidationResult,
-  ThemeSettingsResponse,
   WeaverseClientArgs,
+  WeaverseComponent,
+  WeaverseComponentData,
+  WeaverseEnv,
+  WeaverseI18n,
   WeaverseLoaderData,
+  WeaversePageData,
   WeaverseProjectConfigs,
   WeaverseStudioQueries,
+  WeaverseThemeSettingsResponse,
   WithCacheFetchResponse,
 } from './types'
 import {
   hasError,
-  isFetchProjectPayload,
   isProjectIdFunction,
   WeaverseError,
+  WeaverseLoadError,
+  type WeaverseLoadFailureKind,
 } from './types'
 import {
   generateDataFromSchema,
@@ -41,14 +39,10 @@ import { normalizePageUrl } from './utils/normalize-page-url'
  * These values optimize CDN hit rates while maintaining fresh content.
  */
 const CACHE_DURATIONS = {
-  /** Short browser freshness for content that can change in Builder */
+  /** 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
 
 /**
@@ -76,27 +70,160 @@ function isRetryableFetchError(error: unknown): boolean {
   if (!(error instanceof WeaverseError)) {
     return false
   }
-  if (error.code === 'TIMEOUT_ERROR' || error.code === 'NETWORK_ERROR') {
+  // A successful status with an unparsable body was classified as a network
+  // error before it got its own code; it keeps the same single retry.
+  if (
+    error.code === 'TIMEOUT_ERROR' ||
+    error.code === 'NETWORK_ERROR' ||
+    error.code === 'INVALID_RESPONSE'
+  ) {
     return true
   }
   return error.code === 'FETCH_ERROR' && (error.statusCode ?? 0) >= 500
 }
 
+/** Parses a JSON body, or returns the raw text when it is not JSON. */
+function parseResponseText(text: string): unknown {
+  if (!text) {
+    return text
+  }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Whether a successful `/project` body is a page envelope.
+ *
+ * `page: null` is Builder's authoritative "nothing assigned at this URL" and
+ * stays valid; anything without a `page` field, with an `error` field, or with
+ * a page that has no item list is not an answer about this URL at all.
+ */
+function isProjectEnvelope(payload: unknown): boolean {
+  if (!isPlainObject(payload) || hasError(payload) || !('page' in payload)) {
+    return false
+  }
+  const { page, project } = payload
+  const validPage =
+    page === null || (isPlainObject(page) && Array.isArray(page.items))
+  return validPage && (project == null || isPlainObject(project))
+}
+
+/**
+ * Whether a successful `/project_configs` body carries theme settings.
+ *
+ * Builder always sends the `theme` field; `null` means the merchant never
+ * saved settings, so schema defaults are the real configuration.
+ */
+function isThemeConfigsEnvelope(payload: unknown): boolean {
+  return (
+    isPlainObject(payload) &&
+    !hasError(payload) &&
+    'theme' in payload &&
+    (payload.theme === null || isPlainObject(payload.theme))
+  )
+}
+
+/**
+ * Classifies a page-load failure. `'absent'` is Builder's 404 for a project
+ * that does not exist, which keeps resolving to `null` like before.
+ */
+function classifyPageLoadFailure(
+  error: unknown
+): WeaverseLoadFailureKind | 'absent' {
+  if (error instanceof WeaverseLoadError) {
+    return error.kind
+  }
+  if (!(error instanceof WeaverseError)) {
+    // Thrown while turning a response into page data: the body was not
+    // the shape it claimed to be.
+    return 'invalid-response'
+  }
+  if (error.code === 'TIMEOUT_ERROR' || error.code === 'NETWORK_ERROR') {
+    return 'unavailable'
+  }
+  if (error.code === 'INVALID_RESPONSE') {
+    return 'invalid-response'
+  }
+  if (error.code === 'FETCH_ERROR') {
+    const status = error.statusCode ?? 0
+    if (status === 404) {
+      return 'absent'
+    }
+    if (status === 408 || status === 425 || status === 429 || status >= 500) {
+      return 'unavailable'
+    }
+  }
+  // Refusals (400/401/403) and project-ID errors: retrying cannot succeed.
+  return 'configuration'
+}
+
+/**
+ * Validators for Builder requests made by this client itself, keyed on the
+ * exact options object (same reasoning as `bodyFreeCacheRequests`). On the
+ * cached path such a request rejects a non-2xx status instead of resolving
+ * to `null`, and only stores a body its validator accepts. Every other
+ * `fetchWithCache` caller keeps the existing behavior.
+ */
+const builderPayloadValidators = new WeakMap<
+  object,
+  (payload: unknown) => boolean
+>()
+
+/**
+ * Gives a rejection from Hydrogen's cached fetch the code `fetchOnce` gives
+ * the same failure on the direct path.
+ *
+ * Hydrogen calls the platform `fetch` itself, so a request that never got a
+ * response rejects with the platform's error instead of a `WeaverseError`.
+ * The Fetch standard rejects a network failure with a `TypeError` and an
+ * aborted request with the signal's `AbortError`/`TimeoutError`; those are
+ * outages. Anything else is returned unchanged, so it is not reported as one.
+ */
+function cachedTransportError(error: unknown, url: string): unknown {
+  if (error instanceof WeaverseError || !(error instanceof Error)) {
+    return error
+  }
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+    return new WeaverseError('Request timed out', 'TIMEOUT_ERROR', undefined, {
+      url,
+    })
+  }
+  if (error instanceof TypeError) {
+    return new WeaverseError(
+      'Network error during fetch',
+      'NETWORK_ERROR',
+      undefined,
+      { url, cause: error.message }
+    )
+  }
+  return error
+}
+
 /**
  * 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.
+ * Cache strategy for Weaverse API requests: fresh for a minute, then served
+ * stale for a day while it refreshes or while Builder errors.
+ *
+ * Every Builder resource uses it. Hydrogen 2026.4's subrequest cache only read
+ * `max-age` for freshness, so the old per-resource `sMaxAge` values never
+ * changed how long an entry stayed fresh.
  */
-const DEFAULT_CACHE_STRATEGY: CachingStrategy = {
+const DEFAULT_CACHE_STRATEGY: CachingStrategy = Cache({
   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 =
@@ -107,9 +234,9 @@ export type BuilderApiCacheTarget =
 
 /** Fetch options accepted by {@link WeaverseClient.fetchWithCache}. */
 export interface WeaverseFetchWithCacheOptions extends RequestInit {
-  /** Builder API resource whose default freshness policy should be used. */
+  /** Builder API resource the request reads; part of the cache key. */
   cacheTarget?: BuilderApiCacheTarget
-  /** Explicit Hydrogen caching strategy overriding the resource default. */
+  /** Explicit Hydrogen caching strategy overriding the default. */
   strategy?: CachingStrategy
 }
 
@@ -121,18 +248,6 @@ export interface FetchCustomPagesOptions {
   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
-
 /**
  * Options objects created by the internal `project_configs` request whose
  * subrequest cache identity deliberately excludes the body. Theme settings
@@ -176,12 +291,12 @@ export class WeaverseClient {
   basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>
   /** Resolved project and rendering-mode configuration. */
   configs: WeaverseProjectConfigs
-  /** Hydrogen cache wrapper used for Builder API requests. */
-  withCache: ReturnType<typeof createWithCache>
+  /** Hydrogen cached fetch used for Builder API requests. */
+  private cachedFetch: ReturnType<typeof createFetchWithCache>
 
   /** Incoming request associated with this client instance. */
   request: WeaverseClientArgs['request']
-  /** Hydrogen customer-account client, when configured. */
+  /** Customer Account API client, when the storefront passes one. */
   customerAccount: WeaverseClientArgs['customerAccount']
   /** Hydrogen Storefront API client and locale context. */
   storefront: WeaverseClientArgs['storefront']
@@ -189,21 +304,22 @@ export class WeaverseClient {
   components: WeaverseClientArgs['components']
   /** Theme schema used for defaults and Studio editing. */
   themeSchema: WeaverseClientArgs['themeSchema']
-  /** Hydrogen runtime environment variables. */
+  /** Runtime environment variables. */
   env: WeaverseClientArgs['env']
   /** Cache storage supplied by the Hydrogen runtime. */
   cache: WeaverseClientArgs['cache']
-  /** Background execution hook supplied by the Oxygen runtime. */
+  /** Background execution hook supplied by the runtime. */
   waitUntil: WeaverseClientArgs['waitUntil']
 
   // Performance optimizations
   private readonly parsedUrl: URL
-  private readonly componentsByType: Map<string, HydrogenComponent>
+  private readonly componentsByType: Map<string, WeaverseComponent>
 
   // Configuration
   private readonly fetchTimeoutMs: number
+  private readonly throwPageLoadFailures: boolean
 
-  /** Creates a request-scoped client from the Hydrogen app context. */
+  /** Creates a request-scoped client from the storefront's request context. */
   constructor(args: WeaverseClientArgs) {
     // Assign required dependencies
     this.request = args.request
@@ -221,6 +337,7 @@ export class WeaverseClient {
 
     // Configuration
     this.fetchTimeoutMs = args.fetchTimeoutMs || DEFAULT_FETCH_TIMEOUT_MS
+    this.throwPageLoadFailures = args.throwPageLoadFailures === true
 
     // Initialize cache and configs
     this.initializeCache(args)
@@ -238,10 +355,9 @@ export class WeaverseClient {
       )
     }
 
-    this.withCache = createWithCache({
+    this.cachedFetch = createFetchWithCache({
       cache: args.cache,
-      waitUntil: args.waitUntil || (() => Promise.resolve()),
-      request: args.request,
+      waitUntil: args.waitUntil,
     })
   }
 
@@ -251,16 +367,13 @@ export class WeaverseClient {
    */
   private initializeConfigs(args: WeaverseClientArgs): void {
     // Get base configs once to avoid duplicate calls
-    const baseConfigs = getWeaverseConfigs(
-      args.request,
-      args.env as HydrogenEnv
-    )
+    const baseConfigs = getWeaverseConfigs(args.request, args.env)
 
     // Resolve projectId with multi-project support
     const resolvedProjectId = this.resolveProjectIdSync(
       args.projectId,
       args.request,
-      args.env as HydrogenEnv,
+      args.env,
       baseConfigs
     )
 
@@ -308,8 +421,8 @@ export class WeaverseClient {
    * Significantly improves performance for large component lists.
    */
   private buildComponentLookupMap(
-    components: HydrogenComponent[]
-  ): Map<string, HydrogenComponent> {
+    components: WeaverseComponent[]
+  ): Map<string, WeaverseComponent> {
     return new Map(components.map((comp) => [comp.schema?.type, comp]))
   }
 
@@ -407,7 +520,7 @@ export class WeaverseClient {
   private resolveProjectIdSync(
     projectId: string | (() => string) | (() => Promise<string>) | undefined,
     request: Request,
-    env: HydrogenEnv,
+    env: WeaverseEnv,
     baseConfigs?: WeaverseProjectConfigs
   ): string {
     return (
@@ -525,7 +638,7 @@ export class WeaverseClient {
   private resolveFromEnvironment(
     baseConfigs: WeaverseProjectConfigs | undefined,
     request: Request,
-    env: HydrogenEnv
+    env: WeaverseEnv
   ): string | null {
     const configs = baseConfigs || getWeaverseConfigs(request, env)
 
@@ -538,7 +651,6 @@ export class WeaverseClient {
 
   /**
    * 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>(
@@ -568,7 +680,22 @@ export class WeaverseClient {
         )
       }
 
-      const data = (await response.json()) as T
+      let data: T
+      try {
+        data = (await response.json()) as T
+      } catch (parseError) {
+        // A cut-short body still times out; anything else is a successful
+        // status whose body is not JSON, which is not a network failure.
+        if (parseError?.name === 'AbortError') {
+          throw parseError
+        }
+        throw new WeaverseError(
+          'Response body is not valid JSON',
+          'INVALID_RESPONSE',
+          response.status,
+          { url }
+        )
+      }
       return { data, response }
     } catch (err) {
       if (err instanceof WeaverseError) {
@@ -635,7 +762,7 @@ export class WeaverseClient {
 
   /**
    * Fetch data with caching support for both design mode and production.
-   * Uses direct fetch in design mode, Hydrogen's withCache in production.
+   * Uses direct fetch in design mode, Hydrogen's cached fetch in production.
    * Automatically includes projectId in cache key for multi-project isolation.
    *
    * @param url - The URL to fetch from
@@ -655,13 +782,8 @@ export class WeaverseClient {
     options: WeaverseFetchWithCacheOptions = {}
   ): Promise<T> => {
     const { cacheTarget, strategy: strategyOverride, ...fetchOptions } = options
-    const strategy =
-      strategyOverride ||
-      CacheCustom(
-        cacheTarget
-          ? SMART_CACHE_STRATEGIES[cacheTarget]
-          : DEFAULT_CACHE_STRATEGY
-      )
+    const strategy = strategyOverride || DEFAULT_CACHE_STRATEGY
+    const { body } = fetchOptions
 
     // Update cache key to include method, body content, and projectId for multi-project isolation
     // Prefix for easier debugging in cache systems
@@ -676,7 +798,9 @@ export class WeaverseClient {
       options.method || 'GET',
       bodyFreeCacheRequests.has(options)
         ? BODY_FREE_CACHE_SENTINEL
-        : fetchOptions.body,
+        : body == null
+          ? null
+          : String(body),
       // WeakSet-derived discriminator: this slot cannot be produced by any
       // caller-supplied shape, so no external call can reach the marked
       // identity — even one that happens to send the sentinel string as its
@@ -685,40 +809,66 @@ export class WeaverseClient {
       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 the proxy's
     // project version.
+    const validateBuilderPayload = builderPayloadValidators.get(options)
+
     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 => {
+      const result = await this.directFetch<T>(url, fetchOptions)
+      return result.data
+    }
+
+    let response: Response
+    let text: string
+    try {
+      response = await this.cachedFetch(url, fetchOptions, {
+        key: cacheKey,
+        strategy,
+        shouldCacheResponse: async ({ text: readText }) => {
           // An aborted request never caches: Hydrogen turns a body read cut
-          // short by the abort into an empty payload, not an error.
+          // short by the abort into an empty body, not an error.
           if (fetchOptions.signal?.aborted) {
             return false
           }
+          const payload = parseResponseText(await readText())
+          if (validateBuilderPayload && !validateBuilderPayload(payload)) {
+            return false
+          }
           // Cache any non-error response (for both Weaverse API and third-party APIs)
-          return (
-            !hasError(response) && response !== null && response !== undefined
-          )
+          return !hasError(payload) && payload !== null && payload !== ''
         },
-        displayName: 'Weaverse API',
-      })) as WithCacheFetchResponse<T>
+      })
+      text = await response.text()
+    } catch (error) {
+      // Only this client's own Builder requests are normalized; a
+      // third-party `fetchWithCache` caller keeps the platform error.
+      throw validateBuilderPayload ? cachedTransportError(error, url) : error
     }
 
-    return result.data
+    if (!response.ok) {
+      // For this client's own Builder requests a non-2xx status must not read
+      // as "nothing published"; surface the status the direct path already
+      // throws instead. Other callers keep the `null` body they always got.
+      if (validateBuilderPayload) {
+        throw new WeaverseError(
+          `HTTP ${response.status}: ${response.statusText}`,
+          'FETCH_ERROR',
+          response.status,
+          { url }
+        )
+      }
+      return null as T
+    }
+
+    return parseResponseText(text) as T
   }
 
   /**
@@ -750,7 +900,7 @@ export class WeaverseClient {
    */
   loadThemeSettings = async (
     strategy?: CachingStrategy
-  ): Promise<ThemeSettingsResponse> => {
+  ): Promise<WeaverseThemeSettingsResponse> => {
     const defaultThemeSettings = generateDataFromSchema(this.themeSchema)
     try {
       const { configs } = this
@@ -793,32 +943,28 @@ export class WeaverseClient {
         },
       }
       bodyFreeCacheRequests.add(themeSettingsOptions)
+      builderPayloadValidators.set(themeSettingsOptions, isThemeConfigsEnvelope)
 
       const [data, merchantOverrides] = await Promise.all([
-        this.fetchWithCache<ThemeSettingsResponse>(url, themeSettingsOptions),
+        this.fetchWithCache<WeaverseThemeSettingsResponse>(
+          url,
+          themeSettingsOptions
+        ),
         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),
-          }
+      // A body without a `theme` field (corrupted content, an error body, an
+      // empty object) is not the merchant's configuration. Report it like any
+      // other failure so schema defaults are never presented as loaded.
+      if (!isThemeConfigsEnvelope(data)) {
+        throw new WeaverseError(
+          'Invalid theme settings response format',
+          'INVALID_RESPONSE'
         )
-        result = { theme: defaultThemeSettings }
       }
 
+      let result = data
+
       if (this.themeSchema?.settings || this.themeSchema?.inspector) {
         // Ensure result.theme exists and is an object before merging
         if (!result.theme || typeof result.theme !== 'object') {
@@ -954,9 +1100,9 @@ export class WeaverseClient {
    * 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
+   * @returns WeaversePageData with single main component containing the message
    */
-  generateFallbackPage = (message: string): HydrogenPageData => {
+  generateFallbackPage = (message: string): WeaversePageData => {
     const rootId = crypto.randomUUID()
     return {
       id: `fallback_page_${Date.now()}`,
@@ -1060,6 +1206,24 @@ export class WeaverseClient {
   loadPage = async (
     params: LoadPageParams = {}
   ): Promise<WeaverseLoaderData | null> => {
+    // Validate route-level projectId if provided
+    if (params.projectId !== undefined) {
+      const message =
+        typeof params.projectId === 'string'
+          ? this.validateProjectId(params.projectId).error
+          : `must be a string. Received: ${typeof params.projectId}`
+      if (message) {
+        console.error(`Route-level projectId validation failed: ${message}`)
+        if (this.throwPageLoadFailures) {
+          throw new WeaverseLoadError(
+            'Route-level projectId validation failed',
+            'configuration'
+          )
+        }
+        return null
+      }
+    }
+
     try {
       const { request, storefront, basePageRequestBody, basePageConfigs } = this
       const {
@@ -1069,25 +1233,6 @@ export class WeaverseClient {
         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
 
@@ -1096,14 +1241,17 @@ export class WeaverseClient {
       }
 
       if (!effectiveProjectId) {
-        throw new Error('Missing Weaverse projectId!')
+        throw new WeaverseLoadError(
+          'Missing Weaverse projectId!',
+          'configuration'
+        )
       }
 
       const { strategy, ...pageLoadParams } = params
       const body: {
         projectId: string
         url: string
-        i18n?: I18nBase
+        i18n?: WeaverseI18n
         params?: {
           type?: PageType
           locale?: string
@@ -1131,40 +1279,45 @@ export class WeaverseClient {
       }
       const url = this.getApiUrl('project')
 
+      const projectOptions: WeaverseFetchWithCacheOptions = {
+        ...reqInit,
+        cacheTarget: 'project',
+        strategy,
+      }
+      builderPayloadValidators.set(projectOptions, isProjectEnvelope)
       const projectData: FetchProjectPayload =
-        await this.fetchWithCache<FetchProjectPayload>(url, {
-          ...reqInit,
-          cacheTarget: 'project',
-          strategy,
-        })
+        await this.fetchWithCache<FetchProjectPayload>(url, projectOptions)
 
       if (hasError(projectData)) {
-        throw new Error(projectData.error)
+        throw new WeaverseLoadError(
+          'Weaverse API returned an error body',
+          'invalid-response'
+        )
       }
 
-      // 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 {
+      if (!isProjectEnvelope(projectData)) {
+        // A body that does not answer for this URL is not "nothing assigned
+        // here". Without the opt-in, keep the historical fallback page.
+        if (this.throwPageLoadFailures) {
+          throw new WeaverseLoadError(
+            'Invalid project data structure received from API',
+            'invalid-response'
+          )
+        }
         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
       }
 
+      // Extract what we can; a legacy-mode malformed body may lack any field.
+      const responseData = projectData as Partial<FetchProjectPayload> | null
+      let page: WeaversePageData | undefined = responseData?.page ?? undefined
+      let project: WeaverseLoaderData['project'] | undefined =
+        responseData?.project
+      const pageAssignment: WeaverseLoaderData['pageAssignment'] | undefined =
+        responseData?.pageAssignment
+
       if (!project) {
         console.warn('Weaverse project not found. Id:', effectiveProjectId)
         project = {
@@ -1207,6 +1360,7 @@ export class WeaverseClient {
         },
       }
     } catch (error) {
+      const failure = classifyPageLoadFailure(error)
       const errorMessage = '❌ Page load failed'
       const errorContext: Record<string, unknown> = {
         projectId: params.projectId || this.configs.projectId,
@@ -1232,12 +1386,23 @@ export class WeaverseClient {
         })
       }
 
-      return null
+      if (failure === 'absent' || !this.throwPageLoadFailures) {
+        return null
+      }
+      if (error instanceof WeaverseLoadError) {
+        throw error
+      }
+      // Fixed message: the cause can carry request-derived detail.
+      throw new WeaverseLoadError(
+        'Unable to load Weaverse page',
+        failure,
+        error instanceof WeaverseError ? error.statusCode : undefined
+      )
     }
   }
 
   /** Executes the registered loader for one component and attaches its result. */
-  execComponentLoader = async (item: HydrogenComponentData) => {
+  execComponentLoader = async (item: WeaverseComponentData) => {
     const { data = {}, type, id } = item
     const component = this.componentsByType.get(type)
     const loader = component?.loader