Merge pull request #8 from KYJCASTER/feat/long-form-reading

fix(reading): code review 后的边界 / 竞态 / 阅读体验修正

Author: KYJCASTER

src/app/globals.css

@@ -627,24 +627,24 @@ html .shiki, html .shiki span { color: var(--shiki-light); background-color: tra
      graceful wrapping for the last line, and overflow protection for any
      stray super-long URL or code identifier. The `max-width` only kicks in
      when the parent grid track is wider than 68ch — under tablet/mobile the
-     parent track wins, which is what we want. */
+     parent track wins, which is what we want. `break-word` (not `anywhere`)
+     because we only want to break long URLs / identifiers when nothing else
+     fits, never inside ordinary English words mid-paragraph. */
   max-width: 68ch;
   text-wrap: pretty;
   hanging-punctuation: allow-end;
   word-break: normal;
-  overflow-wrap: anywhere;
+  overflow-wrap: break-word;
 }
 /* Headings get balanced wrapping so the last line never carries a single
    character or English word alone. */
 .prose h1, .prose h2, .prose h3, .prose h4 {
   text-wrap: balance;
 }
-/* CJK metrics: in zh-CN context use proportional alternate widths so
-   half-width punctuation sits tight against glyphs; the latin paragraphs
-   inside this scope still render with their own kerning since `palt`
-   only affects the CJK code points. */
-:lang(zh) .prose,
-:lang(zh-CN) .prose {
+/* CJK metrics: in zh context use proportional alternate widths so half-width
+   punctuation sits tight against glyphs. `:lang(zh)` already matches zh-CN
+   per spec, so we don't need a separate selector. */
+:lang(zh) .prose {
   font-feature-settings: "palt", "ss01", "cv11";
 }
 

src/components/article-shortcuts.tsx

@@ -68,7 +68,11 @@ export function ArticleShortcuts() {
         const chapters = getChapters()
         if (!chapters.length) return
         const cursor = findCursor(chapters)
-        const next = chapters[Math.min(chapters.length - 1, cursor + 1)]
+        // No chapter ahead — let `j` quietly do nothing rather than slamming
+        // back to the current chapter top (which is what Math.min(cursor, last)
+        // would do).
+        if (cursor + 1 >= chapters.length) return
+        const next = chapters[cursor + 1]
         if (next) scrollToHeading(next)
         return
       }
@@ -79,14 +83,21 @@ export function ArticleShortcuts() {
         const chapters = getChapters()
         if (!chapters.length) return
         const cursor = findCursor(chapters)
-        // If we're already inside chapter N (cursor = N), `k` should jump to
-        // the *start* of chapter N first, then to N-1 on subsequent presses.
-        const here = cursor >= 0 ? chapters[cursor] : null
+        // Three cases:
+        //   cursor === -1  → reader is above the first chapter (in the title
+        //                    block). `k` should do nothing rather than push
+        //                    them down into chapter 1.
+        //   inside chap N  → first press jumps to the *start* of chap N, then
+        //                    subsequent presses go N-1, N-2 …
+        //   exactly at N   → jump to chap N-1.
+        if (cursor < 0) return
+        const here = chapters[cursor]
         if (here && here.getBoundingClientRect().top < -8) {
           scrollToHeading(here)
           return
         }
-        const prev = chapters[Math.max(0, cursor - 1)]
+        if (cursor === 0) return
+        const prev = chapters[cursor - 1]
         if (prev) scrollToHeading(prev)
         return
       }

src/components/heading-anchors.tsx

@@ -31,19 +31,24 @@ export function HeadingAnchors() {
       const onClick = async (ev: MouseEvent) => {
         ev.preventDefault()
         const url = `${window.location.origin}${window.location.pathname}#${h.id}`
-        try {
-          await navigator.clipboard.writeText(url)
+        const flashCopied = () => {
           btn.dataset.copied = "true"
           btn.textContent = "✓"
           window.setTimeout(() => {
             btn.dataset.copied = "false"
             btn.textContent = "#"
           }, 1400)
+        }
+        try {
+          await navigator.clipboard.writeText(url)
+          flashCopied()
         } catch {
           // Some browsers refuse without HTTPS / focus — fall back to
           // updating the URL hash so the reader can copy from the address
-          // bar manually.
+          // bar manually. Still flash the indicator so they get *some*
+          // feedback that the click was received.
           window.history.replaceState(null, "", `#${h.id}`)
+          flashCopied()
         }
       }
       btn.addEventListener("click", onClick)

src/components/reading-percent.tsx

@@ -40,9 +40,17 @@ export function ReadingPercent({ targetSelector }: { targetSelector: string }) {
     update()
     window.addEventListener("scroll", onScroll, { passive: true })
     window.addEventListener("resize", onScroll)
+    // Lazy-loaded images / collapsed details elements grow the article body
+    // after first paint; recompute progress when that happens.
+    let ro: ResizeObserver | null = null
+    if (typeof ResizeObserver !== "undefined") {
+      ro = new ResizeObserver(() => onScroll())
+      ro.observe(el)
+    }
     return () => {
       window.removeEventListener("scroll", onScroll)
       window.removeEventListener("resize", onScroll)
+      ro?.disconnect()
     }
   }, [targetSelector])
 

src/components/table-of-contents.tsx

@@ -140,9 +140,19 @@ export function TableOfContents({ headings, placement = "desktop" }: TableOfCont
     update()
     window.addEventListener("scroll", onScroll, { passive: true })
     window.addEventListener("resize", onScroll)
+    // Article body height grows as lazy <img>s load — recompute when it does.
+    // ResizeObserver beats listening to `window.load` because images can finish
+    // long after the load event has fired (lazy / fetchpriority='low' images).
+    let ro: ResizeObserver | null = null
+    const article = document.getElementById("article-body")
+    if (article && typeof ResizeObserver !== "undefined") {
+      ro = new ResizeObserver(() => onScroll())
+      ro.observe(article)
+    }
     return () => {
       window.removeEventListener("scroll", onScroll)
       window.removeEventListener("resize", onScroll)
+      ro?.disconnect()
       if (raf) cancelAnimationFrame(raf)
     }
   }, [chapters])
@@ -179,15 +189,25 @@ export function TableOfContents({ headings, placement = "desktop" }: TableOfCont
           <li
             key={c.head.id}
             ref={(el) => {
+              // Keep the chapterRefs map in sync with the live DOM. React calls
+              // the ref with `null` on unmount; without removing entries here
+              // the map would accumulate forever during HMR / heading changes.
               if (el) chapterRefs.current.set(c.head.id, el)
+              else chapterRefs.current.delete(c.head.id)
             }}
             className="toc-chapter"
-            data-state={isActive || subActive ? "active" : "upcoming"}
+            // NB: data-state is OWNED by the scroll handler in useEffect above.
+            // Don't drive it from React state — the two would race and the
+            // already-read chapters would flash back to "upcoming" on every
+            // active-id change. React only owns the auxiliary data-has-active
+            // flag below, which controls sub-list expansion.
+            data-has-active={isActive || subActive ? "true" : "false"}
             style={{ ["--chapter-progress" as never]: 0 } as React.CSSProperties}
           >
             <a
               ref={(el) => {
                 if (el) linkRefs.current.set(c.head.id, el)
+                else linkRefs.current.delete(c.head.id)
               }}
               href={`#${c.head.id}`}
               className="toc-chapter-link"
@@ -201,6 +221,7 @@ export function TableOfContents({ headings, placement = "desktop" }: TableOfCont
                     <a
                       ref={(el) => {
                         if (el) linkRefs.current.set(s.id, el)
+                        else linkRefs.current.delete(s.id)
                       }}
                       href={`#${s.id}`}
                       className="toc-sub-link"