From 00acc72aa279e39c2ac1549fa394d5d4958f48f8 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 5 Aug 2026 14:00:34 +0000
Subject: [PATCH 1/5] =?UTF-8?q?=E2=9A=A1=20Bolt:=20LCP=20=EC=9D=B4?=
 =?UTF-8?q?=EB=AF=B8=EC=A7=80=20=EC=84=B1=EB=8A=A5=20=EC=B5=9C=EC=A0=81?=
 =?UTF-8?q?=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .jules/bolt.md       | 4 ++++
 CHANGELOG.md         | 1 +
 index.html           | 6 ++++--
 tests/test_styles.py | 7 +++++--
 4 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/.jules/bolt.md b/.jules/bolt.md
index c10fb9b..d3a0f65 100644
--- a/.jules/bolt.md
+++ b/.jules/bolt.md
@@ -12,3 +12,7 @@
 ## 2026-07-10 - Remove unnecessary DOMPurify for performance
 **Learning:** 애플리케이션이 `textContent`와 같은 안전한 DOM API만 사용하고 `innerHTML` 등의 위험한 싱크를 사용하지 않는다면 DOMPurify와 같은 라이브러리를 통해 Trusted Types 정책을 생성할 필요가 없음.
 **Action:** 불필요한 번들 다운로드 및 스크립트 실행을 방지하기 위해 사용하지 않는 라이브러리를 식별하고 제거할 것.
+
+## 2026-08-05 - LCP (Largest Contentful Paint) Image Optimization
+**Learning:** Adding `decoding="async"` to critical above-the-fold LCP SVG images delays their rendering and degrades the LCP metric, as the browser shifts decoding to a background thread instead of processing them immediately alongside the main content.
+**Action:** Remove `decoding="async"` from non-lazy loaded critical images (like the top logo and hero graphics) while maintaining it on `loading="lazy"` off-screen images to prioritize main thread rendering speed.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ca1847a..49eae22 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # CHANGELOG
 
 ## [Unreleased]
+- **성능 최적화**: LCP(Largest Contentful Paint) 개선을 위해 화면 상단의 주요 SVG 이미지(로고, 히어로 그래픽)에서 `decoding="async"` 속성을 제거하여 백그라운드 스레드 지연 없이 즉시 렌더링되도록 수정했습니다.
 - **UX/접근성 개선**: 프로젝트 카드의 클릭 영역을 카드 전체로 확장하여 사용자 편의성을 높였습니다. <a> 태그를 확장하는 대신 가상 요소(pseudo-element) 겹침 방식을 사용하여 스크린 리더 접근성을 유지했습니다.
 - **보안 개선**: 컴포넌트 갤러리의 인라인 스크립트와 스타일을 외부 파일로 분리하고, 엄격한 Content-Security-Policy를 적용해 XSS 방어를 강화했습니다.
 - **성능 회귀 복원**: 오프스크린 `.section` 렌더링을 `content-visibility: auto`로 지연하고, 일반 섹션은 600px·콘텐츠가 큰 DIKW/projects 섹션은 1000px의 `contain-intrinsic-size` placeholder를 유지해 초기 렌더링 비용과 스크롤바 이동을 함께 줄였습니다.
diff --git a/index.html b/index.html
index fd888db..a2dbbd7 100644
--- a/index.html
+++ b/index.html
@@ -29,7 +29,8 @@
     <a href="#top" class="skip-link" data-i18n="nav.skipToContent">본문으로 건너뛰기</a>
     <header class="site-header">
       <a class="brand" href="#top" aria-label="Contextual Wisdom Lab home">
-        <img src="assets/context-wisdom-lab-avatar.svg" alt="" width="44" height="44" decoding="async">
+        <!-- ⚡ Bolt: Removed decoding="async" for SVG/LCP optimization -->
+        <img src="assets/context-wisdom-lab-avatar.svg" alt="" width="44" height="44">
         <span>Contextual Wisdom Lab</span>
       </a>
       <nav class="site-nav" aria-label="Primary navigation">
@@ -64,7 +65,8 @@ <h1 data-i18n="hero.title">맥락지혜 연구실</h1>
         </div>
 
         <div class="hero-visual">
-          <img class="context-art" src="assets/context-thread-map.svg" alt="" aria-hidden="true" width="760" height="560" fetchpriority="high" decoding="async">
+          <!-- ⚡ Bolt: Removed decoding="async" for SVG/LCP optimization -->
+          <img class="context-art" src="assets/context-thread-map.svg" alt="" aria-hidden="true" width="760" height="560" fetchpriority="high">
           <div class="ladder" role="list" aria-label="Data to wisdom ladder">
             <div class="ladder-row" role="listitem">
               <span>Data</span>
diff --git a/tests/test_styles.py b/tests/test_styles.py
index 5b4fb3b..74cc149 100644
--- a/tests/test_styles.py
+++ b/tests/test_styles.py
@@ -44,12 +44,15 @@ def test_tall_sections_reserve_larger_intrinsic_block_size():
 
 
 def test_images_decode_without_blocking_rendering():
-    """All site images opt into asynchronous decoding."""
+    """All lazy-loaded site images opt into asynchronous decoding."""
     parser = _ImageParser()
     parser.feed(INDEX.read_text(encoding="utf-8"))
 
     assert parser.images
-    assert all(image.get("decoding") == "async" for image in parser.images)
+
+    # Non-lazy LCP SVG images should be decoded synchronously
+    lazy_images = [img for img in parser.images if img.get("loading") == "lazy"]
+    assert all(image.get("decoding") == "async" for image in lazy_images)
 
 def test_project_cards_are_fully_clickable_via_pseudo_element():
     """Project cards expand clickable area to entire card without wrapping the whole block in an anchor."""

From b78263bb6262956ff42a12177afc6e71d48db95e Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 6 Aug 2026 00:06:09 +0900
Subject: [PATCH 2/5] test: make image hint contracts non-vacuous

---
 tests/test_styles.py | 68 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 54 insertions(+), 14 deletions(-)

diff --git a/tests/test_styles.py b/tests/test_styles.py
index 74cc149..916bc01 100644
--- a/tests/test_styles.py
+++ b/tests/test_styles.py
@@ -1,4 +1,4 @@
-"""Regression tests for performance-sensitive site CSS."""
+"""Regression tests for performance-sensitive site CSS and image hints."""
 
 import re
 from html.parser import HTMLParser
@@ -10,23 +10,40 @@
 
 
 class _ImageParser(HTMLParser):
-    def __init__(self):
+    """Collect literal image attributes from the static homepage."""
+
+    def __init__(self) -> None:
+        """Initialize an empty image collection."""
         super().__init__()
         self.images: list[dict[str, str | None]] = []
 
-    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+    def handle_starttag(
+        self,
+        tag: str,
+        attrs: list[tuple[str, str | None]],
+    ) -> None:
+        """Record each ``img`` element encountered by the parser."""
         if tag == "img":
             self.images.append(dict(attrs))
 
 
 def _rule(selector: str) -> str:
+    """Return the declaration body for one exact CSS selector."""
     css = STYLES.read_text(encoding="utf-8")
     match = re.search(rf"{re.escape(selector)}\s*\{{(?P<body>[^}}]+)\}}", css)
     assert match is not None, f"missing CSS rule: {selector}"
     return match.group("body")
 
 
-def test_sections_defer_offscreen_rendering_with_stable_placeholder():
+def _homepage_images() -> list[dict[str, str | None]]:
+    """Parse and return every homepage image with its literal attributes."""
+    parser = _ImageParser()
+    parser.feed(INDEX.read_text(encoding="utf-8"))
+    assert parser.images, "homepage must contain at least one image"
+    return parser.images
+
+
+def test_sections_defer_offscreen_rendering_with_stable_placeholder() -> None:
     """Ordinary sections retain their measured-size fallback while skipped."""
     rule = _rule(".section")
 
@@ -35,7 +52,7 @@ def test_sections_defer_offscreen_rendering_with_stable_placeholder():
     assert "contain-intrinsic-size: auto 600px;" in rule
 
 
-def test_tall_sections_reserve_larger_intrinsic_block_size():
+def test_tall_sections_reserve_larger_intrinsic_block_size() -> None:
     """Content-heavy sections reserve enough space to avoid scrollbar jumps."""
     rule = _rule(".section.dikw, .section.projects")
 
@@ -43,19 +60,42 @@ def test_tall_sections_reserve_larger_intrinsic_block_size():
     assert "contain-intrinsic-size: auto 1000px;" in rule
 
 
-def test_images_decode_without_blocking_rendering():
-    """All lazy-loaded site images opt into asynchronous decoding."""
-    parser = _ImageParser()
-    parser.feed(INDEX.read_text(encoding="utf-8"))
+def test_eager_images_leave_decoding_to_the_user_agent() -> None:
+    """Eager images use the standards-defined default ``auto`` decode hint."""
+    eager_images = [
+        image for image in _homepage_images() if image.get("loading") != "lazy"
+    ]
 
-    assert parser.images
+    assert eager_images, "the initial viewport must contain eager images"
+    assert all(image.get("decoding") is None for image in eager_images)
 
-    # Non-lazy LCP SVG images should be decoded synchronously
-    lazy_images = [img for img in parser.images if img.get("loading") == "lazy"]
+
+def test_lazy_images_decode_asynchronously() -> None:
+    """Deferred images remain explicitly asynchronous and cannot pass vacuously."""
+    lazy_images = [
+        image for image in _homepage_images() if image.get("loading") == "lazy"
+    ]
+
+    assert lazy_images, "the long homepage must retain deferred images"
     assert all(image.get("decoding") == "async" for image in lazy_images)
 
-def test_project_cards_are_fully_clickable_via_pseudo_element():
-    """Project cards expand clickable area to entire card without wrapping the whole block in an anchor."""
+
+def test_lcp_candidate_is_eager_and_high_priority() -> None:
+    """The declared LCP candidate is eager without a forced decode strategy."""
+    lcp_candidates = [
+        image
+        for image in _homepage_images()
+        if image.get("fetchpriority") == "high"
+    ]
+
+    assert len(lcp_candidates) == 1
+    lcp_candidate = lcp_candidates[0]
+    assert lcp_candidate.get("loading") != "lazy"
+    assert lcp_candidate.get("decoding") is None
+
+
+def test_project_cards_are_fully_clickable_via_pseudo_element() -> None:
+    """Project cards expose the complete card as the link target."""
     article_rule = _rule(".project-grid article")
     assert "position: relative;" in article_rule
 

From 7faa94034dd01d5481247183dc37272f2773a8d1 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 6 Aug 2026 00:06:30 +0900
Subject: [PATCH 3/5] docs: record image hint decision and evidence

---
 docs/doctoring/image-rendering-hints.md | 26 +++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 docs/doctoring/image-rendering-hints.md

diff --git a/docs/doctoring/image-rendering-hints.md b/docs/doctoring/image-rendering-hints.md
new file mode 100644
index 0000000..1bdf61b
--- /dev/null
+++ b/docs/doctoring/image-rendering-hints.md
@@ -0,0 +1,26 @@
+# Image rendering hints
+
+## Decision
+
+The homepage separates image loading, fetch priority, and decode strategy instead of treating them as a single performance switch.
+
+- The single declared Largest Contentful Paint candidate remains eagerly discoverable and uses `fetchpriority="high"`.
+- Eager first-viewport images omit the `decoding` attribute. The HTML Standard defines the missing value as the `auto` state, allowing the user agent to choose its decode behavior.
+- Explicitly lazy-loaded, below-the-fold images retain `decoding="async"`.
+- Automated tests prove that the eager, lazy, and high-priority image sets are non-empty before checking their contracts, preventing vacuous passes.
+
+## Rationale
+
+The `decoding` attribute is a preference hint, not a guarantee that a particular thread or rendering path will be used. Omitting it does not mean synchronous decoding; it selects the standards-defined `auto` state. Likewise, `fetchpriority` affects fetch priority and is independent from image decoding. Therefore this change does not claim a universal LCP improvement from removing `decoding="async"` alone.
+
+The contract is intentionally measurable:
+
+1. Static regression tests verify markup invariants.
+2. Deployment performance should be evaluated separately with repeated field or laboratory measurements, including LCP distributions and representative device/network conditions.
+3. Any future change to preload, lazy loading, or fetch priority must preserve a single explicit LCP candidate unless measurements justify a different strategy.
+
+## References
+
+Osmani, A., Sohoni, L., Meenan, P., & Pollard, B. (2023, November 14). *Optimize resource loading with the Fetch Priority API*. web.dev. https://web.dev/articles/fetch-priority
+
+WHATWG. (2026, July 20). *HTML living standard: The img element*. https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element

From 795d37b00bfcbde3f47323b1b1464aabaa276b3c Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 6 Aug 2026 00:06:46 +0900
Subject: [PATCH 4/5] docs: correct image decoding performance claims

---
 .jules/bolt.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.jules/bolt.md b/.jules/bolt.md
index d3a0f65..65f2457 100644
--- a/.jules/bolt.md
+++ b/.jules/bolt.md
@@ -13,6 +13,6 @@
 **Learning:** 애플리케이션이 `textContent`와 같은 안전한 DOM API만 사용하고 `innerHTML` 등의 위험한 싱크를 사용하지 않는다면 DOMPurify와 같은 라이브러리를 통해 Trusted Types 정책을 생성할 필요가 없음.
 **Action:** 불필요한 번들 다운로드 및 스크립트 실행을 방지하기 위해 사용하지 않는 라이브러리를 식별하고 제거할 것.
 
-## 2026-08-05 - LCP (Largest Contentful Paint) Image Optimization
-**Learning:** Adding `decoding="async"` to critical above-the-fold LCP SVG images delays their rendering and degrades the LCP metric, as the browser shifts decoding to a background thread instead of processing them immediately alongside the main content.
-**Action:** Remove `decoding="async"` from non-lazy loaded critical images (like the top logo and hero graphics) while maintaining it on `loading="lazy"` off-screen images to prioritize main thread rendering speed.
+## 2026-08-05 - Separate image fetch and decode hints
+**Learning:** The HTML Standard defines `decoding` as a preference hint whose missing-value default is `auto`; it does not guarantee a particular main-thread or background-thread execution path. `fetchpriority` independently influences fetch priority. Removing `decoding="async"` must therefore not be described as a guaranteed LCP improvement.
+**Action:** Let eager first-viewport images use the user agent's `auto` decode strategy, retain `decoding="async"` for explicitly lazy images, and require non-vacuous tests for eager, lazy, and single high-priority LCP-candidate sets. Record the evidence and measurement limits in `docs/doctoring/image-rendering-hints.md`.

From f0c0b4d0c499f8aef32baaee8954aa754a73eb7f Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 6 Aug 2026 00:07:09 +0900
Subject: [PATCH 5/5] docs: bound image rendering claims to measured evidence

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49eae22..9bb1089 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,7 +1,7 @@
 # CHANGELOG
 
 ## [Unreleased]
-- **성능 최적화**: LCP(Largest Contentful Paint) 개선을 위해 화면 상단의 주요 SVG 이미지(로고, 히어로 그래픽)에서 `decoding="async"` 속성을 제거하여 백그라운드 스레드 지연 없이 즉시 렌더링되도록 수정했습니다.
+- **렌더링 힌트 정합성**: 첫 화면의 eager 이미지와 단일 LCP 후보에서 강제 `decoding="async"`를 제거해 HTML 표준의 기본 `auto` 판단에 맡기고, 지연 로드 이미지에는 비동기 디코딩 힌트를 유지했습니다. 정적 테스트가 eager, lazy, LCP 후보 집합의 존재와 조합을 검증하며, 실제 LCP 효과는 배포 후 실측 대상으로 유지합니다.
 - **UX/접근성 개선**: 프로젝트 카드의 클릭 영역을 카드 전체로 확장하여 사용자 편의성을 높였습니다. <a> 태그를 확장하는 대신 가상 요소(pseudo-element) 겹침 방식을 사용하여 스크린 리더 접근성을 유지했습니다.
 - **보안 개선**: 컴포넌트 갤러리의 인라인 스크립트와 스타일을 외부 파일로 분리하고, 엄격한 Content-Security-Policy를 적용해 XSS 방어를 강화했습니다.
 - **성능 회귀 복원**: 오프스크린 `.section` 렌더링을 `content-visibility: auto`로 지연하고, 일반 섹션은 600px·콘텐츠가 큰 DIKW/projects 섹션은 1000px의 `contain-intrinsic-size` placeholder를 유지해 초기 렌더링 비용과 스크롤바 이동을 함께 줄였습니다.