fix(image-pipeline): diagnose and stabilize webgl preview path

lib/image-pipeline/backend/backend-router.ts

@@ -65,6 +65,14 @@ function normalizeBackendHint(value: BackendHint): string | null {
   return normalized.length > 0 ? normalized : null;
 }
 
+function logBackendRouterDebug(event: string, payload: Record<string, unknown>): void {
+  if (process.env.NODE_ENV === "production" || process.env.NODE_ENV === "test") {
+    return;
+  }
+
+  console.info("[image-pipeline backend]", event, payload);
+}
+
 export function createBackendRouter(options?: {
   backends?: readonly ImagePipelineBackend[];
   defaultBackendId?: string;
@@ -123,6 +131,12 @@ export function createBackendRouter(options?: {
   }
 
   function emitFallback(event: BackendFallbackEvent): void {
+    logBackendRouterDebug("fallback", {
+      reason: event.reason,
+      requestedBackend: event.requestedBackend,
+      fallbackBackend: event.fallbackBackend,
+      errorMessage: event.error?.message,
+    });
     options?.onFallback?.(event);
   }
 
@@ -335,23 +349,32 @@ function getRolloutRouterState(): RolloutRouterState {
 export function getPreviewBackendHintForSteps(steps: readonly PreviewBackendRequest["step"][]): BackendHint {
   const rolloutState = getRolloutRouterState();
 
+  let backendHint: BackendHint;
+
   if (rolloutState.webglEnabled && rolloutState.webglAvailable) {
     if (isWebglPreviewPipelineSupported(steps)) {
-      return "webgl";
+      backendHint = "webgl";
+    } else if (rolloutState.wasmEnabled && rolloutState.wasmAvailable) {
+      backendHint = "wasm";
+    } else {
+      backendHint = CPU_BACKEND_ID;
     }
-
-    if (rolloutState.wasmEnabled && rolloutState.wasmAvailable) {
-      return "wasm";
-    }
-
-    return CPU_BACKEND_ID;
+  } else if (rolloutState.wasmEnabled && rolloutState.wasmAvailable) {
+    backendHint = "wasm";
+  } else {
+    backendHint = CPU_BACKEND_ID;
   }
 
-  if (rolloutState.wasmEnabled && rolloutState.wasmAvailable) {
-    return "wasm";
-  }
+  logBackendRouterDebug("preview-backend-hint", {
+    backendHint,
+    stepTypes: steps.map((step) => step.type),
+    webglAvailable: rolloutState.webglAvailable,
+    webglEnabled: rolloutState.webglEnabled,
+    wasmAvailable: rolloutState.wasmAvailable,
+    wasmEnabled: rolloutState.wasmEnabled,
+  });
 
-  return CPU_BACKEND_ID;
+  return backendHint;
 }
 
 export function runPreviewStepWithBackendRouter(request: PreviewBackendRequest): void {