From eae6381d024a6ecd6a0981086bbad42739c3325e Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sun, 31 May 2026 15:13:04 +0000
Subject: [PATCH] =?UTF-8?q?=E2=9A=A1=20Bolt:=20Offload=20lightbox=20image?=
 =?UTF-8?q?=20decoding=20from=20main=20thread?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: Added `decoding="async"` to the dynamically created image element in `js/lightbox.js`.
🎯 Why: When a high-resolution image is loaded into the lightbox, synchronous decoding can block the main thread, causing jank in the UI or animations. This optimization ensures decoding happens off the main thread.
📊 Impact: Reduces main-thread blocking time when viewing large images in the lightbox, improving responsiveness.
🔬 Measurement: Verify by opening a large image in the lightbox using Chrome DevTools Performance tab and observing reduced "Image Decode" time on the main thread.

Co-authored-by: ImChong <74563097+ImChong@users.noreply.github.com>
---
 .jules/bolt.md | 5 +++++
 js/lightbox.js | 1 +
 2 files changed, 6 insertions(+)

diff --git a/.jules/bolt.md b/.jules/bolt.md
index 8366fde..b256783 100644
--- a/.jules/bolt.md
+++ b/.jules/bolt.md
@@ -63,3 +63,8 @@
 
 **Learning:** Creating complex DOM structures (like a lightbox overlay with controls) immediately upon script execution delays the main thread during the critical initial page load phase, even if those components are hidden and may never be used by the user.
 **Action:** Use lazy initialization for interactive components that are not immediately visible. Wait to build and attach their DOM elements until the first time the user actually interacts with them (e.g., clicking an image to open the lightbox). This reduces initial DOM size and main thread blocking time.
+
+## 2026-06-01 - Offload decoding of dynamically created images
+
+**Learning:** When images are dynamically created in JavaScript, such as high-resolution images loaded into a lightbox component, synchronous decoding can block the main thread and cause UI jank (e.g., freezing the page temporarily while the image renders).
+**Action:** Always add `img.decoding = 'async'` when creating an `img` element in JavaScript (`document.createElement('img')`) to instruct the browser to decode the image off the main thread, improving perceived performance and responsiveness.
diff --git a/js/lightbox.js b/js/lightbox.js
index 3c8b925..f57db0e 100644
--- a/js/lightbox.js
+++ b/js/lightbox.js
@@ -34,6 +34,7 @@
     lbImg.id = 'lb-img';
     lbImg.src = '';
     lbImg.alt = '';
+    lbImg.decoding = 'async'; // ⚡ Bolt Performance Optimization: Decode large lightbox images off the main thread
 
     const lbControls = document.createElement('div');
     lbControls.id = 'lb-controls';