BigPipe placeholder guard prevents Drupal.blazy.init from initializing on authenticated pages

Problem/Motivation

Full disclosure, this issue was analyzed, and written with AI assistance.

There have been several issues addressing BigPipe compatibility in this module (#3361143: Compatibility with BigPipe). The fix introduced in that issue added a guard inside onceCompat() in blazy.once.js that the module's own comment acknowledges is incomplete:

// Tested at D10.3, a workaround, not a final fix, till BigPipe issues fixed.
// ...
// @todo update this if blazy ajax-related is broken later, that is when
// BigPipe fixes this issue.

This issue is the "broken later" case that comment anticipated.

When BigPipe is enabled and a page has any pending placeholder IDs in drupalSettings.bigPipePlaceholderIds, the init function in blazy.load.js — the one that creates the IntersectionObserver instance stored at Drupal.blazy.init — is blocked from running. This means Blazy's image observer is never set up, and lazy-loaded images are never loaded.

The onceCompat() function in blazy.once.js wraps Drupal core's once(). At the top of onceCompat():

if (!$.wwoBigPipeDone()) {
  return els;
}

$.wwoBigPipeDone() (defined in dblazy.js) returns false whenever drupalSettings.bigPipePlaceholderIds is non-empty. This guard was added to prevent double-processing of elements during BigPipe fragment replacement, which is correct for per-element processing. The problem is that the same guard also blocks the IntersectionObserver setup, which needs to happen regardless of BigPipe state.

In Drupal.behaviors.blazy.attach() in blazy.load.js, both calls go through the same gated wrapper:

// Per-container processing. BigPipe gate is appropriate here.
$.once(process.bind(me), ID_ONCE, S_ELEMENT, context);

// Creates Drupal.blazy.init (the IntersectionObserver instance).
// BigPipe gate is NOT appropriate here.
$.once(init.bind(me), ID_ONCE_GLOBAL, S_GLOBAL, context);

The second call, which runs the init function that ultimately executes me.init = me.run(me.options) and stores the IntersectionObserver instance at Drupal.blazy.init, is blocked while any BigPipe placeholder is pending on the page.

Why BigPipe resolving does not always recover the situation

When BigPipe eventually streams its last placeholder replacement, it calls Drupal.attachBehaviors() on the new fragment. At that point $.wwoBigPipeDone() returns true, and the init function can run. However, on pages that use Slick with lazyLoad: blazy, Slick's own behavior will have already initialized and positioned its slides during the window when Blazy was blocked. This is part of a separate issue that also needs to be filed with Slick.

The SVG placeholder images Blazy inserts have a natural size of 1×1 pixel. Once Slick initializes around images of that size, the slide containers can be measured and laid out at or near zero height. After that, when Blazy's IntersectionObserver is finally set up, it observes those images — but the IntersectionObserver specification states that elements with zero intersection area never dispatch intersection events, even with threshold: 0. The observer is active but fires nothing. The images remain as placeholders indefinitely.

Steps to reproduce

My apologies that I don't have reliable, clear instructions on reproducing. It's been an inconsistent issue on the site I'm working on, and quite a challenge to get here with it. I'll try to provide more info in the future if needed.

Proposed resolution

The BigPipe guard in onceCompat() is correct for the per-container process call in blazy.load.js: you do not want to mark containers as processed before BigPipe has injected their content. The guard is incorrect for the init call because the IntersectionObserver must be set up before BigPipe resolves so it is ready to observe elements as BigPipe injects them.

In blazy.load.js

Replace the gated $.once call for the observer setup with a direct call to the core once() library, bypassing the BigPipe guard in onceCompat(). In Drupal 10, core/once exposes the once() function as window.once; Drupal.once is provided as an alias in some versions but not all, so the same pattern used in blazy.once.js (Drupal.once || _win.once) is the safe form. Inside the IIFE in blazy.load.js, _win is already bound to window:

// Before:
$.once(init.bind(me), ID_ONCE_GLOBAL, S_GLOBAL, context);

// After:
var _coreOnce = Drupal.once || _win.once;
var _roots = _coreOnce(ID_ONCE_GLOBAL, S_GLOBAL, $.context(context, S_GLOBAL));
if (_roots.length) {
  init.call(me, _roots[0]);
}

The detach side should remain unchanged. $.once.removeSafely() already contains its own $.wwoBigPipeDone() guard, which correctly prevents the once-marking from being removed from body while BigPipe placeholder replacements are still in progress. Replacing it with an unconditional once.remove() causes the observer to be torn down and recreated on every BigPipe replacement event, calling the init function multiple times.

There are related issues in the Slick module that compound this problem when it manifests on a page with a Slick thumbnail nav. Those will be filed separately in the Slick issue queue.

Remaining tasks

Review and confirm the proposed fixes, particularly whether using Drupal.once() directly for ID_ONCE_GLOBAL creates any regression for the AJAX/infinite scroll cases that #3361143: Compatibility with BigPipe was originally addressing.