verlok/vanilla-lazyload

1. This repository is a client-side JavaScript library, not an application server. Its core product is a LazyLoad class that defers loading of images, responsive images, background images, videos, iframes, SVG/object content, and even arbitrary functions until elements are near or inside the viewport.

2. The main runtime boundary is the src/ library code versus the dist/ published bundles. src/ is the authored source, while dist/esm, dist/lazyload.js, and dist/lazyload.iife.js are build outputs for ES modules, UMD, and IIFE consumers. The same architecture is preserved across these bundles.

3. The top-level orchestration lives in src/lazyload.js. It is the public API surface that wires together options, element discovery, observer setup, load triggers, lifecycle methods, and bookkeeping. From an architecture diagram perspective, this is the central controller.

4. Element discovery is based on a container + selector model. By default, the library scans descendants of a scrolling container for elements with the .lazy class, but both the container and the selector are configurable. This means the library supports the main document as well as nested scrolling panels as separate observation scopes.

5. The viewport detection path is built around IntersectionObserver. The intersectionObserver, intersectionHandlers, and unobserve modules appear to split observer setup, per-entry enter/exit handling, and cleanup. The data flow is: discovered elements are observed, intersection events fire, handlers decide whether to enter/exit/load/unobserve, and state is updated accordingly.

6. Actual loading is delegated to type-specific helpers. The load, set, forEachSource, and tempImage modules likely handle translating data-* attributes into real DOM attributes for different targets: img, picture/source, video/source, iframe, object, and background-image variants. This is the key content-loading boundary between lazy metadata and browser-recognized resource URLs.

7. The library maintains per-element state and original attributes so it can reverse changes later. data, originalAttributes, elementStatus, reset, and restore indicate that LazyLoad tracks whether an element is pending, loading, loaded, errored, entered, or exited, and can reset or restore DOM back to its initial state. That makes lifecycle management a first-class concern, especially for SPAs or retry flows.

8. There is explicit support for cancellation and error recovery. cancelOnExit handles abort-like behavior when an image leaves the viewport before finishing, while online suggests retry logic when network connectivity returns. Together these modules add a resilience layer around the basic “load on enter” behavior.

9. Native-lazy-loading support is a separate branch, not just a flag on the same code path. The native and environment modules indicate feature detection and a hybrid mode where the library can delegate supported img/iframe/video loading to the browser via loading="lazy", while still handling unsupported cases such as background images through the JS observer path.

10. The library exposes rich callbacks and DOM class hooks as its integration boundary. callback, event, class, and defaults suggest that consumers can react to enter/load/error/finish events and style loading states through configurable class names. This is the main way application code hooks into the internal pipeline without touching implementation details.

11. autoInitialize.js is the bridge for the “async script” usage model described in the README. It allows the library to self-start from global options and emit an initialization event, which is important for CDN deployments where code runs after the script tag loads instead of via direct construction.

12. The repo includes extensive verification and usage surfaces: unit tests for stateful helpers like load/reset/restore/set/cancel behavior, end-to-end Playwright tests for real browser loading scenarios, and many HTML demos that exercise each feature combination. That makes the architecture easy to validate across browser APIs and edge cases such as dynamic content, multiple containers, placeholders, and error handling.

13. Tooling is centered on packaging and browser compatibility rather than a server runtime: Rollup for bundling, Jest for unit tests, Playwright for browser E2E, and CI workflows in GitHub Actions. There is also a TypeScript declaration file in typings/, so the library is distributed with typed consumer support even though the source is plain JavaScript.