@hanology/cham-browser 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanology/cham-browser",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "CHAM — browser-compatible parser, serializer, and site generator for Classical Han Annotated Markdown",
   "type": "module",
   "main": "dist/index.js",

package/template/src/components/AnnotationTooltip.vue

@@ -198,10 +198,18 @@ onBeforeUnmount(() => {
 }
 
 /* ─── Transition ─── */
-.ann-fade-enter-active, .ann-fade-leave-active {
-  transition: opacity 0.15s ease;
+.ann-fade-enter-active {
+  transition: opacity var(--dur-fast, 0.15s) ease, transform var(--dur-mid, 0.25s) cubic-bezier(0.34, 1.56, 0.64, 1);
 }
-.ann-fade-enter-from, .ann-fade-leave-to {
+.ann-fade-leave-active {
+  transition: opacity var(--dur-fast, 0.15s) ease, transform var(--dur-fast, 0.15s) ease;
+}
+.ann-fade-enter-from {
+  opacity: 0;
+  transform: scale(0.92) translateY(4px);
+}
+.ann-fade-leave-to {
   opacity: 0;
+  transform: scale(0.96);
 }
 </style>

package/template/src/components/BackToTop.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const visible = ref(false)
+let ticking = false
+
+function onScroll() {
+  if (ticking) return
+  ticking = true
+  requestAnimationFrame(() => {
+    visible.value = window.scrollY > 400
+    ticking = false
+  })
+}
+
+function scrollToTop() {
+  window.scrollTo({ top: 0, behavior: 'smooth' })
+}
+
+onMounted(() => window.addEventListener('scroll', onScroll, { passive: true }))
+onUnmounted(() => window.removeEventListener('scroll', onScroll))
+</script>
+
+<template>
+  <Transition name="btt">
+    <button v-if="visible" class="btt" @click="scrollToTop" aria-label="回到頂部">
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 19V5M5 12l7-7 7 7"/>
+      </svg>
+    </button>
+  </Transition>
+</template>
+
+<style scoped>
+.btt {
+  position: fixed;
+  bottom: 80px;
+  right: 24px;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--ink-light);
+  cursor: pointer;
+  z-index: 400;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 16px rgba(var(--shadow-rgb), 0.1);
+  transition: all 0.25s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.btt:hover {
+  background: var(--ink);
+  color: var(--paper);
+  border-color: var(--ink);
+  transform: translateY(-2px);
+  box-shadow: 0 8px 24px rgba(var(--shadow-rgb), 0.16);
+}
+
+.btt-enter-active { transition: all 0.3s cubic-bezier(0.34, 1.56, 0.64, 1); }
+.btt-leave-active { transition: all 0.15s ease; }
+.btt-enter-from { opacity: 0; transform: translateY(12px) scale(0.8); }
+.btt-leave-to { opacity: 0; transform: translateY(8px) scale(0.9); }
+</style>

package/template/src/components/PartBlock.vue

@@ -8,6 +8,7 @@ const props = defineProps<{
   annotations: Annotation[]
   vertical?: boolean
   source?: PieceSource
+  annotationText?: string
 }>()
 
 const emit = defineEmits<{
@@ -55,6 +56,9 @@ const sourceLabel = (() => {
         v-html="verseHtml(i)"
       />
     </div>
+    <div v-if="annotationText" class="part-annotations">
+      <div v-for="line in annotationText.split('\n')" :key="line" class="part-ann-line">{{ line }}</div>
+    </div>
   </div>
 </template>
 
@@ -90,6 +94,20 @@ const sourceLabel = (() => {
   line-height: 1;
 }
 
+.part-annotations {
+  margin-top: 16px;
+  padding-top: 12px;
+  border-top: 1px dashed var(--border-light);
+}
+
+.part-ann-line {
+  font-family: var(--sans);
+  font-size: 14px;
+  line-height: 2;
+  color: var(--ink-mid);
+  letter-spacing: 0.5px;
+}
+
 .part-line-h {
   font-size: var(--main-font-size, 22px);
   line-height: 2.4;
@@ -134,7 +152,6 @@ const sourceLabel = (() => {
   background: rgba(58, 107, 94, 0.08);
 }
 
-/* Vertical mode overrides */
 .part-block--vertical :deep(.ann-target) {
   border-bottom: none;
   border-left: 2px solid var(--vermillion);
@@ -157,4 +174,13 @@ const sourceLabel = (() => {
   margin-bottom: 0;
   margin-left: 8px;
 }
+
+.part-block--vertical .part-annotations {
+  margin-top: 0;
+  margin-left: 12px;
+  padding-top: 0;
+  padding-left: 12px;
+  border-top: none;
+  border-left: 1px dashed var(--border-light);
+}
 </style>

package/template/src/components/PartGroup.vue

@@ -24,6 +24,7 @@ const emit = defineEmits<{
       :num="part.num"
       :verses="part.verses"
       :annotations="part.annotations"
+      :annotation-text="part.annotationText"
       :vertical="vertical"
       :source="part.source"
       @annotation-hover="(e, a) => emit('annotationHover', e, a)"

package/template/src/components/PoemCard.vue

@@ -54,6 +54,13 @@ const preview = computed(() => {
   font-size: 11px; color: var(--ink-faint);
   font-family: var(--sans); letter-spacing: 2px;
   margin-bottom: 10px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2px 6px;
+  border: 1px solid var(--border-light);
+  border-radius: 2px;
+  background: var(--surface-warm);
 }
 .pc-title {
   font-size: 20px; font-weight: 700;

package/template/src/components/ReadingProgress.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, watch } from 'vue'
+
+const props = defineProps<{
+  vertical?: boolean
+  scrollContainer?: HTMLElement | null
+}>()
+
+const progress = ref(0)
+let raf = 0
+
+function updateProgress() {
+  if (props.vertical && props.scrollContainer) {
+    const el = props.scrollContainer
+    const max = el.scrollWidth - el.clientWidth
+    progress.value = max > 0 ? Math.min((el.scrollLeft / max) * 100, 100) : 0
+  } else if (!props.vertical) {
+    const max = document.documentElement.scrollHeight - window.innerHeight
+    progress.value = max > 0 ? Math.min((window.scrollY / max) * 100, 100) : 0
+  }
+}
+
+function onScroll() {
+  cancelAnimationFrame(raf)
+  raf = requestAnimationFrame(updateProgress)
+}
+
+function attach() {
+  if (props.vertical && props.scrollContainer) {
+    props.scrollContainer.addEventListener('scroll', onScroll, { passive: true })
+  } else if (!props.vertical) {
+    window.addEventListener('scroll', onScroll, { passive: true })
+  }
+  updateProgress()
+}
+
+function detach() {
+  if (props.vertical && props.scrollContainer) {
+    props.scrollContainer.removeEventListener('scroll', onScroll)
+  } else {
+    window.removeEventListener('scroll', onScroll)
+  }
+  cancelAnimationFrame(raf)
+}
+
+watch(() => props.scrollContainer, (el, old) => {
+  detach()
+  if (old) old.removeEventListener('scroll', onScroll)
+  attach()
+})
+
+onMounted(attach)
+onUnmounted(detach)
+</script>
+
+<template>
+  <div
+    class="rp"
+    :class="{ 'rp-v': vertical }"
+    :style="vertical
+      ? { height: progress + '%' }
+      : { width: progress + '%' }"
+  />
+</template>
+
+<style scoped>
+.rp {
+  position: fixed;
+  z-index: 1001;
+  background: linear-gradient(90deg, var(--vermillion), var(--vermillion-light));
+  pointer-events: none;
+  will-change: width, height;
+}
+.rp:not(.rp-v) {
+  top: 0; left: 0;
+  height: 2px;
+}
+.rp-v {
+  top: 0; left: 0;
+  width: 2px;
+  background: linear-gradient(180deg, var(--vermillion), var(--vermillion-light));
+}
+</style>

package/template/src/components/ReadingToolbar.vue

@@ -74,6 +74,11 @@ function close() { open.value = false }
           >{{ localeLabels[loc] }}</button>
         </div>
       </div>
+      <div class="rt-shortcuts">
+        <div class="rt-sc"><kbd>V</kbd> 直/橫</div>
+        <div class="rt-sc"><kbd>T</kbd> 主題</div>
+        <div class="rt-sc"><kbd>Esc</kbd> 首頁</div>
+      </div>
     </div>
     <div v-if="open" class="rt-backdrop" @click="close" />
   </div>
@@ -150,6 +155,25 @@ function close() { open.value = false }
   transition: all 0.15s;
 }
 .rt-opt:hover { border-color: var(--ink); color: var(--ink); }
+.rt-opt.rt-theme {
+  position: relative;
+  padding-left: 22px;
+}
+.rt-opt.rt-theme::before {
+  content: '';
+  position: absolute;
+  left: 8px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+}
+.rt-opt.theme-light::before { background: #faf6ee; }
+.rt-opt.theme-sepia::before { background: #f0e4c8; }
+.rt-opt.theme-dark::before { background: #1c1c1e; border-color: #48484a; }
+.rt-opt.theme-oled::before { background: #000; border-color: #333; }
 .rt-opt.active {
   background: var(--ink);
   color: var(--paper);
@@ -182,4 +206,35 @@ function close() { open.value = false }
   position: fixed; inset: 0;
   z-index: -1;
 }
+.rt-shortcuts {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding-top: 10px;
+  border-top: 1px solid var(--border-light);
+  margin-top: 2px;
+}
+.rt-sc {
+  font-family: var(--sans);
+  font-size: 10px;
+  color: var(--ink-faint);
+  letter-spacing: 1px;
+  display: flex;
+  align-items: center;
+  gap: 3px;
+}
+.rt-sc kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 16px;
+  padding: 0 3px;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+  font-family: var(--sans);
+  font-size: 9px;
+  color: var(--ink-light);
+  background: var(--surface);
+}
 </style>

package/template/src/components/SectionBlock.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, ref, onMounted, onUnmounted } from 'vue'
 import { parseAnnotationBlock } from '../utils/annotationParser'
 import PronunciationGroup from './PronunciationGroup.vue'
 
@@ -12,6 +12,27 @@ const props = defineProps<{
   vertical?: boolean
 }>()
 
+const rootRef = ref<HTMLElement | null>(null)
+const visible = ref(false)
+
+onMounted(() => {
+  if (props.vertical || !rootRef.value) {
+    visible.value = true
+    return
+  }
+  const observer = new IntersectionObserver(
+    ([entry]) => {
+      if (entry.isIntersecting) {
+        visible.value = true
+        observer.disconnect()
+      }
+    },
+    { rootMargin: '0px 0px -40px 0px', threshold: 0 }
+  )
+  observer.observe(rootRef.value)
+  onUnmounted(() => observer.disconnect())
+})
+
 function esc(str: string): string {
   return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 }
@@ -40,7 +61,7 @@ const paragraphsHtml = computed(() => {
 </script>
 
 <template>
-  <div v-if="text" class="sb-root" :class="{ 'sb-vertical': vertical }">
+  <div v-if="text" ref="rootRef" class="sb-root" :class="{ 'sb-vertical': vertical, 'sb-visible': visible }">
     <div class="sb-header">
       <span v-if="displayNum" class="sb-num" :class="{ special }">{{ displayNum }}</span>
       <h3>{{ special ? '【' + label + '】' : label }}</h3>
@@ -64,11 +85,13 @@ const paragraphsHtml = computed(() => {
 <style scoped>
 .sb-root {
   margin-bottom: 40px;
-  animation: sb-fade-up 0.5s ease forwards;
+  opacity: 0;
+  transform: translateY(12px);
+  transition: opacity 0.5s ease, transform 0.5s var(--ease-out-expo, cubic-bezier(0.16, 1, 0.3, 1));
 }
-@keyframes sb-fade-up {
-  from { opacity: 0; transform: translateY(16px); }
-  to { opacity: 1; transform: translateY(0); }
+.sb-root.sb-visible {
+  opacity: 1;
+  transform: translateY(0);
 }
 .sb-header {
   display: flex; align-items: center; gap: 12px;
@@ -107,7 +130,9 @@ const paragraphsHtml = computed(() => {
   border-right: 1px solid var(--border);
   overflow-x: auto;
   overflow-y: hidden;
-  animation: none;
+  opacity: 1;
+  transform: none;
+  transition: none;
 }
 .sb-vertical .sb-header {
   flex-direction: column;

package/template/src/components/SideNav.vue

@@ -113,6 +113,11 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
             >{{ localeLabels[loc] }}</button>
           </div>
         </div>
+        <div class="ss-shortcuts">
+          <span class="ss-sc"><kbd>V</kbd> 直/橫</span>
+          <span class="ss-sc"><kbd>T</kbd> 主題</span>
+          <span class="ss-sc"><kbd>Esc</kbd> 首頁</span>
+        </div>
       </div>
     </Transition>
 
@@ -308,6 +313,37 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
   position: fixed; inset: 0;
   z-index: -1;
 }
+.ss-shortcuts {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 8px;
+  padding-top: 10px;
+  border-top: 1px solid var(--border-light);
+  margin-top: 2px;
+}
+.ss-sc {
+  font-family: var(--sans);
+  font-size: 10px;
+  color: var(--ink-faint);
+  letter-spacing: 1px;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+}
+.ss-sc kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 16px;
+  padding: 0 3px;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+  font-family: var(--sans);
+  font-size: 9px;
+  color: var(--ink-light);
+  background: var(--surface);
+}
 
 @media (max-width: 768px) {
   .sidenav { width: 44px; padding: 8px 0; gap: 6px; }

package/template/src/styles/main.css

@@ -90,23 +90,36 @@
   --sans: 'Noto Sans TC', 'PingFang TC', sans-serif;
   --nav-width: 56px;
   --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --dur-fast: 0.15s;
+  --dur-mid: 0.25s;
+  --dur-slow: 0.4s;
 }
 *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
-html { scroll-behavior: smooth; -webkit-font-smoothing: antialiased; }
+html {
+  scroll-behavior: smooth;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  hanging-punctuation: first last;
+}
 body {
   font-family: var(--serif);
   background: var(--paper);
   color: var(--ink);
   line-height: 1.8;
   min-height: 100vh;
+  overflow-x: hidden;
 }
 ::selection { background: var(--vermillion); color: var(--selection-text); }
 ::-webkit-scrollbar { width: 6px; height: 6px; }
 ::-webkit-scrollbar-track { background: transparent; }
 ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
 ::-webkit-scrollbar-thumb:hover { background: var(--ink-faint); }
+html[dir="rtl"] ::-webkit-scrollbar-thumb { background: var(--gold); }
 
 a { color: inherit; text-decoration: none; }
+button { font-family: inherit; }
 
 /* ===== LOADING SCREEN ===== */
 #app-loading {
@@ -166,6 +179,18 @@ a { color: inherit; text-decoration: none; }
   from { opacity: 0; transform: translateY(16px); }
   to { opacity: 1; transform: translateY(0); }
 }
+@keyframes cardEnter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes scaleIn {
+  from { opacity: 0; transform: scale(0.92); }
+  to { opacity: 1; transform: scale(1); }
+}
 
 /* ===== RESPONSIVE ===== */
 @media (max-width: 768px) {

package/template/src/types.ts

@@ -108,11 +108,12 @@ export interface PieceContributor {
   title?: string
 }
 
-export interface PieceSource {  text?: string
+export interface PieceSource {
+  text?: string
   textRef?: string
   pieceRef?: number
   relation: 'section' | 'excerpt' | 'standalone'
-  range?: { start: string; end: string }
+  range?: { start?: string; end?: string; chapter?: string; [key: string]: string | undefined }
 }
 
 export interface ProseSection {
@@ -130,6 +131,7 @@ export interface Part {
   source?: PieceSource
   verses: VerseLine[]
   annotations: Annotation[]
+  annotationText?: string
 }
 
 export interface Piece {

package/template/src/views/AboutView.vue

@@ -5,6 +5,7 @@ import { useReadingMode } from '../composables/useReadingMode'
 import { useHorizontalScroll } from '../composables/useHorizontalScroll'
 import SideNav from '../components/SideNav.vue'
 import ReadingToolbar from '../components/ReadingToolbar.vue'
+import BackToTop from '../components/BackToTop.vue'
 import { useSiteConfig } from '../composables/useSiteConfig'
 import { ref, computed } from 'vue'
 import { useRouter } from 'vue-router'
@@ -63,6 +64,7 @@ function goHome() { router.push('/') }
         <p>Hanology is a digital library for classical Chinese texts. We believe that the wisdom of antiquity should not be locked behind impenetrable editions or forgotten in dusty shelves. By combining rigorous scholarship with thoughtful design, we make the classics accessible, beautiful, and alive for every reader.</p>
       </div>
     </div>
+    <BackToTop />
     <ReadingToolbar />
   </div>
 </template>
@@ -80,6 +82,7 @@ function goHome() { router.push('/') }
   background: var(--paper);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -161,6 +164,11 @@ function goHome() { router.push('/') }
   background: var(--surface);
   border: 1px solid var(--border-light);
   border-radius: 8px;
+  animation: cardEnter 0.5s var(--ease-out-expo, ease) both;
+}
+@keyframes cardEnter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
 }
 .h-about-block:last-child { margin-bottom: 0; }
 .h-about-block h2 {

package/template/src/views/BookHome.vue

@@ -8,6 +8,7 @@ import { useHorizontalScroll } from '../composables/useHorizontalScroll'
 import PoemCard from '../components/PoemCard.vue'
 import SideNav from '../components/SideNav.vue'
 import ReadingToolbar from '../components/ReadingToolbar.vue'
+import BackToTop from '../components/BackToTop.vue'
 
 const props = defineProps<{ bookId: string }>()
 const router = useRouter()
@@ -128,14 +129,17 @@ function scrollToCatalog() {
       </div>
       <div class="h-grid">
         <PoemCard
-          v-for="piece in filtered"
+          v-for="(piece, idx) in filtered"
           :key="piece.num"
           :poem="piece"
+          :style="{ animationDelay: Math.min(idx * 0.04, 0.8) + 's' }"
+          class="h-card-anim"
           @click="openPiece(piece.num)"
         />
       </div>
     </section>
 
+    <BackToTop />
     <ReadingToolbar />
   </div>
 </template>
@@ -154,6 +158,7 @@ function scrollToCatalog() {
   background: linear-gradient(90deg, var(--paper) 0%, var(--paper-warm) 100%);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -358,6 +363,9 @@ function scrollToCatalog() {
   grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
   gap: 16px;
 }
+.h-card-anim {
+  animation: cardEnter 0.4s var(--ease-out-expo) both;
+}
 
 @media (max-width: 768px) {
   .h-stats { gap: 24px; }

package/template/src/views/LibraryHome.vue

@@ -9,6 +9,7 @@ import { useHorizontalScroll } from '../composables/useHorizontalScroll'
 import BookCard from '../components/BookCard.vue'
 import SideNav from '../components/SideNav.vue'
 import ReadingToolbar from '../components/ReadingToolbar.vue'
+import BackToTop from '../components/BackToTop.vue'
 import { useSiteConfig } from '../composables/useSiteConfig'
 import type { BookMeta } from '../types'
 
@@ -125,9 +126,10 @@ function openBook(bookId: string) {
         <h2 class="lib-group-title">{{ group.category }}</h2>
         <div class="lib-grid">
           <div
-            v-for="book in group.books"
+            v-for="(book, bi) in group.books"
             :key="book.id"
-            class="lib-card"
+            class="lib-card lib-card-anim"
+            :style="{ animationDelay: bi * 0.06 + 's' }"
             @click="openBook(book.id)"
           >
             <div class="lib-card-accent"></div>
@@ -145,6 +147,7 @@ function openBook(bookId: string) {
         </div>
       </div>
       <ReadingToolbar />
+      <BackToTop />
     </div>
   </div>
 </template>
@@ -163,6 +166,7 @@ function openBook(bookId: string) {
   background: linear-gradient(90deg, var(--paper) 0%, var(--paper-warm) 100%);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -383,6 +387,10 @@ function openBook(bookId: string) {
   gap: 12px;
 }
 
+.lib-card-anim {
+  animation: cardEnter 0.4s var(--ease-out-expo) both;
+}
+
 .lib-card {
   display: flex;
   flex-direction: column;
@@ -391,9 +399,14 @@ function openBook(bookId: string) {
   border: 1px solid var(--border-light);
   border-radius: 8px;
   cursor: pointer;
-  transition: all 0.3s ease;
+  transition: all 0.3s var(--ease-out-expo, ease);
   position: relative;
   background: var(--surface);
+  animation: cardEnter 0.5s var(--ease-out-expo, ease) both;
+}
+@keyframes cardEnter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
 }
 .lib-card:hover { border-color: var(--gold); box-shadow: 0 4px 20px rgba(var(--shadow-rgb), 0.1); }
 .lib-card-accent {

package/template/src/views/PieceView.vue

@@ -14,6 +14,8 @@ import AnnotationTooltip from '../components/AnnotationTooltip.vue'
 import AnnotationControlBar from '../components/AnnotationControlBar.vue'
 import SideNav from '../components/SideNav.vue'
 import PartGroup from '../components/PartGroup.vue'
+import ReadingProgress from '../components/ReadingProgress.vue'
+import BackToTop from '../components/BackToTop.vue'
 import type { Piece, Annotation, AnnotationLayer, Part } from '../types'
 
 const props = defineProps<{ bookId: string; num: string | number }>()
@@ -59,6 +61,17 @@ useTitle(pageTitle.value)
 
 const isVertical = computed(() => layout.value === 'vertical')
 
+const totalAnnotationCount = computed(() => {
+  if (!piece.value) return 0
+  let count = piece.value.annotations.length
+  if (piece.value.annotationLayers) {
+    for (const layer of piece.value.annotationLayers) {
+      count += layer.annotations.length
+    }
+  }
+  return count
+})
+
 const annotationLayers = computed<AnnotationLayer[]>(() => piece.value?.annotationLayers || [])
 const hasLayers = computed(() => annotationLayers.value.length > 1)
 const activeLayerIds = ref<string[]>([])
@@ -242,6 +255,7 @@ function tcy(n: number): string {
         @back="goBack"
         @home="goHome"
       />
+      <ReadingProgress vertical :scroll-container="vPageRef" />
       <div ref="vPageRef" class="v-page">
         <section ref="vTitleRef" class="v-title-col">
           <h1 class="v-poem-title">{{ piece.title }}</h1>
@@ -262,7 +276,7 @@ function tcy(n: number): string {
             </template>
             <template v-else>
               <span class="v-meta-item" v-html="tcy(piece.verses.length) + ' 段'" />
-              <span class="v-meta-item" v-html="piece.annotations.length > 0 ? tcy(piece.annotations.length) + ' 注' : '無注'" />
+              <span class="v-meta-item" v-html="totalAnnotationCount > 0 ? tcy(totalAnnotationCount) + ' 注' : '無注'" />
             </template>
           </div>
         </section>
@@ -374,24 +388,27 @@ function tcy(n: number): string {
       />
 
       <Teleport to="body">
-        <div v-if="authorPaneOpen" class="v-overlay" @click="closeAuthorPane">
-          <div class="v-author-pane" @click.stop>
-            <button class="v-pane-close" @click="closeAuthorPane">✕</button>
-            <div class="v-pane-header">
-              <div class="v-pane-name">{{ selectedAuthorName }}</div>
-            </div>
-            <div v-if="selectedAuthorBio" class="v-pane-bio">
-              <div v-for="p in selectedAuthorBio.split('\n').filter(l => l.trim())" :key="p" class="v-pane-p">
-                {{ p.trim() }}
+        <Transition name="overlay">
+          <div v-if="authorPaneOpen" class="v-overlay" @click="closeAuthorPane">
+            <div class="v-author-pane" @click.stop>
+              <button class="v-pane-close" @click="closeAuthorPane">✕</button>
+              <div class="v-pane-header">
+                <div class="v-pane-name">{{ selectedAuthorName }}</div>
+              </div>
+              <div v-if="selectedAuthorBio" class="v-pane-bio">
+                <div v-for="p in selectedAuthorBio.split('\n').filter(l => l.trim())" :key="p" class="v-pane-p">
+                  {{ p.trim() }}
+                </div>
               </div>
             </div>
           </div>
-        </div>
+        </Transition>
       </Teleport>
     </div>
 
     <!-- ═══════ 橫排模式 ═══════ -->
     <div v-else class="h-root">
+      <ReadingProgress />
       <div class="h-page">
         <nav class="h-nav">
           <div class="h-nav-inner">
@@ -419,7 +436,7 @@ function tcy(n: number): string {
               </template>
               <template v-else>
                 <span class="h-tag">{{ piece.verses.length }} 段</span>
-                <span class="h-tag">{{ piece.annotations.length > 0 ? piece.annotations.length + ' 注' : '無注' }}</span>
+                <span class="h-tag">{{ totalAnnotationCount > 0 ? totalAnnotationCount + ' 注' : '無注' }}</span>
               </template>
             </div>
           </div>
@@ -516,8 +533,11 @@ function tcy(n: number): string {
         @tooltip-leave="interaction.onTooltipLeave"
       />
 
+      <BackToTop />
+
       <Teleport to="body">
-        <div v-if="authorPaneOpen" class="h-overlay" @click="closeAuthorPane">
+        <Transition name="overlay">
+          <div v-if="authorPaneOpen" class="h-overlay" @click="closeAuthorPane">
           <div class="h-pane" @click.stop>
             <button class="h-pane-close" @click="closeAuthorPane">✕</button>
             <div class="h-pane-header">
@@ -532,13 +552,13 @@ function tcy(n: number): string {
               </div>
             </div>
           </div>
-        </div>
+        </Transition>
       </Teleport>
     </div>
   </div>
 
-  <div v-else style="text-align:center;padding-top:120px">
-    <p style="font-size:18px;color:var(--ink-faint)">載入中…</p>
+  <div v-else class="loading">
+    <div class="loading-seal">詩</div>
   </div>
 </template>
 
@@ -556,6 +576,7 @@ function tcy(n: number): string {
   background: var(--paper);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -571,6 +592,7 @@ function tcy(n: number): string {
   gap: 16px;
   padding: 40px 24px;
   border-right: 1px solid var(--border);
+  scroll-snap-align: start;
 }
 .v-poem-title {
   font-size: 40px; font-weight: 900;
@@ -659,6 +681,7 @@ function tcy(n: number): string {
   justify-content: center;
   padding: 24px 12px;
   gap: 32px;
+  scroll-snap-align: start;
 }
 .v-nav-spacer { flex: 1; }
 .v-nav-btn {
@@ -774,38 +797,63 @@ function tcy(n: number): string {
 .h-nav-bottom {
   max-width: min(680px, calc(100vw - 80px));
   margin: 0 auto 60px;
-  display: flex; justify-content: space-between; gap: 16px;
+  display: grid; grid-template-columns: 1fr 1fr; gap: 16px;
 }
 .h-nav-btn {
-  flex: 1; padding: 16px 24px;
+  padding: 20px 24px;
   background: var(--surface); border: 1px solid var(--border-light);
   border-radius: 8px; cursor: pointer;
-  transition: all 0.2s ease; font-family: var(--serif);
+  transition: all 0.3s cubic-bezier(0.34, 1.56, 0.64, 1);
+  font-family: var(--serif);
   text-align: left;
+  position: relative;
+  overflow: hidden;
+}
+.h-nav-btn::after {
+  content: '';
+  position: absolute;
+  bottom: 0; left: 0; right: 0;
+  height: 2px;
+  background: var(--vermillion);
+  transform: scaleX(0);
+  transition: transform 0.3s ease;
+}
+.h-nav-btn:hover {
+  border-color: var(--gold);
+  box-shadow: 0 8px 32px rgba(var(--shadow-rgb), 0.1);
+  transform: translateY(-2px);
 }
-.h-nav-btn:hover { border-color: var(--gold); box-shadow: 0 4px 16px rgba(var(--shadow-rgb), 0.08); }
+.h-nav-btn:hover::after { transform: scaleX(1); }
 .h-nav-btn.h-nav-next { text-align: right; }
 .h-nav-label { font-size: 11px; color: var(--ink-faint); font-family: var(--sans); letter-spacing: 2px; margin-bottom: 4px; }
 .h-nav-title { font-size: 16px; font-weight: 600; letter-spacing: 1px; color: var(--ink); }
 
 .h-overlay {
   position: fixed; inset: 0;
-  background: rgba(var(--shadow-rgb), 0.3);
+  background: rgba(var(--shadow-rgb), 0.24);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
   z-index: 200;
   display: flex; justify-content: flex-end;
-  animation: fadeIn 0.2s ease;
 }
-@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
 .h-pane {
   width: min(420px, 90vw);
   height: 100vh;
   background: var(--paper);
   padding: 32px;
   overflow-y: auto;
-  animation: slideIn 0.25s ease;
   box-shadow: -8px 0 32px rgba(var(--shadow-rgb), 0.1);
 }
-@keyframes slideIn { from { transform: translateX(100%); } to { transform: translateX(0); } }
+
+/* Overlay transition */
+.overlay-enter-active { transition: opacity var(--dur-mid, 0.25s) ease; }
+.overlay-enter-active .h-pane { transition: transform var(--dur-mid, 0.25s) cubic-bezier(0.34, 1.56, 0.64, 1); }
+.overlay-leave-active { transition: opacity var(--dur-fast, 0.15s) ease; }
+.overlay-leave-active .h-pane { transition: transform var(--dur-fast, 0.15s) ease; }
+.overlay-enter-from { opacity: 0; }
+.overlay-enter-from .h-pane { transform: translateX(100%); }
+.overlay-leave-to { opacity: 0; }
+.overlay-leave-to .h-pane { transform: translateX(40px); }
 .h-pane-close {
   display: block; margin-left: auto;
   width: 36px; height: 36px;
@@ -837,10 +885,11 @@ function tcy(n: number): string {
 
 .v-overlay {
   position: fixed; inset: 0;
-  background: rgba(var(--shadow-rgb), 0.3);
+  background: rgba(var(--shadow-rgb), 0.24);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
   z-index: 200;
   display: flex; justify-content: flex-start;
-  animation: fadeIn 0.2s ease;
 }
 .v-author-pane {
   writing-mode: vertical-rl;
@@ -850,9 +899,7 @@ function tcy(n: number): string {
   padding: 32px 24px;
   overflow-x: auto;
   box-shadow: 8px 0 32px rgba(var(--shadow-rgb), 0.1);
-  animation: slideInV 0.25s ease;
 }
-@keyframes slideInV { from { transform: translateX(-100%); } to { transform: translateX(0); } }
 .v-pane-close {
   display: block;
   width: 32px; height: 32px;
@@ -894,6 +941,25 @@ function tcy(n: number): string {
   margin-left: 12px;
 }
 
+.loading {
+  display: flex; flex-direction: column;
+  align-items: center; justify-content: center;
+  height: 100vh;
+}
+.loading-seal {
+  width: 56px; height: 56px;
+  border: 2px solid var(--vermillion);
+  border-radius: 4px;
+  display: flex; align-items: center; justify-content: center;
+  font-size: 28px; font-weight: 900;
+  color: var(--vermillion);
+  animation: pulse 1.2s ease-in-out infinite;
+}
+@keyframes pulse {
+  0%, 100% { opacity: 0.3; }
+  50% { opacity: 1; }
+}
+
 @media (max-width: 768px) {
   .h-content { padding: 30px 20px; }
 }