@hyebook/vue3-adapter 2.3.9 → 2.3.11

package/dist/core/src/player/ebook-player.js

@@ -1,13 +1,40 @@
 import { PlayerEngine } from "./engine";
 const EBOOK_PLAYER_STYLE_ID = "hy-ebook-lite-player-style";
-const EBOOK_PLAYER_STYLE_VERSION = "0.2.0";
+const EBOOK_PLAYER_STYLE_VERSION = "0.2.2";
+const JUMP_SCROLL_FOCUS_DELAY_MS = 360;
+const JUMP_FOCUS_ANIMATION_MS = 560;
+const BOOKMARK_JUMP_REVEAL_TOP_OFFSET_PX = 28;
 const HIGHLIGHT_ICON_SVG = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M3 22V12.5H6V8.5H18V12.5H21V22H3Z" stroke="#333333" stroke-width="2" stroke-linejoin="round"/><path d="M8.5 8.5V4L15.5 2V8.5" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
 const NOTE_ICON_SVG = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M15.4998 4.49951L19.4998 8.4995" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M3.99977 15.9995L17.9997 2L21.9998 5.9995L7.99975 19.9995L2.99976 20.9995L3.99977 15.9995Z" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M4.49976 15.9995L7.99975 19.4995" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M6.49976 17.4995L17.4998 6.4995" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
 const BOOKMARK_ICON_SVG = `<svg width="30" height="40" viewBox="0 0 30 40" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0 3C0 1.34315 1.34315 0 3 0H27C28.6569 0 30 1.34315 30 3V38.1989C30 38.9837 29.1374 39.4627 28.4713 39.0477L15 30.6562L1.52873 39.0477C0.862627 39.4627 0 38.9837 0 38.1989L0 3Z" fill="#4FCEBB"/></svg>`;
+const BACK_TO_TOP_ICON_SVG = `<svg width="18" height="18" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 18V6" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><path d="M7 11L12 6L17 11" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
 const EBOOK_PLAYER_CSS = `
 .hyepl-root{position:relative;max-width:100%;margin:0 auto;color:#0f172a;font-size:14px;line-height:1.7}
 .hyepl-root ::selection{background:#7DE2D3}
 .hyepl-root ::-moz-selection{background:#7DE2D3}
+.hyepl-load-warning{position:absolute;top:12px;right:12px;z-index:10080;max-width:min(420px,calc(100% - 24px));display:none;border:1px solid #f5c2c7;background:#fff5f5;color:#7f1d1d;border-radius:10px;box-shadow:0 10px 24px rgba(15,23,42,.12);padding:8px 10px}
+.hyepl-load-warning.show{display:block}
+.hyepl-load-warning-header{display:flex;align-items:center;gap:8px}
+.hyepl-load-warning-title{font-size:12px;font-weight:600;line-height:1.4}
+.hyepl-load-warning-actions{margin-left:auto;display:inline-flex;align-items:center;gap:6px}
+.hyepl-load-warning-btn{border:1px solid #f1b3b3;background:#fff;color:#7f1d1d;border-radius:6px;height:24px;padding:0 8px;font-size:12px;line-height:1;cursor:pointer}
+.hyepl-load-warning-close{width:24px;padding:0}
+.hyepl-load-warning-message{margin:8px 0 0;font-size:12px;line-height:1.5;color:#7f1d1d;white-space:pre-wrap;word-break:break-word;display:none;max-height:180px;overflow:auto}
+.hyepl-load-warning.expanded .hyepl-load-warning-message{display:block}
+.hyepl-input-backdrop{position:fixed;inset:0;display:none;align-items:center;justify-content:center;background:rgba(15,23,42,.45);z-index:10090;padding:16px}
+.hyepl-input-backdrop.show{display:flex}
+.hyepl-input-dialog{width:min(520px,100%);background:#fff;border:1px solid #cbd5e1;border-radius:12px;padding:14px;display:grid;gap:10px;box-shadow:0 16px 34px rgba(15,23,42,.28)}
+.hyepl-input-title{margin:0;font-size:14px;font-weight:600;color:#0f172a}
+.hyepl-input-textarea{width:100%;min-height:120px;resize:vertical;border:1px solid #94a3b8;border-radius:8px;padding:8px 10px;background:#fff;color:#0f172a;box-sizing:border-box;font-family:inherit;font-size:14px;line-height:1.5}
+.hyepl-input-error{min-height:18px;margin:0;color:#b91c1c;font-size:12px}
+.hyepl-input-actions{display:flex;justify-content:flex-end;gap:8px}
+.hyepl-input-btn{height:34px;padding:0 12px;border-radius:8px;border:1px solid #94a3b8;background:#fff;color:#0f172a;cursor:pointer}
+.hyepl-input-btn.primary{border-color:#0b7285;background:#0b7285;color:#fff}
+.hyepl-back-to-top{position:absolute;right:16px;bottom:16px;z-index:10060;width:52px;height:52px;border:1px solid #d5dde8;border-radius:999px;background:#ffffff;color:#0f172a;box-shadow:0 10px 28px rgba(15,23,42,.2);display:inline-flex;align-items:center;justify-content:center;cursor:pointer;transition:background .2s ease,color .2s ease,border-color .2s ease}
+.hyepl-back-to-top svg{width:22px;height:22px}
+.hyepl-back-to-top:hover{background:#0f172a;color:#ffffff;border-color:#0f172a}
+.hyepl-back-to-top:focus-visible{outline:2px solid #38bdf8;outline-offset:2px}
+.hyepl-back-to-top.hidden{display:none}
 .hyepl-content{position:relative}
 .hyepl-page{margin:0 0 16px}
 .hyepl-page:last-child{margin-bottom:0}
@@ -16,6 +43,7 @@ const EBOOK_PLAYER_CSS = `
 .hyepl-block-text{position:relative;padding-right:18px;white-space:normal}
 .hyepl-block-text p,.hyepl-block-text h1,.hyepl-block-text h2,.hyepl-block-text h3,.hyepl-block-text h4,.hyepl-block-text blockquote{margin:0 0 .75em;line-height:1.7}
 .hyepl-block-text p:last-child,.hyepl-block-text h1:last-child,.hyepl-block-text h2:last-child,.hyepl-block-text h3:last-child,.hyepl-block-text h4:last-child,.hyepl-block-text blockquote:last-child{margin-bottom:0}
+.hyepl-block-text em,.hyepl-block-text i,.hyepl-block-table em,.hyepl-block-table i{font-style:italic}
 .hyepl-block-text h1{font-size:24px;line-height:1.3}
 .hyepl-block-text h2{font-size:20px;line-height:1.35}
 .hyepl-block-text h3{font-size:16px;line-height:1.45}
@@ -48,10 +76,31 @@ const EBOOK_PLAYER_CSS = `
 .hyepl-toolbar-icon{display:inline-flex;align-items:center;justify-content:center;width:24px;height:24px}
 .hyepl-toolbar-icon svg{display:block;width:24px;height:24px}
 .hyepl-toolbar-text{font-size:14px;font-weight:700;color:#111827}
+
+.hyepl-jump-focus{animation:hyepl-jump-focus 560ms ease-out}
+.hyepl-jump-focus-mark{animation:hyepl-jump-focus-mark 560ms ease-out}
+
+@keyframes hyepl-jump-focus{
+  0%{filter:none;box-shadow:0 0 0 0 rgba(125,226,211,0)}
+  35%{filter:brightness(1.08);box-shadow:0 0 0 4px rgba(125,226,211,.24)}
+  100%{filter:none;box-shadow:0 0 0 0 rgba(125,226,211,0)}
+}
+
+@keyframes hyepl-jump-focus-mark{
+  0%{opacity:1;filter:none}
+  35%{opacity:.72;filter:brightness(1.2)}
+  100%{opacity:1;filter:none}
+}
+
+@media (prefers-reduced-motion:reduce){
+  .hyepl-jump-focus,.hyepl-jump-focus-mark{animation:none}
+}
 `;
 export class EBookPlayer {
     constructor(container, options) {
         this.runtimeDocument = null;
+        this.pendingTextInputResolver = null;
+        this.pendingTextInputMaxLength = 0;
         this.selectionDraft = null;
         this.loaded = false;
         this.destroyed = false;
@@ -60,6 +109,7 @@ export class EBookPlayer {
         };
         this.handleSelectionRepositionBound = () => {
             this.updateSelectionToolbarPosition();
+            this.updateBackToTopButtonPosition();
         };
         this.handleDocumentPointerDownBound = (event) => {
             this.handleDocumentPointerDown(event);
@@ -73,6 +123,37 @@ export class EBookPlayer {
         this.handleNoteClickBound = () => {
             void this.handleNoteClick();
         };
+        this.handleLoadWarningToggleBound = () => {
+            this.toggleLoadWarning();
+        };
+        this.handleLoadWarningCloseBound = () => {
+            this.hideLoadWarning();
+        };
+        this.handleTextInputCancelBound = () => {
+            this.finishTextInput(null);
+        };
+        this.handleTextInputConfirmBound = () => {
+            this.confirmTextInput();
+        };
+        this.handleTextInputBackdropPointerDownBound = (event) => {
+            if (event.target === this.textInputBackdrop) {
+                this.finishTextInput(null);
+            }
+        };
+        this.handleTextInputKeyDownBound = (event) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                this.finishTextInput(null);
+                return;
+            }
+            if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                this.confirmTextInput();
+            }
+        };
+        this.handleBackToTopClickBound = () => {
+            this.scrollToStoredPosition(0, "smooth");
+        };
         this.container = container;
         this.options = options;
         const runtimeProvider = createRuntimeProvider(options.provider, () => this.runtimeDocument);
@@ -87,6 +168,60 @@ export class EBookPlayer {
         this.content.className = "hyepl-content";
         this.selectionToolbar = document.createElement("div");
         this.selectionToolbar.className = "hyepl-selection-toolbar";
+        this.loadWarning = document.createElement("div");
+        this.loadWarning.className = "hyepl-load-warning";
+        const loadWarningHeader = document.createElement("div");
+        loadWarningHeader.className = "hyepl-load-warning-header";
+        const loadWarningTitle = document.createElement("span");
+        loadWarningTitle.className = "hyepl-load-warning-title";
+        loadWarningTitle.textContent = "加载数据异常";
+        const loadWarningActions = document.createElement("div");
+        loadWarningActions.className = "hyepl-load-warning-actions";
+        this.loadWarningToggleBtn = document.createElement("button");
+        this.loadWarningToggleBtn.type = "button";
+        this.loadWarningToggleBtn.className = "hyepl-load-warning-btn";
+        this.loadWarningCloseBtn = document.createElement("button");
+        this.loadWarningCloseBtn.type = "button";
+        this.loadWarningCloseBtn.className =
+            "hyepl-load-warning-btn hyepl-load-warning-close";
+        this.loadWarningCloseBtn.textContent = "×";
+        this.loadWarningCloseBtn.title = "关闭";
+        this.loadWarningCloseBtn.setAttribute("aria-label", "关闭加载异常提示");
+        this.loadWarningMessage = document.createElement("pre");
+        this.loadWarningMessage.className = "hyepl-load-warning-message";
+        loadWarningActions.append(this.loadWarningToggleBtn, this.loadWarningCloseBtn);
+        loadWarningHeader.append(loadWarningTitle, loadWarningActions);
+        this.loadWarning.append(loadWarningHeader, this.loadWarningMessage);
+        this.setLoadWarningExpanded(false);
+        this.textInputBackdrop = document.createElement("div");
+        this.textInputBackdrop.className = "hyepl-input-backdrop";
+        const textInputDialog = document.createElement("div");
+        textInputDialog.className = "hyepl-input-dialog";
+        this.textInputTitle = document.createElement("h4");
+        this.textInputTitle.className = "hyepl-input-title";
+        this.textInputTextarea = document.createElement("textarea");
+        this.textInputTextarea.className = "hyepl-input-textarea";
+        this.textInputError = document.createElement("p");
+        this.textInputError.className = "hyepl-input-error";
+        const textInputActions = document.createElement("div");
+        textInputActions.className = "hyepl-input-actions";
+        this.textInputCancelBtn = document.createElement("button");
+        this.textInputCancelBtn.type = "button";
+        this.textInputCancelBtn.className = "hyepl-input-btn";
+        this.textInputCancelBtn.textContent = "取消";
+        this.textInputConfirmBtn = document.createElement("button");
+        this.textInputConfirmBtn.type = "button";
+        this.textInputConfirmBtn.className = "hyepl-input-btn primary";
+        this.textInputConfirmBtn.textContent = "确认";
+        textInputActions.append(this.textInputCancelBtn, this.textInputConfirmBtn);
+        textInputDialog.append(this.textInputTitle, this.textInputTextarea, this.textInputError, textInputActions);
+        this.textInputBackdrop.append(textInputDialog);
+        this.backToTopBtn = document.createElement("button");
+        this.backToTopBtn.type = "button";
+        this.backToTopBtn.className = "hyepl-back-to-top";
+        this.backToTopBtn.innerHTML = BACK_TO_TOP_ICON_SVG;
+        this.backToTopBtn.title = "回到顶部";
+        this.backToTopBtn.setAttribute("aria-label", "回到顶部");
         this.highlightBtn = document.createElement("button");
         this.highlightBtn.type = "button";
         this.highlightBtn.className = "hyepl-toolbar-btn";
@@ -101,32 +236,51 @@ export class EBookPlayer {
         this.setToolbarButtonContent(this.noteBtn, NOTE_ICON_SVG, this.selectionOptions.noteButtonText);
         this.noteBtn.setAttribute("aria-label", this.selectionOptions.noteButtonText);
         this.selectionToolbar.append(this.highlightBtn, this.toolbarDivider, this.noteBtn);
-        this.root.append(this.content, this.selectionToolbar);
+        this.root.append(this.content, this.selectionToolbar, this.loadWarning, this.textInputBackdrop);
         this.container.innerHTML = "";
         this.container.append(this.root);
+        if (!this.container.style.position) {
+            this.container.style.position = "relative";
+        }
+        this.container.append(this.backToTopBtn);
         this.highlightBtn.addEventListener("mousedown", this.preserveSelectionOnToolbarMouseDownBound);
         this.noteBtn.addEventListener("mousedown", this.preserveSelectionOnToolbarMouseDownBound);
         this.highlightBtn.addEventListener("click", this.handleHighlightClickBound);
         this.noteBtn.addEventListener("click", this.handleNoteClickBound);
+        this.loadWarningToggleBtn.addEventListener("click", this.handleLoadWarningToggleBound);
+        this.loadWarningCloseBtn.addEventListener("click", this.handleLoadWarningCloseBound);
+        this.textInputCancelBtn.addEventListener("click", this.handleTextInputCancelBound);
+        this.textInputConfirmBtn.addEventListener("click", this.handleTextInputConfirmBound);
+        this.textInputBackdrop.addEventListener("pointerdown", this.handleTextInputBackdropPointerDownBound);
+        this.textInputTextarea.addEventListener("keydown", this.handleTextInputKeyDownBound);
+        this.backToTopBtn.addEventListener("click", this.handleBackToTopClickBound);
         document.addEventListener("selectionchange", this.handleSelectionChangeBound);
         document.addEventListener("pointerdown", this.handleDocumentPointerDownBound);
         window.addEventListener("scroll", this.handleSelectionRepositionBound, true);
         window.addEventListener("resize", this.handleSelectionRepositionBound);
+        this.updateBackToTopButtonPosition();
     }
     async load(doc) {
         if (doc) {
             this.runtimeDocument = cloneEbookDoc(doc);
         }
-        if (!this.options.provider && !this.runtimeDocument) {
-            throw new Error("Provider is not configured. Call load(doc) when using EBookPlayer without provider.");
+        try {
+            if (!this.options.provider && !this.runtimeDocument) {
+                throw new Error("Provider is not configured. Call load(doc) when using EBookPlayer without provider.");
+            }
+            const loadedDoc = await this.engine.load();
+            this.loaded = true;
+            if (this.options.initialAnnotations) {
+                await this.engine.setAnnotations(this.options.initialAnnotations, "api");
+            }
+            this.renderDocument();
+            this.hideLoadWarning();
+            return loadedDoc;
         }
-        const loadedDoc = await this.engine.load();
-        this.loaded = true;
-        if (this.options.initialAnnotations) {
-            await this.engine.setAnnotations(this.options.initialAnnotations, "api");
+        catch (error) {
+            this.showLoadWarning(error);
+            throw error;
         }
-        this.renderDocument();
-        return loadedDoc;
     }
     destroy() {
         if (this.destroyed) {
@@ -142,6 +296,19 @@ export class EBookPlayer {
         this.noteBtn.removeEventListener("mousedown", this.preserveSelectionOnToolbarMouseDownBound);
         this.highlightBtn.removeEventListener("click", this.handleHighlightClickBound);
         this.noteBtn.removeEventListener("click", this.handleNoteClickBound);
+        this.loadWarningToggleBtn.removeEventListener("click", this.handleLoadWarningToggleBound);
+        this.loadWarningCloseBtn.removeEventListener("click", this.handleLoadWarningCloseBound);
+        this.textInputCancelBtn.removeEventListener("click", this.handleTextInputCancelBound);
+        this.textInputConfirmBtn.removeEventListener("click", this.handleTextInputConfirmBound);
+        this.textInputBackdrop.removeEventListener("pointerdown", this.handleTextInputBackdropPointerDownBound);
+        this.textInputTextarea.removeEventListener("keydown", this.handleTextInputKeyDownBound);
+        this.backToTopBtn.removeEventListener("click", this.handleBackToTopClickBound);
+        if (this.pendingTextInputResolver) {
+            this.finishTextInput(null);
+        }
+        if (this.backToTopBtn.parentNode === this.container) {
+            this.container.removeChild(this.backToTopBtn);
+        }
         if (this.root.parentNode === this.container) {
             this.container.removeChild(this.root);
         }
@@ -226,7 +393,7 @@ export class EBookPlayer {
             throw new Error("Bookmark content is required when prompt is disabled.");
         }
         else {
-            content = this.promptTextWithLimit("请输入书签内容", current?.content || "", this.inputLimits.bookmarkMaxLength);
+            content = await this.promptTextWithLimit("请输入书签内容", current?.content || "", this.inputLimits.bookmarkMaxLength);
         }
         if (content === null) {
             return null;
@@ -236,6 +403,31 @@ export class EBookPlayer {
         this.renderDocument();
         return bookmark;
     }
+    async updateBookmark(bookmarkId, options = {}, source = "api") {
+        this.ensureLoaded();
+        const current = this.engine
+            .getBookmarks()
+            .find((item) => item.id === bookmarkId);
+        if (!current) {
+            return null;
+        }
+        let content = null;
+        if (typeof options.content === "string" && options.content.trim()) {
+            content = this.normalizeBookmarkContent(options.content);
+        }
+        else if (options.prompt === false) {
+            throw new Error("Bookmark content is required when prompt is disabled.");
+        }
+        else {
+            content = await this.promptTextWithLimit("请输入书签内容", current.content || "", this.inputLimits.bookmarkMaxLength);
+        }
+        if (content === null) {
+            return null;
+        }
+        const updated = await this.engine.updateBookmark(bookmarkId, { content }, source);
+        this.renderDocument();
+        return updated;
+    }
     async deleteBookmark(bookmarkId, source = "api") {
         this.ensureLoaded();
         const deleted = await this.engine.deleteBookmark(bookmarkId, source);
@@ -254,7 +446,13 @@ export class EBookPlayer {
         if (pageIndex === null) {
             return null;
         }
-        this.scrollToBlock(target.pageId, target.blockId);
+        const blockNode = this.scrollToBlock(target.pageId, target.blockId);
+        const selector = `mark.hyepl-highlight[data-highlight-id="${this.escapeSelectorValue(highlightId)}"]`;
+        this.focusAfterJump({
+            selector,
+            focusClass: "hyepl-jump-focus-mark",
+            fallbackNode: blockNode,
+        });
         return pageIndex;
     }
     goToNote(noteId) {
@@ -267,7 +465,13 @@ export class EBookPlayer {
         if (pageIndex === null) {
             return null;
         }
-        this.scrollToBlock(target.pageId, target.blockId);
+        const blockNode = this.scrollToBlock(target.pageId, target.blockId);
+        const selector = `mark.hyepl-note[data-note-id="${this.escapeSelectorValue(noteId)}"]`;
+        this.focusAfterJump({
+            selector,
+            focusClass: "hyepl-jump-focus-mark",
+            fallbackNode: blockNode,
+        });
         return pageIndex;
     }
     goToBookmark(bookmarkId) {
@@ -282,11 +486,30 @@ export class EBookPlayer {
         if (pageIndex === null) {
             return null;
         }
+        const bookmarkSelector = `.hyepl-bookmark-flag[data-bookmark-id="${this.escapeSelectorValue(bookmarkId)}"]`;
+        const bookmarkNode = this.content.querySelector(bookmarkSelector);
+        const fallbackNode = this.findBlockNode(target.pageId, target.blockId);
         if (Number.isFinite(target.scrollTop)) {
-            this.scrollToStoredPosition(target.scrollTop);
+            this.scrollToStoredPosition(target.scrollTop - BOOKMARK_JUMP_REVEAL_TOP_OFFSET_PX);
+            this.focusAfterJump({
+                selector: bookmarkSelector,
+                fallbackNode,
+            });
             return pageIndex;
         }
-        this.scrollToBlock(target.pageId, target.blockId);
+        if (bookmarkNode) {
+            this.scrollToNodeWithTopOffset(bookmarkNode, BOOKMARK_JUMP_REVEAL_TOP_OFFSET_PX);
+        }
+        else if (fallbackNode) {
+            this.scrollToNodeWithTopOffset(fallbackNode, BOOKMARK_JUMP_REVEAL_TOP_OFFSET_PX);
+        }
+        else {
+            this.scrollToBlock(target.pageId, target.blockId);
+        }
+        this.focusAfterJump({
+            selector: bookmarkSelector,
+            fallbackNode,
+        });
         return pageIndex;
     }
     onAnnotationCreate(listener) {
@@ -681,6 +904,7 @@ export class EBookPlayer {
             }
             const mark = document.createElement("mark");
             mark.className = "hyepl-highlight";
+            mark.dataset.highlightId = item.id;
             if (item.color) {
                 mark.style.setProperty("--hyepl-highlight-color", item.color);
             }
@@ -995,6 +1219,22 @@ export class EBookPlayer {
         this.selectionToolbar.classList.remove("show");
         this.selectionDraft = null;
     }
+    showLoadWarning(error) {
+        this.loadWarningMessage.textContent = resolveErrorMessage(error, "未知加载错误");
+        this.loadWarning.classList.add("show");
+        this.setLoadWarningExpanded(false);
+    }
+    hideLoadWarning() {
+        this.loadWarning.classList.remove("show");
+        this.setLoadWarningExpanded(false);
+    }
+    toggleLoadWarning() {
+        this.setLoadWarningExpanded(!this.loadWarning.classList.contains("expanded"));
+    }
+    setLoadWarningExpanded(expanded) {
+        this.loadWarning.classList.toggle("expanded", expanded);
+        this.loadWarningToggleBtn.textContent = expanded ? "收起" : "详情";
+    }
     clearSelection() {
         window.getSelection()?.removeAllRanges();
     }
@@ -1059,29 +1299,30 @@ export class EBookPlayer {
         this.hideSelectionToolbar();
     }
     async handleNoteClick() {
-        if (!this.selectionDraft) {
+        const selectionDraft = this.selectionDraft;
+        if (!selectionDraft) {
             return;
         }
         const defaultText = "";
-        const content = this.promptTextWithLimit("请输入笔记内容", defaultText, this.inputLimits.noteMaxLength);
+        const content = await this.promptTextWithLimit("请输入笔记内容", defaultText, this.inputLimits.noteMaxLength);
         if (content === null) {
             return;
         }
-        const segments = this.selectionDraft.segments && this.selectionDraft.segments.length
-            ? this.selectionDraft.segments
+        const segments = selectionDraft.segments && selectionDraft.segments.length
+            ? selectionDraft.segments
             : [
                 {
-                    pageId: this.selectionDraft.pageId,
-                    blockId: this.selectionDraft.blockId,
-                    range: this.selectionDraft.range,
-                    text: this.selectionDraft.text,
+                    pageId: selectionDraft.pageId,
+                    blockId: selectionDraft.blockId,
+                    range: selectionDraft.range,
+                    text: selectionDraft.text,
                 },
             ];
         const firstSegment = segments[0];
         if (!firstSegment) {
             return;
         }
-        const mergedSelectedText = this.selectionDraft.text ||
+        const mergedSelectedText = selectionDraft.text ||
             segments
                 .map((segment) => segment.text)
                 .filter(Boolean)
@@ -1113,6 +1354,41 @@ export class EBookPlayer {
         }
         return Math.max(320, Math.round(width));
     }
+    updateBackToTopButtonPosition() {
+        const hostRect = this.container.getBoundingClientRect();
+        const hostWidth = this.container.clientWidth || hostRect.width;
+        const hostHeight = this.container.clientHeight || hostRect.height;
+        const buttonWidth = this.backToTopBtn.offsetWidth || 52;
+        const buttonHeight = this.backToTopBtn.offsetHeight || 52;
+        const margin = 16;
+        if (hostWidth <= 0 || hostHeight <= 0) {
+            this.backToTopBtn.classList.add("hidden");
+            return;
+        }
+        const viewportLeft = 0;
+        const viewportTop = 0;
+        const viewportRight = window.innerWidth;
+        const viewportBottom = window.innerHeight;
+        const desiredViewportLeft = Math.min(hostRect.right - buttonWidth - margin, viewportRight - buttonWidth - margin);
+        const desiredViewportTop = viewportBottom - buttonHeight - margin;
+        const minViewportLeft = Math.max(viewportLeft + margin, hostRect.left + margin);
+        const maxViewportLeft = Math.min(viewportRight - buttonWidth - margin, hostRect.right - buttonWidth - margin);
+        const minViewportTop = Math.max(viewportTop + margin, hostRect.top + margin);
+        const maxViewportTop = Math.min(viewportBottom - buttonHeight - margin, hostRect.bottom - buttonHeight - margin);
+        if (maxViewportLeft < minViewportLeft || maxViewportTop < minViewportTop) {
+            this.backToTopBtn.classList.add("hidden");
+            return;
+        }
+        const clampedViewportLeft = Math.max(minViewportLeft, Math.min(desiredViewportLeft, maxViewportLeft));
+        const clampedViewportTop = Math.max(minViewportTop, Math.min(desiredViewportTop, maxViewportTop));
+        const localLeft = clampedViewportLeft - hostRect.left;
+        const localTop = clampedViewportTop - hostRect.top;
+        this.backToTopBtn.style.left = `${Math.round(localLeft)}px`;
+        this.backToTopBtn.style.top = `${Math.round(localTop)}px`;
+        this.backToTopBtn.style.right = "auto";
+        this.backToTopBtn.style.bottom = "auto";
+        this.backToTopBtn.classList.remove("hidden");
+    }
     resolveSelectionToolbarOptions(options) {
         const highlightButtonText = typeof options?.highlightButtonText === "string" &&
             options.highlightButtonText.trim()
@@ -1150,24 +1426,43 @@ export class EBookPlayer {
         return Math.max(1, Math.floor(value));
     }
     promptTextWithLimit(title, defaultText, maxLength) {
-        let nextDefault = defaultText;
-        while (true) {
-            const raw = window.prompt(`${title}（最多${maxLength}字）`, nextDefault);
-            if (raw === null) {
-                return null;
-            }
-            const trimmed = raw.trim();
-            if (!trimmed) {
-                window.alert("内容不能为空");
-                nextDefault = "";
-                continue;
-            }
-            if (trimmed.length > maxLength) {
-                window.alert(`最多输入${maxLength}字，当前${trimmed.length}字。`);
-                nextDefault = trimmed.slice(0, maxLength);
-                continue;
-            }
-            return trimmed;
+        if (this.pendingTextInputResolver) {
+            this.finishTextInput(null);
+        }
+        this.pendingTextInputMaxLength = maxLength;
+        this.textInputTitle.textContent = `${title}（最多${maxLength}字）`;
+        this.textInputTextarea.value = defaultText;
+        this.textInputError.textContent = "";
+        this.textInputBackdrop.classList.add("show");
+        window.setTimeout(() => {
+            this.textInputTextarea.focus();
+            this.textInputTextarea.setSelectionRange(this.textInputTextarea.value.length, this.textInputTextarea.value.length);
+        }, 0);
+        return new Promise((resolve) => {
+            this.pendingTextInputResolver = resolve;
+        });
+    }
+    confirmTextInput() {
+        const raw = this.textInputTextarea.value || "";
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            this.textInputError.textContent = "内容不能为空";
+            return;
+        }
+        if (trimmed.length > this.pendingTextInputMaxLength) {
+            this.textInputError.textContent = `最多输入${this.pendingTextInputMaxLength}字，当前${trimmed.length}字。`;
+            return;
+        }
+        this.finishTextInput(trimmed);
+    }
+    finishTextInput(value) {
+        const resolver = this.pendingTextInputResolver;
+        this.pendingTextInputResolver = null;
+        this.pendingTextInputMaxLength = 0;
+        this.textInputBackdrop.classList.remove("show");
+        this.textInputError.textContent = "";
+        if (resolver) {
+            resolver(value);
         }
     }
     normalizeBookmarkContent(raw) {
@@ -1220,15 +1515,18 @@ export class EBookPlayer {
         }
         return { pageId, blockId };
     }
-    scrollToBlock(pageId, blockId) {
+    findBlockNode(pageId, blockId) {
         const page = this.escapeSelectorValue(pageId);
         const block = this.escapeSelectorValue(blockId);
-        const node = this.content.querySelector(`[data-page-id="${page}"][data-block-id="${block}"]`);
+        return this.content.querySelector(`[data-page-id="${page}"][data-block-id="${block}"]`);
+    }
+    scrollToBlock(pageId, blockId, behavior = "smooth") {
+        const node = this.findBlockNode(pageId, blockId);
         if (!node) {
-            return false;
+            return null;
         }
-        node.scrollIntoView({ block: "start" });
-        return true;
+        node.scrollIntoView({ block: "start", behavior });
+        return node;
     }
     getCurrentScrollTop() {
         const scrollHost = this.resolveScrollHost();
@@ -1237,14 +1535,59 @@ export class EBookPlayer {
         }
         return Math.max(0, Math.floor(scrollHost.scrollTop || 0));
     }
-    scrollToStoredPosition(scrollTop) {
+    scrollToStoredPosition(scrollTop, behavior = "smooth") {
         const safeTop = Math.max(0, Math.floor(scrollTop || 0));
         const scrollHost = this.resolveScrollHost();
         if (this.isWindowScrollHost(scrollHost)) {
-            window.scrollTo({ top: safeTop, behavior: "auto" });
+            window.scrollTo({ top: safeTop, behavior });
+            return;
+        }
+        scrollHost.scrollTo({ top: safeTop, behavior });
+    }
+    scrollToNodeWithTopOffset(node, topOffset, behavior = "smooth") {
+        const safeOffset = Math.max(0, Math.floor(topOffset || 0));
+        const scrollHost = this.resolveScrollHost();
+        if (this.isWindowScrollHost(scrollHost)) {
+            const absoluteTop = node.getBoundingClientRect().top + window.scrollY;
+            const targetTop = Math.max(0, Math.floor(absoluteTop - safeOffset));
+            window.scrollTo({ top: targetTop, behavior });
             return;
         }
-        scrollHost.scrollTo({ top: safeTop, behavior: "auto" });
+        const hostRect = scrollHost.getBoundingClientRect();
+        const relativeTop = node.getBoundingClientRect().top - hostRect.top + scrollHost.scrollTop;
+        const targetTop = Math.max(0, Math.floor(relativeTop - safeOffset));
+        scrollHost.scrollTo({ top: targetTop, behavior });
+    }
+    focusAfterJump(options) {
+        const { selector, focusClass = "hyepl-jump-focus", fallbackNode = null, } = options;
+        this.deferFocus(() => {
+            const matched = Array.from(this.content.querySelectorAll(selector));
+            if (matched.length) {
+                this.playFocusAnimation(matched, focusClass);
+                return;
+            }
+            if (fallbackNode) {
+                this.playFocusAnimation([fallbackNode], "hyepl-jump-focus");
+            }
+        });
+    }
+    deferFocus(task) {
+        window.setTimeout(task, JUMP_SCROLL_FOCUS_DELAY_MS);
+    }
+    playFocusAnimation(nodes, className = "hyepl-jump-focus") {
+        const seen = new Set();
+        for (const node of nodes) {
+            if (!node || !this.content.contains(node) || seen.has(node)) {
+                continue;
+            }
+            seen.add(node);
+            node.classList.remove(className);
+            void node.offsetWidth;
+            node.classList.add(className);
+            window.setTimeout(() => {
+                node.classList.remove(className);
+            }, JUMP_FOCUS_ANIMATION_MS + 40);
+        }
     }
     resolveScrollHost() {
         let current = this.container;
@@ -1397,3 +1740,12 @@ function escapeHtml(value) {
 function escapeAttribute(value) {
     return escapeHtml(value);
 }
+function resolveErrorMessage(error, fallback = "未知错误") {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    if (typeof error === "string" && error.trim()) {
+        return error.trim();
+    }
+    return fallback;
+}

package/dist/core/src/player/engine.d.ts

@@ -1,5 +1,5 @@
 import type { EbookDoc } from "../types/ebook";
-import type { ReaderAnnotationCreateEvent, ReaderAnnotationDeleteEvent, ReaderAnnotations, ReaderAnnotationsChangeEvent, ReaderAnnotationUpdateEvent, ReaderBookmark, ReaderHighlight, PlayerDataProvider, PlayerEngineOptions, PlayerFeatures, ReaderNote, ReaderProgress } from "../types/player";
+import type { ReaderAnnotationCreateEvent, ReaderAnnotationDeleteEvent, ReaderAnnotations, ReaderAnnotationsChangeEvent, ReaderAnnotationUpdateEvent, ReaderBookmark, ReaderBookmarkPatch, ReaderHighlight, PlayerDataProvider, PlayerEngineOptions, PlayerFeatures, ReaderNote, ReaderProgress } from "../types/player";
 export interface PlayerState {
     currentPage: number;
     zoom: number;
@@ -49,6 +49,7 @@ export declare class PlayerEngine {
     updateNote(noteId: string, patch: Partial<Omit<ReaderNote, "id" | "bookId" | "createdAt">>, source?: "api" | "user"): Promise<ReaderNote | null>;
     deleteNote(noteId: string, source?: "api" | "user"): Promise<boolean>;
     setBookmark(pageId: string, blockId: string, content: string, source?: "api" | "user", scrollTop?: number): Promise<ReaderBookmark>;
+    updateBookmark(bookmarkId: string, patch: ReaderBookmarkPatch, source?: "api" | "user"): Promise<ReaderBookmark | null>;
     deleteBookmark(bookmarkId: string, source?: "api" | "user"): Promise<boolean>;
     onAnnotationCreate(listener: AnnotationCreateListener): () => void;
     onAnnotationUpdate(listener: AnnotationUpdateListener): () => void;