fix: align eager, lazy, and LCP image hints with HTML standard

.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 - 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`.

CHANGELOG.md

@@ -1,6 +1,7 @@
 # CHANGELOG
 
 ## [Unreleased]
+- **렌더링 힌트 정합성**: 첫 화면의 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를 유지해 초기 렌더링 비용과 스크롤바 이동을 함께 줄였습니다.

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

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>

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,24 +52,50 @@ 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")
 
     assert "contain-intrinsic-size: 1000px;" in rule
     assert "contain-intrinsic-size: auto 1000px;" in rule
 
 
-def test_images_decode_without_blocking_rendering():
-    """All 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 eager_images, "the initial viewport must contain eager images"
+    assert all(image.get("decoding") is None for image in eager_images)
+
+
+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_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
 
-    assert parser.images
-    assert all(image.get("decoding") == "async" for image in parser.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_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