From 892c83827a1f0fa5d4a70986ed5680e762935ede Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Tue, 22 Sep 2026 20:54:33 +0000
Subject: [PATCH 01/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지
---
 .jules/palette.md                             |   3 +
 src/main/kotlin/html4tree/main.kt             |   6 +-
 src/main/kotlin/html4tree/main.kt.orig        | 529 ++++++++++++++++++
 .../GeneratedIndexReadabilityTest.kt          |   4 +-
 .../GeneratedIndexReadabilityTest.kt.orig     | 199 +++++++
 5 files changed, 736 insertions(+), 5 deletions(-)
 create mode 100644 src/main/kotlin/html4tree/main.kt.orig
 create mode 100644 src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig

diff --git a/.jules/palette.md b/.jules/palette.md
index 604d7810..9609c093 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -73,3 +73,6 @@
 ## 2026-08-17 - 브라우저 번역과 화면 판독기의 호환성을 위한 텍스트 처리
 **Learning:** `aria-label` 속성으로 지정된 화면 판독기용 대체 텍스트는 Chrome Translate 등 브라우저 번역 도구에 의해 번역되지 않는 경우가 많습니다. 이로 인해 문서 언어가 변환되어도 스크린 리더에서는 원본 언어(예: 영어)로 읽혀 다국어 접근성이 저하됩니다.
 **Action:** 화면 판독기를 위한 숨겨진 설명 텍스트를 제공할 때 `aria-label` 대신 CSS `.visually-hidden` 클래스를 적용한 `<span>` 요소를 사용하여, 브라우저가 일반 텍스트로 인식하고 번역할 수 있도록 하여 다국어 접근성 호환성을 확보하십시오.
+## 2024-05-18 - Fix visual hover feedback regression caused by visually-hidden elements
+**Learning:** Using structural pseudo-classes like `:last-child` is fragile when accessibility elements (like `<span class="visually-hidden">`) are added to the end of a container. It breaks visual styles such as hover underlines which target the wrong element.
+**Action:** Use semantic classes (e.g., `.entry-label`) instead of structural pseudo-classes to reliably target visible elements for styling.
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index 0972fa2c..3bfcbfe1 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -56,7 +56,7 @@ a:hover, a:focus-visible {
   outline: 2px solid #0969da;
   outline-offset: -2px;
 }
-a:hover span:last-child, a:focus-visible span:last-child {
+a:hover .entry-label, a:focus-visible .entry-label {
   text-decoration: underline;
 }
 @media (prefers-reduced-motion: reduce) {
@@ -429,7 +429,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
          <h1>${directoryName.escapeHtml()}</h1>
          <nav aria-label="디렉토리 목록">
          <ul role="list">
-            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
+            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span class="entry-label" aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
 """ 
 
     val index_middle = fun():String{ 
@@ -460,7 +460,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
                   val ariaLabel = "${fileName} ${if (isLinkedDirectory) { "디렉토리" } else { "파일" }}".escapeHtml()
                   val typeLabel = if (isLinkedDirectory) { "디렉토리" } else { "파일" }
                   val icon = if (isLinkedDirectory) { "&#128193;" } else { "&#128196;" }
-                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span>${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
+                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span class="entry-label">${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
                   l.append('\n')
                }
            }
diff --git a/src/main/kotlin/html4tree/main.kt.orig b/src/main/kotlin/html4tree/main.kt.orig
new file mode 100644
index 00000000..8193bb82
--- /dev/null
+++ b/src/main/kotlin/html4tree/main.kt.orig
@@ -0,0 +1,529 @@
+package html4tree
+
+import java.io.File
+import java.security.MessageDigest
+import java.nio.file.Files
+import java.nio.file.LinkOption
+import java.nio.file.StandardCopyOption
+import java.nio.file.attribute.BasicFileAttributes
+import java.util.Base64
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.options.default
+import com.github.ajalt.clikt.parameters.arguments.argument
+import com.github.ajalt.clikt.parameters.types.int
+
+private val CSS_CONTENT = """
+body {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.5;
+  padding: 1rem;
+  color: #1f2328;
+}
+main {
+  max-width: 800px;
+  margin: 0 auto;
+}
+h1 {
+  overflow-wrap: anywhere;
+}
+ul {
+  list-style-type: none;
+  padding-left: 0;
+}
+a.dir-link {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  width: 100%;
+  overflow-wrap: anywhere;
+  box-sizing: border-box;
+}
+.icon {
+  flex-shrink: 0;
+  width: 1.25rem;
+  text-align: center;
+}
+a {
+  padding: 0.75rem 0.5rem;
+  text-decoration: none;
+  color: #0969da;
+  border-radius: 4px;
+  transition: background-color 0.2s ease, outline-color 0.2s ease;
+}
+a:hover, a:focus-visible {
+  background-color: #f6f8fa;
+  outline: 2px solid #0969da;
+  outline-offset: -2px;
+}
+a:hover .entry-label, a:focus-visible .entry-label {
+  text-decoration: underline;
+}
+@media (prefers-reduced-motion: reduce) {
+  a {
+    transition: none;
+  }
+}
+li + li {
+  border-top: 1px solid #d0d7de;
+}
+.empty-dir {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  padding: 0.75rem 0.5rem;
+  color: #656d76;
+  font-style: italic;
+}
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+@media (prefers-color-scheme: dark) {
+  body {
+    background-color: #0d1117;
+    color: #c9d1d9;
+  }
+  a {
+    color: #58a6ff;
+  }
+  a:hover, a:focus-visible {
+    background-color: #161b22;
+    outline-color: #58a6ff;
+  }
+  li + li {
+    border-top-color: #21262d;
+  }
+  .empty-dir {
+    color: #8b949e;
+  }
+}
+""".trimIndent()
+
+private val STYLE_HASH = "sha256-" + Base64.getEncoder().encodeToString(MessageDigest.getInstance("SHA-256").digest(CSS_CONTENT.toByteArray(Charsets.UTF_8)))
+private val FILE_NAME_COMPARATOR = compareBy<File> { it.name }
+
+class Html4tree : CliktCommand() {
+    val maxLevel:Int by option(help="Number of levels deep for which to generate an index.html file", hidden = false).int().default(-1)
+    val topDir: String by argument(help="Top directory to crawl")
+
+    override fun run() {
+        go(topDir, maxLevel)
+    }
+}
+
+fun main(args: Array<String>)  = Html4tree().main(args)
+
+
+internal data class FileIdentity(val key: Any?, val readable: Boolean)
+
+
+internal fun read_file_identity(file: File): FileIdentity {
+    return try {
+        val attrs = Files.readAttributes(file.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
+        FileIdentity(attrs.fileKey(), true)
+    } catch (e: Exception) {
+        FileIdentity(null, false)
+    }
+}
+
+fun go(topDir: String, maxLevel: Int)  {
+    require(topDir.isNotBlank())
+    require(!topDir.contains("..")) { "Path traversal sequences are not allowed." }
+    // 보안 수정: symlink 검사를 우회하는 canonicalFile 대신 absoluteFile을 사용
+    // canonicalFile은 symlink를 대상 경로로 해석하여 이어지는 NOFOLLOW_LINKS 검사를 무력화합니다.
+    val top_dir = File(topDir).absoluteFile.toPath().normalize().toFile()
+
+    // 보안 향상: 시스템 전체 정보 노출 및 리소스 고갈(DoS) 방지를 위해 크로스 플랫폼 방식으로 루트 디렉토리 크롤링을 제한합니다.
+    require(top_dir.parentFile != null) { "Crawling the root directory is not allowed for security reasons" }
+
+    require(Files.isDirectory(top_dir.toPath(), LinkOption.NOFOLLOW_LINKS)) { "Top directory must be an existing non-symlink directory" }
+
+    val ll = LinkedList()
+
+    val topEntry = LinkedListEntry(top_dir,0, read_file_identity(top_dir).key)
+    ll.push(topEntry)
+    crawl_directories(ll, maxLevel)
+}
+
+internal fun crawl_directories(
+    ll: LinkedList,
+    maxLevel: Int,
+    processDirectory: (File, Set<String>, Array<File>?) -> Unit = { file, exclude, files -> process_dir(file, exclude, files) },
+    processIgnoreFile: (File, Array<String>?) -> Set<String> = { file, names -> process_ignore_file(file, names) },
+    listFiles: (File) -> Array<File>? = { it.listFiles() },
+    readAttributes: (File) -> BasicFileAttributes? = {
+        try {
+            Files.readAttributes(it.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
+        } catch (e: Exception) {
+            null
+        }
+    },
+    readIdentity: (File) -> FileIdentity = ::read_file_identity
+) {
+    var lle: LinkedListEntry? = ll.pull()
+
+    while(lle != null){
+        val attrs = readAttributes(lle.file)
+        if (attrs == null || !attrs.isDirectory) {
+            lle = ll.pull()
+            continue
+        }
+
+        val currentIdentity = readIdentity(lle.file)
+        if (!currentIdentity.readable || (lle.fileKey != null && currentIdentity.key != lle.fileKey)) {
+            lle = ll.pull()
+            continue
+        }
+
+        val currentLevel: Int = lle.level
+
+        // ⚡ Bolt Performance Optimization: 디렉토리 목록을 캐싱하여 중복된 I/O 시스템 호출을 줄임
+        val dirFiles = listFiles(lle.file)
+
+        // The path can be replaced between the initial identity check and
+        // directory enumeration. Do not process or enqueue children from a
+        // snapshot whose post-listing identity is unreadable or different.
+        val postListingIdentity = readIdentity(lle.file)
+        if (!postListingIdentity.readable || currentIdentity.key != postListingIdentity.key) {
+            lle = ll.pull()
+            continue
+        }
+
+        val dirFilesNames = dirFiles?.let { files ->
+            Array(files.size) { index -> files[index].name }
+        }
+        val exclude = processIgnoreFile(lle.file, dirFilesNames)
+
+        if(maxLevel == -1 || currentLevel <= maxLevel)
+           processDirectory(lle.file, exclude, dirFiles)
+
+        if(maxLevel == -1 || currentLevel < maxLevel) {
+            dirFiles?.forEach {
+                // ⚡ Bolt Performance Optimization: Short-circuit OS stat calls
+                // by checking cheap in-memory string exclusion rules first
+                if(!it.name.isHiddenFile() && it.name !in exclude) {
+                    val childAttrs = readAttributes(it)
+                    if(childAttrs != null && childAttrs.isDirectory && !childAttrs.isSymbolicLink) {
+                        val childEntry = LinkedListEntry(it, currentLevel+1, readIdentity(it).key)
+                        ll.push(childEntry)
+                    }
+                }
+            }
+        }
+        lle = ll.pull()
+    }
+}
+
+fun String.isHiddenFile(): Boolean {
+    return when (firstOrNull()) {
+        '.', '\u3002', '\uFF0E', '\uFF61' -> true
+        else -> false
+    }
+}
+
+// ⚡ Bolt Performance Optimization: Single-pass loop with lazy StringBuilder
+// Chained `.replace()` calls allocate multiple intermediate strings.
+// A single pass over the string lazily allocating a StringBuilder is much faster.
+fun String.escapeHtml(): String {
+    var sb: StringBuilder? = null
+    for (i in 0 until this.length) {
+        val c = this[i]
+        val replacement = when (c) {
+            '&' -> "&amp;"
+            '<' -> "&lt;"
+            '>' -> "&gt;"
+            '"' -> "&quot;"
+            '\'' -> "&#x27;"
+            '`' -> "&#x60;"
+            else -> null
+        }
+        if (replacement != null) {
+            if (sb == null) {
+                sb = StringBuilder(this.length + 16)
+                sb.append(this as CharSequence, 0, i)
+            }
+            sb.append(replacement)
+        } else {
+            sb?.append(c)
+        }
+    }
+    return sb?.toString() ?: this
+}
+
+fun String.urlEncodePath(): String {
+    val bytes = this.toByteArray(Charsets.UTF_8)
+    var encoded: StringBuilder? = null
+    for (i in bytes.indices) {
+        val byte = bytes[i].toInt() and 0xff
+        val isUnreserved = (byte in 'A'.toInt()..'Z'.toInt()) ||
+                           (byte in 'a'.toInt()..'z'.toInt()) ||
+                           (byte in '0'.toInt()..'9'.toInt()) ||
+                           byte == '-'.toInt() ||
+                           byte == '.'.toInt() ||
+                           byte == '_'.toInt() ||
+                           byte == '~'.toInt()
+        if (isUnreserved) {
+            encoded?.append(byte.toChar())
+        } else {
+            var builder = encoded
+            if (builder == null) {
+                builder = StringBuilder(bytes.size + 16)
+                for (j in 0 until i) {
+                    builder.append((bytes[j].toInt() and 0xff).toChar())
+                }
+                encoded = builder
+            }
+            // ⚡ Bolt Performance Optimization: Direct character mapping
+            // Avoids multiple string allocations (toString, padStart, toUpperCase) per reserved byte.
+            builder.append('%')
+            val hex1 = byte ushr 4
+            val hex2 = byte and 0xf
+            builder.append(if (hex1 < 10) (hex1 + 48).toChar() else (hex1 + 55).toChar())
+            builder.append(if (hex2 < 10) (hex2 + 48).toChar() else (hex2 + 55).toChar())
+        }
+    }
+    return encoded?.toString() ?: this
+}
+
+fun process_ignore_file(curr_dir: File, dirFilesNames: Array<String>? = null): Set<String> {
+
+    val ignore_filename = ".html4ignore"
+
+    val ignore_file_path = curr_dir.getAbsolutePath()+"/"+ignore_filename
+
+    val ignore_file = File(ignore_file_path)
+
+    val files_to_exclude = mutableSetOf<String>()
+
+    // 보안 향상: .html4ignore 파일이 일반 파일인지 확인하고, 심볼릭 링크인 경우 무시하여 DoS 및 경로 조작을 방지합니다.
+    // 보안 향상: 파일 크기(1MB 제한) 및 줄 수(1000줄), 정규식 길이(100자)를 제한하여 ReDoS 및 메모리 고갈(OOM) 방지
+    // 보안 향상: 권한이 없는 파일 접근 시 발생하는 예외(DoS)를 방지하기 위해 canRead() 추가 확인
+    if(ignore_file.isFile && !Files.isSymbolicLink(ignore_file.toPath()) && ignore_file.canRead() && ignore_file.length() <= 1048576){
+       val ignored_matchers = mutableListOf<java.nio.file.PathMatcher>()
+
+       ignore_file.useLines { lines ->
+           for ((lineIndex, it) in lines.withIndex()) {
+               // 줄 수 제한이 패턴 수도 함께 상한(줄당 최대 1개 패턴)하므로 별도 패턴 카운터는 불필요
+               if (lineIndex >= 1000) break
+               val pattern = it.trim()
+               if (pattern.isNotEmpty() && pattern.length <= 100) {
+                   try {
+                       ignored_matchers.add(java.nio.file.FileSystems.getDefault().getPathMatcher("glob:$pattern"))
+                   } catch (_: IllegalArgumentException) {
+                   }
+               }
+           }
+       }
+
+       // ⚡ Bolt Performance Optimization: 디렉토리 목록을 Set에 추가하기 위해 필터링만 할 때는 정렬이 불필요하므로 .sorted()를 제거하여 O(N log N) 오버헤드를 방지합니다.
+       val list = dirFilesNames ?: curr_dir.list()
+       list?.forEach {
+           val current = it
+           val pathCurrent = try {
+               java.nio.file.Paths.get(current)
+           } catch (_: java.nio.file.InvalidPathException) {
+               files_to_exclude.add(current)
+               return@forEach
+           }
+           for (matcher in ignored_matchers) {
+              if (matcher.matches(pathCurrent)) {
+                 files_to_exclude.add(current)
+                 break
+              }
+           }
+       }
+    }
+
+    if ("index.html" !in files_to_exclude)
+       files_to_exclude.add("index.html")
+
+    // ⚡ Bolt Performance Optimization: Extract static list to prevent redundant allocations per directory
+    // 보안 향상: 민감한 시스템, 설정, 시크릿 파일을 디렉토리 목록에서 기본적으로 제외하여 정보 노출(Information Exposure) 방지
+    files_to_exclude.addAll(Constants.defaultSensitiveFiles)
+
+    // 보안 향상: dot-like prefixes and case variants of known sensitive names are excluded.
+    (dirFilesNames ?: curr_dir.list())?.forEach {
+        val normalizedName = it.toLowerCase(java.util.Locale.ROOT)
+        if (
+            it.isHiddenFile() ||
+            normalizedName in Constants.defaultSensitiveFileNamesLowercase ||
+            normalizedName.endsWith("~") ||
+            Constants.defaultSensitiveExtensions.any { extension ->
+                normalizedName.endsWith(extension)
+            }
+        ) {
+            files_to_exclude.add(it)
+        }
+    }
+
+    return files_to_exclude
+}
+
+fun write_index_file(
+    curr_dir: File,
+    content: String,
+    moveFile: (
+        java.nio.file.Path,
+        java.nio.file.Path,
+        Array<out java.nio.file.CopyOption>
+    ) -> Unit = { source, target, options ->
+        Files.move(source, target, *options)
+        Unit
+    }
+) {
+    val indexPath = curr_dir.toPath().resolve("index.html")
+    val tempPath = Files.createTempFile(curr_dir.toPath(), ".index-", ".html")
+    try {
+        Files.write(tempPath, content.toByteArray(Charsets.UTF_8))
+        try {
+            // With ATOMIC_MOVE, Java ignores every other copy option and the
+            // existing-target policy is provider-specific.
+            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.ATOMIC_MOVE))
+        } catch (error: java.io.IOException) {
+            if (
+                error !is java.nio.file.AtomicMoveNotSupportedException &&
+                error !is java.nio.file.FileAlreadyExistsException
+            ) {
+                throw error
+            }
+            // This compatibility fallback preserves replacement semantics but
+            // is explicitly non-atomic.
+            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.REPLACE_EXISTING))
+        }
+    } finally {
+        Files.deleteIfExists(tempPath)
+    }
+}
+
+fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array<File>? = null){
+
+    val exclude: Set<String> = excludeSet ?: process_ignore_file(curr_dir)
+    val directoryName = curr_dir.name.ifEmpty { "Root" }
+
+    val index_top = """<!doctype html>
+<html lang="ko">
+     <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <meta name="color-scheme" content="light dark">
+        <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
+        <meta name="theme-color" content="#0d1117" media="(prefers-color-scheme: dark)">
+        <!-- 보안 향상: 인라인 스크립트 실행 방지 -->
+        <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src '${STYLE_HASH}'; base-uri 'none'; form-action 'none';">
+        <!-- 보안 향상: 리퍼러를 통한 디렉토리 경로 노출 방지 -->
+        <meta name="referrer" content="no-referrer">
+        <meta name="robots" content="noindex, nofollow">
+        <title>${directoryName.escapeHtml()} - 디렉토리 목록</title>
+        <style>${CSS_CONTENT}</style>
+     </head>
+     <body>
+       <main>
+         <h1>${directoryName.escapeHtml()}</h1>
+         <nav aria-label="디렉토리 목록">
+         <ul role="list">
+            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span class="entry-label" aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
+"""
+
+    val index_middle = fun():String{
+        val l = StringBuilder()
+
+        val filesList = dirFiles ?: curr_dir.listFiles()
+        // ⚡ Bolt Performance Optimization: Use Array clone instead of toMutableList
+        // toMutableList() allocates a new ArrayList and a backing object array, whereas clone() only allocates a new array.
+        val dir_files: Array<File> = filesList?.clone() ?: emptyArray()
+        dir_files.sortWith(FILE_NAME_COMPARATOR)
+        dir_files.forEach {
+           val fileName = it.getName()
+           // ⚡ Bolt Performance Optimization: Short-circuit string match before expensive OS filesystem calls
+           // 🛡️ Sentinel: Ignore hidden files/directories to prevent sensitive data exposure
+           if (!fileName.isHiddenFile() && fileName !in exclude) {
+               var isLinkedDirectory = false
+               var isSymbolicLink = false
+               try {
+                   // ⚡ Bolt Performance Optimization: Replace 3 separate OS stat calls (isDirectory, it.isDirectory(), isSymbolicLink)
+                   // with a single readAttributes call to reduce I/O overhead.
+                   val attrs = Files.readAttributes(it.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
+                   isLinkedDirectory = attrs.isDirectory
+                   isSymbolicLink = attrs.isSymbolicLink
+               } catch (e: Exception) {
+               }
+               if (!isSymbolicLink) {
+                  val encodedHref = if (isLinkedDirectory) { "./${fileName.urlEncodePath()}/" } else { "./${fileName.urlEncodePath()}" }
+                  val ariaLabel = "${fileName} ${if (isLinkedDirectory) { "디렉토리" } else { "파일" }}".escapeHtml()
+                  val typeLabel = if (isLinkedDirectory) { "디렉토리" } else { "파일" }
+                  val icon = if (isLinkedDirectory) { "&#128193;" } else { "&#128196;" }
+                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span>${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
+                  l.append('\n')
+               }
+           }
+        }
+
+        if(l.isEmpty()){
+            l.append("""          <li><div class="empty-dir" role="status"><span class="icon" aria-hidden="true">&#128194;</span> <span>이 디렉토리는 비어 있습니다.</span></div></li>""")
+            l.append('\n')
+        }
+
+        return l.toString();
+     }
+
+   val index_bottom="""
+         </ul>
+         </nav>
+       </main>
+    </body>
+</html>
+"""
+
+   try {
+       write_index_file(curr_dir, index_top+index_middle()+index_bottom)
+   } catch (e: Exception) {
+       // 보안 향상: 디렉토리에 쓰기 권한이 없거나 파일 시스템 오류가 발생했을 때
+       // 전체 크롤링(프로세스)이 중단되는 DoS를 방지합니다. (Fail Securely)
+   }
+
+}
+
+fun help() {
+    println("ERROR: help has not been written yet!")
+}
+
+private object Constants {
+    @JvmField
+    val defaultSensitiveFiles = listOf(".git", ".env", ".ssh", ".htpasswd", ".htaccess", "id_rsa", "id_ed25519", "secrets.yml", ".html4ignore", ".DS_Store", ".aws", ".kube", ".npmrc", ".gnupg", "config.json", "credentials.json")
+
+    @JvmField
+    val defaultSensitiveFileNamesLowercase =
+        defaultSensitiveFiles.map { it.toLowerCase(java.util.Locale.ROOT) }.toSet()
+
+    @JvmField
+    val defaultSensitiveExtensions = listOf(
+        ".pem",
+        ".key",
+        ".p12",
+        ".pfx",
+        ".crt",
+        ".cer",
+        ".der",
+        ".keystore",
+        ".truststore",
+        ".jks",
+        ".sqlite",
+        ".db",
+        ".bak",
+        ".sql",
+        ".pcap",
+        ".pcapng",
+        ".log",
+        ".swp",
+        ".swo",
+        ".swpx"
+    )
+}
diff --git a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
index 5897ce6d..0bcb8b58 100644
--- a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
+++ b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
@@ -44,7 +44,7 @@ class GeneratedIndexReadabilityTest {
         )
 
         val generatedHtml = generatedHtml()
-        val parentIndex = generatedHtml.indexOf("<span aria-hidden=\"true\">..</span>")
+        val parentIndex = generatedHtml.indexOf("<span class=\"entry-label\" aria-hidden=\"true\">..</span>")
         val firstIndex = generatedHtml.indexOf("alpha.txt")
         val middleIndex = generatedHtml.indexOf("middle.txt")
         val lastIndex = generatedHtml.indexOf("zulu.txt")
@@ -147,7 +147,7 @@ class GeneratedIndexReadabilityTest {
         assertTrue(
             style.contains(
                 """
-                a:hover span:last-child, a:focus-visible span:last-child {
+                a:hover .entry-label, a:focus-visible .entry-label {
                   text-decoration: underline;
                 }
                 """.trimIndent()
diff --git a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig
new file mode 100644
index 00000000..db710138
--- /dev/null
+++ b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig
@@ -0,0 +1,199 @@
+package html4tree
+
+import org.junit.After
+import org.junit.Before
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+import kotlin.math.pow
+import kotlin.test.assertFalse
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+/**
+ * Product-level regressions for the CSS and markup emitted into a generated
+ * directory index.
+ *
+ * These tests inspect the real `index.html` output rather than an independent
+ * stylesheet fixture, so a template or CSP-byte regression cannot be hidden by
+ * a test-only copy of the CSS.
+ */
+class GeneratedIndexReadabilityTest {
+    private lateinit var temporaryDirectory: File
+
+    @Before
+    fun createTemporaryDirectory() {
+        temporaryDirectory = Files.createTempDirectory("html4tree-readability-").toFile()
+    }
+
+    @After
+    fun removeTemporaryDirectory() {
+        temporaryDirectory.deleteRecursively()
+    }
+
+    @Test
+    fun generatedRowsPreserveFirstMiddleAndLastOrder() {
+        val firstFile = File(temporaryDirectory, "alpha.txt").apply { writeText("alpha") }
+        val middleFile = File(temporaryDirectory, "middle.txt").apply { writeText("middle") }
+        val lastFile = File(temporaryDirectory, "zulu.txt").apply { writeText("zulu") }
+
+        process_dir(
+            temporaryDirectory,
+            setOf("index.html"),
+            arrayOf(lastFile, firstFile, middleFile)
+        )
+
+        val generatedHtml = generatedHtml()
+        val parentIndex = generatedHtml.indexOf("<span aria-hidden=\"true\">..</span>")
+        val firstIndex = generatedHtml.indexOf("alpha.txt")
+        val middleIndex = generatedHtml.indexOf("middle.txt")
+        val lastIndex = generatedHtml.indexOf("zulu.txt")
+
+        assertTrue(parentIndex >= 0)
+        assertTrue(parentIndex < firstIndex)
+        assertTrue(firstIndex < middleIndex)
+        assertTrue(middleIndex < lastIndex)
+        assertFalse(generatedHtml.contains("이 디렉토리는 비어 있습니다."))
+    }
+
+    @Test
+    fun emptyDirectoryRetainsOneSemanticStatusRow() {
+        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
+
+        val generatedHtml = generatedHtml()
+        val expectedEmptyRow =
+            """<li><div class="empty-dir" role="status"><span class="icon" aria-hidden="true">&#128194;</span> <span>이 디렉토리는 비어 있습니다.</span></div></li>"""
+
+        assertTrue(generatedHtml.contains(expectedEmptyRow))
+        assertTrue(generatedHtml.indexOf(expectedEmptyRow) == generatedHtml.lastIndexOf(expectedEmptyRow))
+    }
+
+    @Test
+    fun stylesheetSeparatesAdjacentRowsWithoutTrailingBorderRule() {
+        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
+
+        val style = emittedStyle()
+        assertTrue(
+            style.contains(
+                """
+                li + li {
+                  border-top: 1px solid #d0d7de;
+                }
+                """.trimIndent()
+            )
+        )
+        assertFalse(style.contains("li:last-child"))
+    }
+
+    @Test
+    fun linkRowsRetainMobileTouchTargetPadding() {
+        val linkedFile = File(temporaryDirectory, "touch-target.txt").apply { writeText("target") }
+        process_dir(temporaryDirectory, setOf("index.html"), arrayOf(linkedFile))
+
+        assertTrue(generatedHtml().contains("<a class=\"dir-link\""))
+        val style = emittedStyle()
+        assertTrue(
+            style.contains(
+                """
+                a {
+                  padding: 0.75rem 0.5rem;
+                  text-decoration: none;
+                """.trimIndent()
+            )
+        )
+    }
+
+    @Test
+    fun emptyStateUsesExplicitLightAndDarkForegroundColors() {
+        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
+
+        val style = emittedStyle()
+        val baseRule =
+            """
+            .empty-dir {
+              display: flex;
+              align-items: flex-start;
+              gap: 0.5rem;
+              padding: 0.75rem 0.5rem;
+              color: #656d76;
+              font-style: italic;
+            }
+            """.trimIndent()
+        val darkModeMarker = "@media (prefers-color-scheme: dark)"
+        val darkRule = "  .empty-dir {\n    color: #8b949e;\n  }"
+
+        val baseRuleIndex = style.indexOf(baseRule)
+        val darkModeIndex = style.indexOf(darkModeMarker)
+        val darkRuleIndex = style.indexOf(darkRule, startIndex = darkModeIndex.coerceAtLeast(0))
+
+        assertTrue(baseRuleIndex >= 0)
+        assertFalse(style.contains("opacity:"))
+        assertTrue(darkModeIndex > baseRuleIndex)
+        assertTrue(darkRuleIndex > darkModeIndex)
+    }
+
+    @Test
+    fun hoverAndKeyboardFocusUnderlineOnlyLinkText() {
+        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
+
+        val style = emittedStyle()
+        val completeTargetRule = Regex("""a:hover, a:focus-visible \{([\s\S]*?)\}""")
+            .find(style)
+            ?.groupValues
+            ?.get(1)
+        assertNotNull(completeTargetRule)
+        assertFalse(completeTargetRule.contains("text-decoration"))
+        assertTrue(completeTargetRule.contains("outline: 2px solid #0969da;"))
+        assertTrue(
+            style.contains(
+                """
+                a:hover .entry-label, a:focus-visible .entry-label {
+                  text-decoration: underline;
+                }
+                """.trimIndent()
+            )
+        )
+        assertTrue(style.contains("@media (prefers-reduced-motion: reduce)"))
+    }
+
+    @Test
+    fun authoredColorsMeetDocumentedContrastThresholds() {
+        assertTrue(contrastRatio("#656d76", "#ffffff") >= 4.5)
+        assertTrue(contrastRatio("#8b949e", "#0d1117") >= 4.5)
+        assertTrue(contrastRatio("#0969da", "#f6f8fa") >= 3.0)
+        assertTrue(contrastRatio("#58a6ff", "#161b22") >= 3.0)
+    }
+
+    private fun generatedHtml(): String =
+        File(temporaryDirectory, "index.html").readText(Charsets.UTF_8)
+
+    private fun emittedStyle(): String {
+        val style = Regex("""<style>([\s\S]*?)</style>""")
+            .find(generatedHtml())
+            ?.groupValues
+            ?.get(1)
+        return requireNotNull(style) { "Generated HTML must contain one inline style block" }
+    }
+
+    private fun contrastRatio(foreground: String, background: String): Double {
+        val foregroundLuminance = relativeLuminance(foreground)
+        val backgroundLuminance = relativeLuminance(background)
+        val lighter = maxOf(foregroundLuminance, backgroundLuminance)
+        val darker = minOf(foregroundLuminance, backgroundLuminance)
+        return (lighter + 0.05) / (darker + 0.05)
+    }
+
+    private fun relativeLuminance(hexColor: String): Double {
+        val channels = hexColor.removePrefix("#")
+            .chunked(2)
+            .map { it.toInt(16) / 255.0 }
+            .map { channel ->
+                if (channel <= 0.04045) {
+                    channel / 12.92
+                } else {
+                    ((channel + 0.055) / 1.055).pow(2.4)
+                }
+            }
+        return (0.2126 * channels[0]) + (0.7152 * channels[1]) + (0.0722 * channels[2])
+    }
+}

From 7bdb0fc4fad9f74f482cda511911a8e1311d7d69 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 23 Sep 2026 01:03:00 +0000
Subject: [PATCH 02/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지
---
 .jules/palette.md                             |   6 +-
 src/main/kotlin/html4tree/main.kt.orig        | 529 ------------------
 .../GeneratedIndexReadabilityTest.kt.orig     | 199 -------
 3 files changed, 3 insertions(+), 731 deletions(-)
 delete mode 100644 src/main/kotlin/html4tree/main.kt.orig
 delete mode 100644 src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig

diff --git a/.jules/palette.md b/.jules/palette.md
index 9609c093..53270f98 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -73,6 +73,6 @@
 ## 2026-08-17 - 브라우저 번역과 화면 판독기의 호환성을 위한 텍스트 처리
 **Learning:** `aria-label` 속성으로 지정된 화면 판독기용 대체 텍스트는 Chrome Translate 등 브라우저 번역 도구에 의해 번역되지 않는 경우가 많습니다. 이로 인해 문서 언어가 변환되어도 스크린 리더에서는 원본 언어(예: 영어)로 읽혀 다국어 접근성이 저하됩니다.
 **Action:** 화면 판독기를 위한 숨겨진 설명 텍스트를 제공할 때 `aria-label` 대신 CSS `.visually-hidden` 클래스를 적용한 `<span>` 요소를 사용하여, 브라우저가 일반 텍스트로 인식하고 번역할 수 있도록 하여 다국어 접근성 호환성을 확보하십시오.
-## 2024-05-18 - Fix visual hover feedback regression caused by visually-hidden elements
-**Learning:** Using structural pseudo-classes like `:last-child` is fragile when accessibility elements (like `<span class="visually-hidden">`) are added to the end of a container. It breaks visual styles such as hover underlines which target the wrong element.
-**Action:** Use semantic classes (e.g., `.entry-label`) instead of structural pseudo-classes to reliably target visible elements for styling.
+## 2024-05-18 - 시각적으로 숨겨진 요소로 인해 발생하는 시각적 Hover 피드백 회귀 수정
+**Learning:** 접근성 개선을 위해 컨테이너의 마지막에 `<span class="visually-hidden">`과 같은 요소를 추가할 때 `:last-child`와 같은 구조적 가상 클래스를 사용하는 것은 위험합니다. 잘못된 요소에 스타일이 적용되어 hover 시 밑줄과 같은 시각적 효과가 깨질 수 있습니다.
+**Action:** 구조적 가상 클래스 대신 시맨틱 클래스(예: `.entry-label`)를 사용하여 렌더링되는 시각적 요소를 안정적으로 타겟팅하고 스타일을 적용해야 합니다.
diff --git a/src/main/kotlin/html4tree/main.kt.orig b/src/main/kotlin/html4tree/main.kt.orig
deleted file mode 100644
index 8193bb82..00000000
--- a/src/main/kotlin/html4tree/main.kt.orig
+++ /dev/null
@@ -1,529 +0,0 @@
-package html4tree
-
-import java.io.File
-import java.security.MessageDigest
-import java.nio.file.Files
-import java.nio.file.LinkOption
-import java.nio.file.StandardCopyOption
-import java.nio.file.attribute.BasicFileAttributes
-import java.util.Base64
-import com.github.ajalt.clikt.core.CliktCommand
-import com.github.ajalt.clikt.parameters.options.option
-import com.github.ajalt.clikt.parameters.options.default
-import com.github.ajalt.clikt.parameters.arguments.argument
-import com.github.ajalt.clikt.parameters.types.int
-
-private val CSS_CONTENT = """
-body {
-  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-  line-height: 1.5;
-  padding: 1rem;
-  color: #1f2328;
-}
-main {
-  max-width: 800px;
-  margin: 0 auto;
-}
-h1 {
-  overflow-wrap: anywhere;
-}
-ul {
-  list-style-type: none;
-  padding-left: 0;
-}
-a.dir-link {
-  display: flex;
-  align-items: flex-start;
-  gap: 0.5rem;
-  width: 100%;
-  overflow-wrap: anywhere;
-  box-sizing: border-box;
-}
-.icon {
-  flex-shrink: 0;
-  width: 1.25rem;
-  text-align: center;
-}
-a {
-  padding: 0.75rem 0.5rem;
-  text-decoration: none;
-  color: #0969da;
-  border-radius: 4px;
-  transition: background-color 0.2s ease, outline-color 0.2s ease;
-}
-a:hover, a:focus-visible {
-  background-color: #f6f8fa;
-  outline: 2px solid #0969da;
-  outline-offset: -2px;
-}
-a:hover .entry-label, a:focus-visible .entry-label {
-  text-decoration: underline;
-}
-@media (prefers-reduced-motion: reduce) {
-  a {
-    transition: none;
-  }
-}
-li + li {
-  border-top: 1px solid #d0d7de;
-}
-.empty-dir {
-  display: flex;
-  align-items: flex-start;
-  gap: 0.5rem;
-  padding: 0.75rem 0.5rem;
-  color: #656d76;
-  font-style: italic;
-}
-.visually-hidden {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  margin: -1px;
-  padding: 0;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
-@media (prefers-color-scheme: dark) {
-  body {
-    background-color: #0d1117;
-    color: #c9d1d9;
-  }
-  a {
-    color: #58a6ff;
-  }
-  a:hover, a:focus-visible {
-    background-color: #161b22;
-    outline-color: #58a6ff;
-  }
-  li + li {
-    border-top-color: #21262d;
-  }
-  .empty-dir {
-    color: #8b949e;
-  }
-}
-""".trimIndent()
-
-private val STYLE_HASH = "sha256-" + Base64.getEncoder().encodeToString(MessageDigest.getInstance("SHA-256").digest(CSS_CONTENT.toByteArray(Charsets.UTF_8)))
-private val FILE_NAME_COMPARATOR = compareBy<File> { it.name }
-
-class Html4tree : CliktCommand() {
-    val maxLevel:Int by option(help="Number of levels deep for which to generate an index.html file", hidden = false).int().default(-1)
-    val topDir: String by argument(help="Top directory to crawl")
-
-    override fun run() {
-        go(topDir, maxLevel)
-    }
-}
-
-fun main(args: Array<String>)  = Html4tree().main(args)
-
-
-internal data class FileIdentity(val key: Any?, val readable: Boolean)
-
-
-internal fun read_file_identity(file: File): FileIdentity {
-    return try {
-        val attrs = Files.readAttributes(file.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
-        FileIdentity(attrs.fileKey(), true)
-    } catch (e: Exception) {
-        FileIdentity(null, false)
-    }
-}
-
-fun go(topDir: String, maxLevel: Int)  {
-    require(topDir.isNotBlank())
-    require(!topDir.contains("..")) { "Path traversal sequences are not allowed." }
-    // 보안 수정: symlink 검사를 우회하는 canonicalFile 대신 absoluteFile을 사용
-    // canonicalFile은 symlink를 대상 경로로 해석하여 이어지는 NOFOLLOW_LINKS 검사를 무력화합니다.
-    val top_dir = File(topDir).absoluteFile.toPath().normalize().toFile()
-
-    // 보안 향상: 시스템 전체 정보 노출 및 리소스 고갈(DoS) 방지를 위해 크로스 플랫폼 방식으로 루트 디렉토리 크롤링을 제한합니다.
-    require(top_dir.parentFile != null) { "Crawling the root directory is not allowed for security reasons" }
-
-    require(Files.isDirectory(top_dir.toPath(), LinkOption.NOFOLLOW_LINKS)) { "Top directory must be an existing non-symlink directory" }
-
-    val ll = LinkedList()
-
-    val topEntry = LinkedListEntry(top_dir,0, read_file_identity(top_dir).key)
-    ll.push(topEntry)
-    crawl_directories(ll, maxLevel)
-}
-
-internal fun crawl_directories(
-    ll: LinkedList,
-    maxLevel: Int,
-    processDirectory: (File, Set<String>, Array<File>?) -> Unit = { file, exclude, files -> process_dir(file, exclude, files) },
-    processIgnoreFile: (File, Array<String>?) -> Set<String> = { file, names -> process_ignore_file(file, names) },
-    listFiles: (File) -> Array<File>? = { it.listFiles() },
-    readAttributes: (File) -> BasicFileAttributes? = {
-        try {
-            Files.readAttributes(it.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
-        } catch (e: Exception) {
-            null
-        }
-    },
-    readIdentity: (File) -> FileIdentity = ::read_file_identity
-) {
-    var lle: LinkedListEntry? = ll.pull()
-
-    while(lle != null){
-        val attrs = readAttributes(lle.file)
-        if (attrs == null || !attrs.isDirectory) {
-            lle = ll.pull()
-            continue
-        }
-
-        val currentIdentity = readIdentity(lle.file)
-        if (!currentIdentity.readable || (lle.fileKey != null && currentIdentity.key != lle.fileKey)) {
-            lle = ll.pull()
-            continue
-        }
-
-        val currentLevel: Int = lle.level
-
-        // ⚡ Bolt Performance Optimization: 디렉토리 목록을 캐싱하여 중복된 I/O 시스템 호출을 줄임
-        val dirFiles = listFiles(lle.file)
-
-        // The path can be replaced between the initial identity check and
-        // directory enumeration. Do not process or enqueue children from a
-        // snapshot whose post-listing identity is unreadable or different.
-        val postListingIdentity = readIdentity(lle.file)
-        if (!postListingIdentity.readable || currentIdentity.key != postListingIdentity.key) {
-            lle = ll.pull()
-            continue
-        }
-
-        val dirFilesNames = dirFiles?.let { files ->
-            Array(files.size) { index -> files[index].name }
-        }
-        val exclude = processIgnoreFile(lle.file, dirFilesNames)
-
-        if(maxLevel == -1 || currentLevel <= maxLevel)
-           processDirectory(lle.file, exclude, dirFiles)
-
-        if(maxLevel == -1 || currentLevel < maxLevel) {
-            dirFiles?.forEach {
-                // ⚡ Bolt Performance Optimization: Short-circuit OS stat calls
-                // by checking cheap in-memory string exclusion rules first
-                if(!it.name.isHiddenFile() && it.name !in exclude) {
-                    val childAttrs = readAttributes(it)
-                    if(childAttrs != null && childAttrs.isDirectory && !childAttrs.isSymbolicLink) {
-                        val childEntry = LinkedListEntry(it, currentLevel+1, readIdentity(it).key)
-                        ll.push(childEntry)
-                    }
-                }
-            }
-        }
-        lle = ll.pull()
-    }
-}
-
-fun String.isHiddenFile(): Boolean {
-    return when (firstOrNull()) {
-        '.', '\u3002', '\uFF0E', '\uFF61' -> true
-        else -> false
-    }
-}
-
-// ⚡ Bolt Performance Optimization: Single-pass loop with lazy StringBuilder
-// Chained `.replace()` calls allocate multiple intermediate strings.
-// A single pass over the string lazily allocating a StringBuilder is much faster.
-fun String.escapeHtml(): String {
-    var sb: StringBuilder? = null
-    for (i in 0 until this.length) {
-        val c = this[i]
-        val replacement = when (c) {
-            '&' -> "&amp;"
-            '<' -> "&lt;"
-            '>' -> "&gt;"
-            '"' -> "&quot;"
-            '\'' -> "&#x27;"
-            '`' -> "&#x60;"
-            else -> null
-        }
-        if (replacement != null) {
-            if (sb == null) {
-                sb = StringBuilder(this.length + 16)
-                sb.append(this as CharSequence, 0, i)
-            }
-            sb.append(replacement)
-        } else {
-            sb?.append(c)
-        }
-    }
-    return sb?.toString() ?: this
-}
-
-fun String.urlEncodePath(): String {
-    val bytes = this.toByteArray(Charsets.UTF_8)
-    var encoded: StringBuilder? = null
-    for (i in bytes.indices) {
-        val byte = bytes[i].toInt() and 0xff
-        val isUnreserved = (byte in 'A'.toInt()..'Z'.toInt()) ||
-                           (byte in 'a'.toInt()..'z'.toInt()) ||
-                           (byte in '0'.toInt()..'9'.toInt()) ||
-                           byte == '-'.toInt() ||
-                           byte == '.'.toInt() ||
-                           byte == '_'.toInt() ||
-                           byte == '~'.toInt()
-        if (isUnreserved) {
-            encoded?.append(byte.toChar())
-        } else {
-            var builder = encoded
-            if (builder == null) {
-                builder = StringBuilder(bytes.size + 16)
-                for (j in 0 until i) {
-                    builder.append((bytes[j].toInt() and 0xff).toChar())
-                }
-                encoded = builder
-            }
-            // ⚡ Bolt Performance Optimization: Direct character mapping
-            // Avoids multiple string allocations (toString, padStart, toUpperCase) per reserved byte.
-            builder.append('%')
-            val hex1 = byte ushr 4
-            val hex2 = byte and 0xf
-            builder.append(if (hex1 < 10) (hex1 + 48).toChar() else (hex1 + 55).toChar())
-            builder.append(if (hex2 < 10) (hex2 + 48).toChar() else (hex2 + 55).toChar())
-        }
-    }
-    return encoded?.toString() ?: this
-}
-
-fun process_ignore_file(curr_dir: File, dirFilesNames: Array<String>? = null): Set<String> {
-
-    val ignore_filename = ".html4ignore"
-
-    val ignore_file_path = curr_dir.getAbsolutePath()+"/"+ignore_filename
-
-    val ignore_file = File(ignore_file_path)
-
-    val files_to_exclude = mutableSetOf<String>()
-
-    // 보안 향상: .html4ignore 파일이 일반 파일인지 확인하고, 심볼릭 링크인 경우 무시하여 DoS 및 경로 조작을 방지합니다.
-    // 보안 향상: 파일 크기(1MB 제한) 및 줄 수(1000줄), 정규식 길이(100자)를 제한하여 ReDoS 및 메모리 고갈(OOM) 방지
-    // 보안 향상: 권한이 없는 파일 접근 시 발생하는 예외(DoS)를 방지하기 위해 canRead() 추가 확인
-    if(ignore_file.isFile && !Files.isSymbolicLink(ignore_file.toPath()) && ignore_file.canRead() && ignore_file.length() <= 1048576){
-       val ignored_matchers = mutableListOf<java.nio.file.PathMatcher>()
-
-       ignore_file.useLines { lines ->
-           for ((lineIndex, it) in lines.withIndex()) {
-               // 줄 수 제한이 패턴 수도 함께 상한(줄당 최대 1개 패턴)하므로 별도 패턴 카운터는 불필요
-               if (lineIndex >= 1000) break
-               val pattern = it.trim()
-               if (pattern.isNotEmpty() && pattern.length <= 100) {
-                   try {
-                       ignored_matchers.add(java.nio.file.FileSystems.getDefault().getPathMatcher("glob:$pattern"))
-                   } catch (_: IllegalArgumentException) {
-                   }
-               }
-           }
-       }
-
-       // ⚡ Bolt Performance Optimization: 디렉토리 목록을 Set에 추가하기 위해 필터링만 할 때는 정렬이 불필요하므로 .sorted()를 제거하여 O(N log N) 오버헤드를 방지합니다.
-       val list = dirFilesNames ?: curr_dir.list()
-       list?.forEach {
-           val current = it
-           val pathCurrent = try {
-               java.nio.file.Paths.get(current)
-           } catch (_: java.nio.file.InvalidPathException) {
-               files_to_exclude.add(current)
-               return@forEach
-           }
-           for (matcher in ignored_matchers) {
-              if (matcher.matches(pathCurrent)) {
-                 files_to_exclude.add(current)
-                 break
-              }
-           }
-       }
-    }
-
-    if ("index.html" !in files_to_exclude)
-       files_to_exclude.add("index.html")
-
-    // ⚡ Bolt Performance Optimization: Extract static list to prevent redundant allocations per directory
-    // 보안 향상: 민감한 시스템, 설정, 시크릿 파일을 디렉토리 목록에서 기본적으로 제외하여 정보 노출(Information Exposure) 방지
-    files_to_exclude.addAll(Constants.defaultSensitiveFiles)
-
-    // 보안 향상: dot-like prefixes and case variants of known sensitive names are excluded.
-    (dirFilesNames ?: curr_dir.list())?.forEach {
-        val normalizedName = it.toLowerCase(java.util.Locale.ROOT)
-        if (
-            it.isHiddenFile() ||
-            normalizedName in Constants.defaultSensitiveFileNamesLowercase ||
-            normalizedName.endsWith("~") ||
-            Constants.defaultSensitiveExtensions.any { extension ->
-                normalizedName.endsWith(extension)
-            }
-        ) {
-            files_to_exclude.add(it)
-        }
-    }
-
-    return files_to_exclude
-}
-
-fun write_index_file(
-    curr_dir: File,
-    content: String,
-    moveFile: (
-        java.nio.file.Path,
-        java.nio.file.Path,
-        Array<out java.nio.file.CopyOption>
-    ) -> Unit = { source, target, options ->
-        Files.move(source, target, *options)
-        Unit
-    }
-) {
-    val indexPath = curr_dir.toPath().resolve("index.html")
-    val tempPath = Files.createTempFile(curr_dir.toPath(), ".index-", ".html")
-    try {
-        Files.write(tempPath, content.toByteArray(Charsets.UTF_8))
-        try {
-            // With ATOMIC_MOVE, Java ignores every other copy option and the
-            // existing-target policy is provider-specific.
-            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.ATOMIC_MOVE))
-        } catch (error: java.io.IOException) {
-            if (
-                error !is java.nio.file.AtomicMoveNotSupportedException &&
-                error !is java.nio.file.FileAlreadyExistsException
-            ) {
-                throw error
-            }
-            // This compatibility fallback preserves replacement semantics but
-            // is explicitly non-atomic.
-            moveFile(tempPath, indexPath, arrayOf(StandardCopyOption.REPLACE_EXISTING))
-        }
-    } finally {
-        Files.deleteIfExists(tempPath)
-    }
-}
-
-fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array<File>? = null){
-
-    val exclude: Set<String> = excludeSet ?: process_ignore_file(curr_dir)
-    val directoryName = curr_dir.name.ifEmpty { "Root" }
-
-    val index_top = """<!doctype html>
-<html lang="ko">
-     <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <meta name="color-scheme" content="light dark">
-        <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
-        <meta name="theme-color" content="#0d1117" media="(prefers-color-scheme: dark)">
-        <!-- 보안 향상: 인라인 스크립트 실행 방지 -->
-        <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src '${STYLE_HASH}'; base-uri 'none'; form-action 'none';">
-        <!-- 보안 향상: 리퍼러를 통한 디렉토리 경로 노출 방지 -->
-        <meta name="referrer" content="no-referrer">
-        <meta name="robots" content="noindex, nofollow">
-        <title>${directoryName.escapeHtml()} - 디렉토리 목록</title>
-        <style>${CSS_CONTENT}</style>
-     </head>
-     <body>
-       <main>
-         <h1>${directoryName.escapeHtml()}</h1>
-         <nav aria-label="디렉토리 목록">
-         <ul role="list">
-            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span class="entry-label" aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
-"""
-
-    val index_middle = fun():String{
-        val l = StringBuilder()
-
-        val filesList = dirFiles ?: curr_dir.listFiles()
-        // ⚡ Bolt Performance Optimization: Use Array clone instead of toMutableList
-        // toMutableList() allocates a new ArrayList and a backing object array, whereas clone() only allocates a new array.
-        val dir_files: Array<File> = filesList?.clone() ?: emptyArray()
-        dir_files.sortWith(FILE_NAME_COMPARATOR)
-        dir_files.forEach {
-           val fileName = it.getName()
-           // ⚡ Bolt Performance Optimization: Short-circuit string match before expensive OS filesystem calls
-           // 🛡️ Sentinel: Ignore hidden files/directories to prevent sensitive data exposure
-           if (!fileName.isHiddenFile() && fileName !in exclude) {
-               var isLinkedDirectory = false
-               var isSymbolicLink = false
-               try {
-                   // ⚡ Bolt Performance Optimization: Replace 3 separate OS stat calls (isDirectory, it.isDirectory(), isSymbolicLink)
-                   // with a single readAttributes call to reduce I/O overhead.
-                   val attrs = Files.readAttributes(it.toPath(), BasicFileAttributes::class.java, LinkOption.NOFOLLOW_LINKS)
-                   isLinkedDirectory = attrs.isDirectory
-                   isSymbolicLink = attrs.isSymbolicLink
-               } catch (e: Exception) {
-               }
-               if (!isSymbolicLink) {
-                  val encodedHref = if (isLinkedDirectory) { "./${fileName.urlEncodePath()}/" } else { "./${fileName.urlEncodePath()}" }
-                  val ariaLabel = "${fileName} ${if (isLinkedDirectory) { "디렉토리" } else { "파일" }}".escapeHtml()
-                  val typeLabel = if (isLinkedDirectory) { "디렉토리" } else { "파일" }
-                  val icon = if (isLinkedDirectory) { "&#128193;" } else { "&#128196;" }
-                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span>${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
-                  l.append('\n')
-               }
-           }
-        }
-
-        if(l.isEmpty()){
-            l.append("""          <li><div class="empty-dir" role="status"><span class="icon" aria-hidden="true">&#128194;</span> <span>이 디렉토리는 비어 있습니다.</span></div></li>""")
-            l.append('\n')
-        }
-
-        return l.toString();
-     }
-
-   val index_bottom="""
-         </ul>
-         </nav>
-       </main>
-    </body>
-</html>
-"""
-
-   try {
-       write_index_file(curr_dir, index_top+index_middle()+index_bottom)
-   } catch (e: Exception) {
-       // 보안 향상: 디렉토리에 쓰기 권한이 없거나 파일 시스템 오류가 발생했을 때
-       // 전체 크롤링(프로세스)이 중단되는 DoS를 방지합니다. (Fail Securely)
-   }
-
-}
-
-fun help() {
-    println("ERROR: help has not been written yet!")
-}
-
-private object Constants {
-    @JvmField
-    val defaultSensitiveFiles = listOf(".git", ".env", ".ssh", ".htpasswd", ".htaccess", "id_rsa", "id_ed25519", "secrets.yml", ".html4ignore", ".DS_Store", ".aws", ".kube", ".npmrc", ".gnupg", "config.json", "credentials.json")
-
-    @JvmField
-    val defaultSensitiveFileNamesLowercase =
-        defaultSensitiveFiles.map { it.toLowerCase(java.util.Locale.ROOT) }.toSet()
-
-    @JvmField
-    val defaultSensitiveExtensions = listOf(
-        ".pem",
-        ".key",
-        ".p12",
-        ".pfx",
-        ".crt",
-        ".cer",
-        ".der",
-        ".keystore",
-        ".truststore",
-        ".jks",
-        ".sqlite",
-        ".db",
-        ".bak",
-        ".sql",
-        ".pcap",
-        ".pcapng",
-        ".log",
-        ".swp",
-        ".swo",
-        ".swpx"
-    )
-}
diff --git a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig
deleted file mode 100644
index db710138..00000000
--- a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt.orig
+++ /dev/null
@@ -1,199 +0,0 @@
-package html4tree
-
-import org.junit.After
-import org.junit.Before
-import org.junit.Test
-import java.io.File
-import java.nio.file.Files
-import kotlin.math.pow
-import kotlin.test.assertFalse
-import kotlin.test.assertNotNull
-import kotlin.test.assertTrue
-
-/**
- * Product-level regressions for the CSS and markup emitted into a generated
- * directory index.
- *
- * These tests inspect the real `index.html` output rather than an independent
- * stylesheet fixture, so a template or CSP-byte regression cannot be hidden by
- * a test-only copy of the CSS.
- */
-class GeneratedIndexReadabilityTest {
-    private lateinit var temporaryDirectory: File
-
-    @Before
-    fun createTemporaryDirectory() {
-        temporaryDirectory = Files.createTempDirectory("html4tree-readability-").toFile()
-    }
-
-    @After
-    fun removeTemporaryDirectory() {
-        temporaryDirectory.deleteRecursively()
-    }
-
-    @Test
-    fun generatedRowsPreserveFirstMiddleAndLastOrder() {
-        val firstFile = File(temporaryDirectory, "alpha.txt").apply { writeText("alpha") }
-        val middleFile = File(temporaryDirectory, "middle.txt").apply { writeText("middle") }
-        val lastFile = File(temporaryDirectory, "zulu.txt").apply { writeText("zulu") }
-
-        process_dir(
-            temporaryDirectory,
-            setOf("index.html"),
-            arrayOf(lastFile, firstFile, middleFile)
-        )
-
-        val generatedHtml = generatedHtml()
-        val parentIndex = generatedHtml.indexOf("<span aria-hidden=\"true\">..</span>")
-        val firstIndex = generatedHtml.indexOf("alpha.txt")
-        val middleIndex = generatedHtml.indexOf("middle.txt")
-        val lastIndex = generatedHtml.indexOf("zulu.txt")
-
-        assertTrue(parentIndex >= 0)
-        assertTrue(parentIndex < firstIndex)
-        assertTrue(firstIndex < middleIndex)
-        assertTrue(middleIndex < lastIndex)
-        assertFalse(generatedHtml.contains("이 디렉토리는 비어 있습니다."))
-    }
-
-    @Test
-    fun emptyDirectoryRetainsOneSemanticStatusRow() {
-        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
-
-        val generatedHtml = generatedHtml()
-        val expectedEmptyRow =
-            """<li><div class="empty-dir" role="status"><span class="icon" aria-hidden="true">&#128194;</span> <span>이 디렉토리는 비어 있습니다.</span></div></li>"""
-
-        assertTrue(generatedHtml.contains(expectedEmptyRow))
-        assertTrue(generatedHtml.indexOf(expectedEmptyRow) == generatedHtml.lastIndexOf(expectedEmptyRow))
-    }
-
-    @Test
-    fun stylesheetSeparatesAdjacentRowsWithoutTrailingBorderRule() {
-        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
-
-        val style = emittedStyle()
-        assertTrue(
-            style.contains(
-                """
-                li + li {
-                  border-top: 1px solid #d0d7de;
-                }
-                """.trimIndent()
-            )
-        )
-        assertFalse(style.contains("li:last-child"))
-    }
-
-    @Test
-    fun linkRowsRetainMobileTouchTargetPadding() {
-        val linkedFile = File(temporaryDirectory, "touch-target.txt").apply { writeText("target") }
-        process_dir(temporaryDirectory, setOf("index.html"), arrayOf(linkedFile))
-
-        assertTrue(generatedHtml().contains("<a class=\"dir-link\""))
-        val style = emittedStyle()
-        assertTrue(
-            style.contains(
-                """
-                a {
-                  padding: 0.75rem 0.5rem;
-                  text-decoration: none;
-                """.trimIndent()
-            )
-        )
-    }
-
-    @Test
-    fun emptyStateUsesExplicitLightAndDarkForegroundColors() {
-        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
-
-        val style = emittedStyle()
-        val baseRule =
-            """
-            .empty-dir {
-              display: flex;
-              align-items: flex-start;
-              gap: 0.5rem;
-              padding: 0.75rem 0.5rem;
-              color: #656d76;
-              font-style: italic;
-            }
-            """.trimIndent()
-        val darkModeMarker = "@media (prefers-color-scheme: dark)"
-        val darkRule = "  .empty-dir {\n    color: #8b949e;\n  }"
-
-        val baseRuleIndex = style.indexOf(baseRule)
-        val darkModeIndex = style.indexOf(darkModeMarker)
-        val darkRuleIndex = style.indexOf(darkRule, startIndex = darkModeIndex.coerceAtLeast(0))
-
-        assertTrue(baseRuleIndex >= 0)
-        assertFalse(style.contains("opacity:"))
-        assertTrue(darkModeIndex > baseRuleIndex)
-        assertTrue(darkRuleIndex > darkModeIndex)
-    }
-
-    @Test
-    fun hoverAndKeyboardFocusUnderlineOnlyLinkText() {
-        process_dir(temporaryDirectory, setOf("index.html"), emptyArray())
-
-        val style = emittedStyle()
-        val completeTargetRule = Regex("""a:hover, a:focus-visible \{([\s\S]*?)\}""")
-            .find(style)
-            ?.groupValues
-            ?.get(1)
-        assertNotNull(completeTargetRule)
-        assertFalse(completeTargetRule.contains("text-decoration"))
-        assertTrue(completeTargetRule.contains("outline: 2px solid #0969da;"))
-        assertTrue(
-            style.contains(
-                """
-                a:hover .entry-label, a:focus-visible .entry-label {
-                  text-decoration: underline;
-                }
-                """.trimIndent()
-            )
-        )
-        assertTrue(style.contains("@media (prefers-reduced-motion: reduce)"))
-    }
-
-    @Test
-    fun authoredColorsMeetDocumentedContrastThresholds() {
-        assertTrue(contrastRatio("#656d76", "#ffffff") >= 4.5)
-        assertTrue(contrastRatio("#8b949e", "#0d1117") >= 4.5)
-        assertTrue(contrastRatio("#0969da", "#f6f8fa") >= 3.0)
-        assertTrue(contrastRatio("#58a6ff", "#161b22") >= 3.0)
-    }
-
-    private fun generatedHtml(): String =
-        File(temporaryDirectory, "index.html").readText(Charsets.UTF_8)
-
-    private fun emittedStyle(): String {
-        val style = Regex("""<style>([\s\S]*?)</style>""")
-            .find(generatedHtml())
-            ?.groupValues
-            ?.get(1)
-        return requireNotNull(style) { "Generated HTML must contain one inline style block" }
-    }
-
-    private fun contrastRatio(foreground: String, background: String): Double {
-        val foregroundLuminance = relativeLuminance(foreground)
-        val backgroundLuminance = relativeLuminance(background)
-        val lighter = maxOf(foregroundLuminance, backgroundLuminance)
-        val darker = minOf(foregroundLuminance, backgroundLuminance)
-        return (lighter + 0.05) / (darker + 0.05)
-    }
-
-    private fun relativeLuminance(hexColor: String): Double {
-        val channels = hexColor.removePrefix("#")
-            .chunked(2)
-            .map { it.toInt(16) / 255.0 }
-            .map { channel ->
-                if (channel <= 0.04045) {
-                    channel / 12.92
-                } else {
-                    ((channel + 0.055) / 1.055).pow(2.4)
-                }
-            }
-        return (0.2126 * channels[0]) + (0.7152 * channels[1]) + (0.0722 * channels[2])
-    }
-}

From a37fad6d6c3ee1d9e8e49b2f2419b2c40bcd5282 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 23 Sep 2026 06:35:38 +0000
Subject: [PATCH 03/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지

From d9387ecb31947ca09689ca8c5dcb1f20a9f1e968 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 23 Sep 2026 11:39:09 +0000
Subject: [PATCH 04/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지

From f7938ff0701b458b5196d30c115971128f824404 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 24 Sep 2026 01:56:18 +0000
Subject: [PATCH 05/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지

From b5d0c1fa3579908ef6c2af961ee946cfec4f3e7d Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 24 Sep 2026 11:02:20 +0900
Subject: [PATCH 06/10] chore(ui): preserve hover-feedback intent behind #772

---
 .jules/palette.md                                          | 3 ---
 src/main/kotlin/html4tree/main.kt                          | 6 +++---
 src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt | 4 ++--
 3 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index 53270f98..604d7810 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -73,6 +73,3 @@
 ## 2026-08-17 - 브라우저 번역과 화면 판독기의 호환성을 위한 텍스트 처리
 **Learning:** `aria-label` 속성으로 지정된 화면 판독기용 대체 텍스트는 Chrome Translate 등 브라우저 번역 도구에 의해 번역되지 않는 경우가 많습니다. 이로 인해 문서 언어가 변환되어도 스크린 리더에서는 원본 언어(예: 영어)로 읽혀 다국어 접근성이 저하됩니다.
 **Action:** 화면 판독기를 위한 숨겨진 설명 텍스트를 제공할 때 `aria-label` 대신 CSS `.visually-hidden` 클래스를 적용한 `<span>` 요소를 사용하여, 브라우저가 일반 텍스트로 인식하고 번역할 수 있도록 하여 다국어 접근성 호환성을 확보하십시오.
-## 2024-05-18 - 시각적으로 숨겨진 요소로 인해 발생하는 시각적 Hover 피드백 회귀 수정
-**Learning:** 접근성 개선을 위해 컨테이너의 마지막에 `<span class="visually-hidden">`과 같은 요소를 추가할 때 `:last-child`와 같은 구조적 가상 클래스를 사용하는 것은 위험합니다. 잘못된 요소에 스타일이 적용되어 hover 시 밑줄과 같은 시각적 효과가 깨질 수 있습니다.
-**Action:** 구조적 가상 클래스 대신 시맨틱 클래스(예: `.entry-label`)를 사용하여 렌더링되는 시각적 요소를 안정적으로 타겟팅하고 스타일을 적용해야 합니다.
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index 3bfcbfe1..0972fa2c 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -56,7 +56,7 @@ a:hover, a:focus-visible {
   outline: 2px solid #0969da;
   outline-offset: -2px;
 }
-a:hover .entry-label, a:focus-visible .entry-label {
+a:hover span:last-child, a:focus-visible span:last-child {
   text-decoration: underline;
 }
 @media (prefers-reduced-motion: reduce) {
@@ -429,7 +429,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
          <h1>${directoryName.escapeHtml()}</h1>
          <nav aria-label="디렉토리 목록">
          <ul role="list">
-            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span class="entry-label" aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
+            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
 """ 
 
     val index_middle = fun():String{ 
@@ -460,7 +460,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
                   val ariaLabel = "${fileName} ${if (isLinkedDirectory) { "디렉토리" } else { "파일" }}".escapeHtml()
                   val typeLabel = if (isLinkedDirectory) { "디렉토리" } else { "파일" }
                   val icon = if (isLinkedDirectory) { "&#128193;" } else { "&#128196;" }
-                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span class="entry-label">${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
+                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span>${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
                   l.append('\n')
                }
            }
diff --git a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
index 0bcb8b58..5897ce6d 100644
--- a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
+++ b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
@@ -44,7 +44,7 @@ class GeneratedIndexReadabilityTest {
         )
 
         val generatedHtml = generatedHtml()
-        val parentIndex = generatedHtml.indexOf("<span class=\"entry-label\" aria-hidden=\"true\">..</span>")
+        val parentIndex = generatedHtml.indexOf("<span aria-hidden=\"true\">..</span>")
         val firstIndex = generatedHtml.indexOf("alpha.txt")
         val middleIndex = generatedHtml.indexOf("middle.txt")
         val lastIndex = generatedHtml.indexOf("zulu.txt")
@@ -147,7 +147,7 @@ class GeneratedIndexReadabilityTest {
         assertTrue(
             style.contains(
                 """
-                a:hover .entry-label, a:focus-visible .entry-label {
+                a:hover span:last-child, a:focus-visible span:last-child {
                   text-decoration: underline;
                 }
                 """.trimIndent()

From 42dfb78366d2d2d80e6b47463736c2c8746763d5 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 24 Sep 2026 12:40:12 +0000
Subject: [PATCH 07/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지
---
 .jules/palette.md                                          | 3 +++
 src/main/kotlin/html4tree/main.kt                          | 6 +++---
 src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt | 4 ++--
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index 604d7810..53270f98 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -73,3 +73,6 @@
 ## 2026-08-17 - 브라우저 번역과 화면 판독기의 호환성을 위한 텍스트 처리
 **Learning:** `aria-label` 속성으로 지정된 화면 판독기용 대체 텍스트는 Chrome Translate 등 브라우저 번역 도구에 의해 번역되지 않는 경우가 많습니다. 이로 인해 문서 언어가 변환되어도 스크린 리더에서는 원본 언어(예: 영어)로 읽혀 다국어 접근성이 저하됩니다.
 **Action:** 화면 판독기를 위한 숨겨진 설명 텍스트를 제공할 때 `aria-label` 대신 CSS `.visually-hidden` 클래스를 적용한 `<span>` 요소를 사용하여, 브라우저가 일반 텍스트로 인식하고 번역할 수 있도록 하여 다국어 접근성 호환성을 확보하십시오.
+## 2024-05-18 - 시각적으로 숨겨진 요소로 인해 발생하는 시각적 Hover 피드백 회귀 수정
+**Learning:** 접근성 개선을 위해 컨테이너의 마지막에 `<span class="visually-hidden">`과 같은 요소를 추가할 때 `:last-child`와 같은 구조적 가상 클래스를 사용하는 것은 위험합니다. 잘못된 요소에 스타일이 적용되어 hover 시 밑줄과 같은 시각적 효과가 깨질 수 있습니다.
+**Action:** 구조적 가상 클래스 대신 시맨틱 클래스(예: `.entry-label`)를 사용하여 렌더링되는 시각적 요소를 안정적으로 타겟팅하고 스타일을 적용해야 합니다.
diff --git a/src/main/kotlin/html4tree/main.kt b/src/main/kotlin/html4tree/main.kt
index 0972fa2c..3bfcbfe1 100644
--- a/src/main/kotlin/html4tree/main.kt
+++ b/src/main/kotlin/html4tree/main.kt
@@ -56,7 +56,7 @@ a:hover, a:focus-visible {
   outline: 2px solid #0969da;
   outline-offset: -2px;
 }
-a:hover span:last-child, a:focus-visible span:last-child {
+a:hover .entry-label, a:focus-visible .entry-label {
   text-decoration: underline;
 }
 @media (prefers-reduced-motion: reduce) {
@@ -429,7 +429,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
          <h1>${directoryName.escapeHtml()}</h1>
          <nav aria-label="디렉토리 목록">
          <ul role="list">
-            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
+            <li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span class="entry-label" aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
 """ 
 
     val index_middle = fun():String{ 
@@ -460,7 +460,7 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
                   val ariaLabel = "${fileName} ${if (isLinkedDirectory) { "디렉토리" } else { "파일" }}".escapeHtml()
                   val typeLabel = if (isLinkedDirectory) { "디렉토리" } else { "파일" }
                   val icon = if (isLinkedDirectory) { "&#128193;" } else { "&#128196;" }
-                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span>${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
+                  l.append("""          <li><a class="dir-link" href="${encodedHref}" title="${ariaLabel}"><span class="icon" aria-hidden="true">${icon}</span> <span class="entry-label">${fileName.escapeHtml()}</span> <span class="visually-hidden">${typeLabel}</span></a></li>""")
                   l.append('\n')
                }
            }
diff --git a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
index 5897ce6d..0bcb8b58 100644
--- a/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
+++ b/src/test/kotlin/html4tree/GeneratedIndexReadabilityTest.kt
@@ -44,7 +44,7 @@ class GeneratedIndexReadabilityTest {
         )
 
         val generatedHtml = generatedHtml()
-        val parentIndex = generatedHtml.indexOf("<span aria-hidden=\"true\">..</span>")
+        val parentIndex = generatedHtml.indexOf("<span class=\"entry-label\" aria-hidden=\"true\">..</span>")
         val firstIndex = generatedHtml.indexOf("alpha.txt")
         val middleIndex = generatedHtml.indexOf("middle.txt")
         val lastIndex = generatedHtml.indexOf("zulu.txt")
@@ -147,7 +147,7 @@ class GeneratedIndexReadabilityTest {
         assertTrue(
             style.contains(
                 """
-                a:hover span:last-child, a:focus-visible span:last-child {
+                a:hover .entry-label, a:focus-visible .entry-label {
                   text-decoration: underline;
                 }
                 """.trimIndent()

From d6898e3e677dcde004eb190eefde6e5e71dab663 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 24 Sep 2026 22:39:25 +0000
Subject: [PATCH 08/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지

From 4a99fe178e4f34ba3960168f867ad96e43569bd5 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Fri, 25 Sep 2026 11:03:23 +0000
Subject: [PATCH 09/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지

From d2ac67f6084391bd668ad917653c128a069aec6e Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sat, 26 Sep 2026 00:20:03 +0000
Subject: [PATCH 10/10] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EC=8B=9C?=
 =?UTF-8?q?=EA=B0=81=EC=A0=81=20Hover=20=ED=94=BC=EB=93=9C=EB=B0=B1=20?=
 =?UTF-8?q?=EB=B3=B5=EC=9B=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: `:last-child` 선택자를 시맨틱 클래스(`.entry-label`)로 교체하여 숨겨진 스크린 리더용 텍스트 추가로 인해 깨졌던 시각적 Hover 피드백 복원
🎯 Why: 시각적으로 숨겨진 접근성 텍스트(<span class="visually-hidden">)가 DOM의 마지막 요소로 추가되면서, `:last-child`에 적용되던 Hover 시 밑줄 효과가 화면에 보이지 않는 버그를 해결
📸 Before/After: 해당 없음 (시각적 변경)
♿ Accessibility: 시각적 Hover 효과를 복원하면서 스크린 리더용 숨겨진 텍스트 접근성을 유지