Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
feat(source-preview): enhance HTML source preview with viewport scaling and navigation handling
myhloli2cf4e40516e6
diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.pyindex 296eab31..0c916c8f 100644--- a/mineru/kit/gradio/app.py+++ b/mineru/kit/gradio/app.py@@ -185,6 +185,14 @@ _KIT_MENU_CSS = """.mineru-kit-pdf-preview .html-container, .mineru-kit-pdf-preview .prose,.mineru-kit-source-preview .html-container, .mineru-kit-source-preview .prose { height: 100%; padding: 0 !important; }.mineru-kit-pdf-preview:not(:has(.mineru-pdf-frame, [role="alert"])) { display: none !important; }+/* HTML 源预览用固定 viewport 裁剪逻辑舞台。缩放舞台而不是 iframe 本体,+ 避免 Safari/WebKit 在 transform iframe 时把子文档绘制层裁成局部区域。 */+.mineru-source-viewport {+ position: relative; display: block; width: 100%; height: 100%; min-height: 0; overflow: hidden;+}+.mineru-source-stage {+ display: block; width: 100%; height: 100%; min-height: 0; transform-origin: 0 0;+}.mineru-pdf-frame, .mineru-source-frame, .mineru-epub-frame {display: block; width: 100%; height: 100%; min-height: 0; border: 0;}diff --git a/mineru/kit/gradio/source_preview.py b/mineru/kit/gradio/source_preview.pyindex 068e796c..9dd7a520 100644--- a/mineru/kit/gradio/source_preview.py+++ b/mineru/kit/gradio/source_preview.py@@ -9,7 +9,9 @@ import jsonimport refrom collections.abc import Callablefrom pathlib import Path+from urllib.parse import urlsplit+from bs4 import BeautifulSoupfrom loguru import loggerfrom .i18n import preview_placeholder@@ -17,16 +19,117 @@ from .ofd_preview import build_ofd_preview__all__ = ["build_html_preview", "prepare_source_preview"]-# 与结果预览一致允许脚本执行:MathJax/KaTeX 等公式排版依赖内联配置、eval 加载-# 与 XHR 拉取字体;沙箱保持 opaque origin(无 allow-same-origin),隔离父页面、-# 存储与顶级导航,媒体、内嵌框架和表单仍由 default-src 'none' 封禁。+# 源 HTML 预览以视觉兼容性优先:允许原页面脚本和联网资源,但继续依赖 sandbox 的+# opaque origin 隔离 MinerU 父页面,同时显式禁用表单、子框架、对象和 Worker。+_REFERRER_META = '<meta name="referrer" content="no-referrer">'+_CSP_META = ('<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '"script-src 'unsafe-inline' 'unsafe-eval' https: http:; ""style-src 'unsafe-inline' https: http:; img-src data: blob: https: http:; "- 'font-src data: blob: https:; connect-src https: http:">'+ "font-src data: blob: https: http:; connect-src https: http:; media-src data: blob: https: http:; "+ "object-src 'none'; frame-src 'none'; worker-src 'none'; form-action 'none'\">"+)++_NAVIGATION_HANDLER_PATTERN = re.compile(+ r"""(?ix)+ (?:+ (?:window|document|top|parent|self|globalThis)\s*\.\s*location\b+ |(?<![\w$.])location\s*(?:\.|\[|=)+ |window\s*\.\s*open\s*\(+ )+ """)+# sandbox 的 opaque origin 让父页面无法读取 iframe 的实际排版宽度,因此由源文档主动+# 上报首轮稳定布局宽度。不能直接使用整页 scrollWidth:Safari/WebKit 会把横向轮播的+# 离屏 slide 计入文档宽度,导致虚拟视口被错误放大到数千像素。+_SOURCE_PREVIEW_BRIDGE = """<script id="mineru-source-preview-bridge">+(function () {+ function explicitViewportWidth() {+ var injected = document.querySelector('meta[name="mineru-source-preview-width"]');+ var injectedWidth = injected ? Number(injected.getAttribute("content")) : 0;+ if (injectedWidth >= 320 && injectedWidth <= 2400) return injectedWidth;++ var viewport = document.querySelector('meta[name="viewport"]');+ var content = viewport ? String(viewport.getAttribute("content") || "") : "";+ var match = content.match(/(?:^|[,;\\s])width\\s*=\\s*(\\d{3,4})(?:$|[,;\\s])/i);+ if (match) {+ var numeric = Number(match[1]);+ if (numeric >= 320 && numeric <= 2400) return numeric;+ }+ var device = document.querySelector('meta[name="applicable-device"]');+ var deviceContent = device ? String(device.getAttribute("content") || "").toLowerCase() : "";+ if (/(^|[,;\\s])pc($|[,;\\s])/.test(deviceContent)) return 1200;+ return 0;+ }++ function structuralWidth() {+ var root = document.documentElement;+ var body = document.body;+ var viewportWidth = root ? root.clientWidth : innerWidth;+ var width = viewportWidth || innerWidth || 0;+ if (!body) return width;+ for (var i = 0; i < body.children.length; i++) {+ var element = body.children[i];+ var style = getComputedStyle(element);+ if (style.display === "none" || style.visibility === "hidden") continue;+ var rect = element.getBoundingClientRect();+ if (!Number.isFinite(rect.width) || rect.width <= 0) continue;+ // 只看 body 顶层布局盒,忽略 swiper/横向滚动容器内部的离屏子项。+ width = Math.max(width, rect.right - Math.min(0, rect.left));+ }+ return Math.min(Math.max(width, viewportWidth), 2400);+ }++ var preferredWidth = 0;+ function measurePreferredWidth() {+ var explicit = explicitViewportWidth();+ if (explicit) {+ preferredWidth = explicit;+ return preferredWidth;+ }+ var measured = structuralWidth();+ if (!preferredWidth || measured > preferredWidth) preferredWidth = measured;+ return preferredWidth;+ }++ function publishSize() {+ var root = document.documentElement;+ var body = document.body;+ var height = Math.max(+ root ? root.scrollHeight : 0,+ body ? body.scrollHeight : 0,+ root ? root.clientHeight : 0+ );+ parent.postMessage({+ type: "mineru-source-preview-size",+ width: measurePreferredWidth(),+ height: height+ }, "*");+ }++ var initialWidth = explicitViewportWidth();+ if (initialWidth) {+ preferredWidth = initialWidth;+ parent.postMessage({+ type: "mineru-source-preview-size",+ width: initialWidth,+ height: 0+ }, "*");+ }++ addEventListener("load", function () {+ // 无显式宽度时等外部 CSS 与页面初始化脚本完成首轮布局,避免 Safari 过早锁定单列宽度。+ requestAnimationFrame(function () {+ requestAnimationFrame(publishSize);+ });+ setTimeout(publishSize, 250);+ setTimeout(publishSize, 1000);+ }, {once: true});+})();+</script>"""+# 只嗅探文档头部即可覆盖 meta 声明,避免扫描超大文件。_CHARSET_SNIFF_SIZE = 4096_CHARSET_PATTERN = re.compile(rb"""charset\s*=\s*["']?\s*([A-Za-z0-9_.:+-]+)""", re.IGNORECASE)@@ -63,13 +166,111 @@ def _inject_head(document: str, snippet: str) -> str:return f"<head>{snippet}</head>" + document+def _remove_auto_navigation_handlers(soup: BeautifulSoup) -> None:+ """移除内联事件中明确会发起页面导航的处理器,普通交互事件保持原样。"""+ for tag in soup.find_all(True):+ for attribute, value in list(tag.attrs.items()):+ if not attribute.lower().startswith("on"):+ continue+ source = " ".join(value) if isinstance(value, list) else str(value)+ if _NAVIGATION_HANDLER_PATTERN.search(source):+ del tag.attrs[attribute]+++def _source_viewport_width_hint(soup: BeautifulSoup) -> int:+ """从源文档声明推断稳定的桌面预览宽度,供 Safari 在资源加载前立即完成缩放。"""+ viewport = soup.find("meta", attrs={"name": re.compile(r"^viewport$", re.IGNORECASE)})+ if viewport is not None:+ content = str(viewport.get("content", ""))+ match = re.search(r"(?:^|[,;\s])width\s*=\s*(\d{3,4})(?:$|[,;\s])", content, re.IGNORECASE)+ if match:+ width = int(match.group(1))+ if 320 <= width <= 2400:+ return width++ device = soup.find("meta", attrs={"name": re.compile(r"^applicable-device$", re.IGNORECASE)})+ if device is not None:+ content = str(device.get("content", "")).lower()+ if re.search(r"(^|[,;\s])pc($|[,;\s])", content):+ return 1200+ return 0+++def _source_base_url(soup: BeautifulSoup) -> str | None:+ """从已有 base、canonical 或 og:url 中恢复网页资源的原始解析基址。"""+ existing = soup.find("base", href=True)+ if existing is not None:+ try:+ if urlsplit(str(existing["href"])).scheme.lower() in {"http", "https"}:+ return None+ except ValueError:+ pass+ existing.decompose()++ canonical = None+ for link in soup.find_all("link", href=True):+ rel = link.get("rel", [])+ values = rel if isinstance(rel, list) else [rel]+ if "canonical" in {str(item).lower() for item in values}:+ canonical = link+ break+ candidates = [canonical.get("href") if canonical is not None else None]+ og_url = soup.find("meta", attrs={"property": "og:url"})+ candidates.append(og_url.get("content") if og_url is not None else None)+ for candidate in candidates:+ if not candidate:+ continue+ try:+ if urlsplit(str(candidate)).scheme.lower() in {"http", "https"}:+ return str(candidate)+ except ValueError:+ continue+ return None+++def _prepare_source_html_preview(document: str) -> tuple[str, int]:+ """清理自动导航、恢复原网页资源基址,并返回预览文档与稳定视口宽度提示。"""+ soup = BeautifulSoup(document, "html.parser")+ for meta in soup.find_all("meta"):+ directive = str(meta.get("http-equiv", "")).strip().lower()+ name = str(meta.get("name", "")).strip().lower()+ if directive in {"refresh", "content-security-policy"} or name == "referrer":+ meta.decompose()++ _remove_auto_navigation_handlers(soup)+ # 文档策略无法覆盖标签显式声明的策略,统一已有覆盖值以免重新发送本地 Referer。+ for tag in soup.find_all(attrs={"referrerpolicy": True}):+ tag["referrerpolicy"] = "no-referrer"++ for link in soup.find_all("a", href=True):+ try:+ scheme = urlsplit(str(link["href"])).scheme.lower()+ except ValueError:+ continue+ if scheme not in {"http", "https"}:+ continue+ link["target"] = "_blank"+ link["rel"] = list(dict.fromkeys([*link.get("rel", []), "noopener", "noreferrer"]))++ width_hint = _source_viewport_width_hint(soup)+ hint = f'<meta name="mineru-source-preview-width" content="{width_hint}">' if width_hint else ""+ base_url = _source_base_url(soup)+ base = f'<base href="{html.escape(base_url, quote=True)}">' if base_url is not None else ""+ prepared = _inject_head(str(soup), f"{_REFERRER_META}{hint}{base}{_CSP_META}{_SOURCE_PREVIEW_BRIDGE}")+ return prepared, width_hint++def build_html_preview(payload: bytes) -> str:- """按声明编码解码源 HTML,并在仅开放脚本的隔离框架中显示自包含页面。"""- document = _inject_head(_decode_html(payload), _CSP_META)- return (- '<iframe class="mineru-source-frame" title="HTML preview" sandbox="allow-scripts" '+ """按声明编码解码源 HTML,并在允许脚本但保持 opaque origin 的隔离框架中显示页面。"""+ document, width_hint = _prepare_source_html_preview(_decode_html(payload))+ width_attribute = f' data-mineru-source-content-width="{width_hint}"' if width_hint else ""+ frame = (+ f'<iframe class="mineru-source-frame"{width_attribute} title="HTML preview" '+ 'sandbox="allow-scripts" referrerpolicy="no-referrer" 'f'srcdoc="{html.escape(document, quote=True)}"></iframe>')+ # 外层舞台负责缩放,iframe 保留桌面布局视口,避免窄预览面板改变源页面排版。+ return f'<div class="mineru-source-viewport"><div class="mineru-source-stage">{frame}</div></div>'# 后缀到预览构造器和失败占位键的显式映射,避免运行时注册。diff --git a/mineru/resources/gradio_source_preview.js b/mineru/resources/gradio_source_preview.jsindex 8340d10b..7efd5d52 100644--- a/mineru/resources/gradio_source_preview.js+++ b/mineru/resources/gradio_source_preview.js@@ -23,6 +23,98 @@"&": "&", "<": "<", ">": ">", '"': """, "'": "'",})[character]);+ // 源 HTML 可以执行自身脚本,但初始化完成后若 iframe 又发生整页导航,则恢复原始 srcdoc。+ // HTML 的桌面视口缩放只作用于 iframe 外层舞台:WebKit 直接 transform iframe 时会出现+ // 内部页面布局正确、但绘制层只更新局部区域的现象,典型表现就是大块空白和正文被截断。+ const navigationGuardKey = `${key}NavigationGuard`;+ const sizeGuardKey = `${key}SizeGuard`;+ const fitSourceFrame = (frame, reportedWidth = null) => {+ if (!frame?.classList?.contains("mineru-source-frame")) return;+ const stage = frame.parentElement?.classList?.contains("mineru-source-stage") ? frame.parentElement : null;+ const viewport = stage?.parentElement;+ if (!stage || !viewport?.classList?.contains("mineru-source-viewport")) return;+ const availableWidth = viewport.clientWidth;+ const availableHeight = viewport.clientHeight;+ const measured = Number(reportedWidth ?? frame.dataset?.mineruSourceContentWidth ?? availableWidth);+ if (!Number.isFinite(measured) || availableWidth <= 0 || availableHeight <= 0) return;+ const contentWidth = Math.min(Math.max(measured, availableWidth), 2400);+ frame.dataset.mineruSourceContentWidth = String(contentWidth);+ const scale = Math.min(1, availableWidth / contentWidth);++ // iframe 始终只填满逻辑舞台,不在自身创建缩放合成层,避免 Safari/WebKit 的绘制裁剪。+ frame.style.width = "100%";+ frame.style.height = "100%";+ frame.style.transform = "";+ frame.style.transformOrigin = "";+ if (scale >= 0.995) {+ stage.style.width = "100%";+ stage.style.height = "100%";+ stage.style.transform = "";+ stage.style.transformOrigin = "";+ return;+ }+ stage.style.width = `${contentWidth}px`;+ stage.style.height = `${availableHeight / scale}px`;+ stage.style.transformOrigin = "0 0";+ stage.style.transform = `scale(${scale})`;+ };+ const observeSourceFrame = (frame) => {+ if (!frame || frame.dataset?.mineruSourceObserved === "1") return;+ const stage = frame.parentElement?.classList?.contains("mineru-source-stage") ? frame.parentElement : null;+ const viewport = stage?.parentElement;+ frame.dataset.mineruSourceObserved = "1";+ if (typeof ResizeObserver === "function" && viewport?.classList?.contains("mineru-source-viewport")) {+ new ResizeObserver(() => fitSourceFrame(frame)).observe(viewport);+ }+ };+ const installNavigationGuard = () => {+ if (window[navigationGuardKey] || typeof document === "undefined") return;+ const states = new WeakMap();+ document.addEventListener("load", (event) => {+ const frame = event.target;+ if (!frame || frame.tagName !== "IFRAME" || !frame.classList?.contains("mineru-source-frame")) return;+ const frameId = frame.dataset?.mineruSourcePreviewId;+ if (!frameId || frameId !== String(window[key])) return;+ observeSourceFrame(frame);+ fitSourceFrame(frame);+ const state = states.get(frame);+ if (!state) {+ states.set(frame, {restoring: false});+ return;+ }+ if (state.restoring) {+ state.restoring = false;+ return;+ }+ const source = frame.getAttribute?.("srcdoc");+ if (!source) return;+ state.restoring = true;+ frame.srcdoc = source;+ }, true);+ window[navigationGuardKey] = true;+ };+ const installSizeGuard = () => {+ if (window[sizeGuardKey] || typeof window.addEventListener !== "function") return;+ window.addEventListener("message", (event) => {+ if (event.data?.type !== "mineru-source-preview-size") return;+ for (const frame of document.querySelectorAll?.("iframe.mineru-source-frame") || []) {+ if (frame.contentWindow !== event.source) continue;+ const frameId = frame.dataset?.mineruSourcePreviewId;+ if (!frameId || frameId !== String(window[key])) return;+ observeSourceFrame(frame);+ fitSourceFrame(frame, event.data.width);+ return;+ }+ });+ window[sizeGuardKey] = true;+ };+ const markSourceFrame = (markup, id) => String(markup).replace(+ '<iframe class="mineru-source-frame"',+ `<iframe class="mineru-source-frame" data-mineru-source-preview-id="${escapeHtml(id)}"`,+ );+ installNavigationGuard();+ installSizeGuard();+if (action === "begin" || action === "clear") {const file = action === "clear" ? null : args[0];window[key] = (window[key] || 0) + 1;@@ -32,7 +124,7 @@}const receipt = JSON.parse(args[0]);if (receipt.id !== window[key]) return skip();- if (receipt.kind !== "epub") return receipt.html;+ if (receipt.kind !== "epub") return markSourceFrame(receipt.html, receipt.id);// EPUB viewer 本身是静态资源,书籍和 viewer 都必须来自当前 Gradio origin。const viewer = args[1];diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.pyindex 2a5c9043..875e8bf1 100644--- a/tests/unittest/test_kit_gradio.py+++ b/tests/unittest/test_kit_gradio.py@@ -1152,6 +1152,9 @@ def test_build_gradio_app_exposes_html_tab_and_download_menu(tmp_path: Path) ->assert ".mineru-kit-results .mineru-markdown-output,\n .mineru-kit-results .mineru-structured-json" in app._mineru_kit_cssassert ".mineru-kit-results { min-height: 0; flex: 0 0 auto !important; }" in app._mineru_kit_cssassert ".mineru-kit-source-preview:has(.mineru-epub-frame)" in app._mineru_kit_css+ # Safari 不能直接缩放源 iframe;固定 viewport 与可缩放舞台必须随应用 CSS 一起注入。+ assert ".mineru-source-viewport" in app._mineru_kit_css+ assert ".mineru-source-stage" in app._mineru_kit_cssassert "flex: 0 0 auto !important;" in app._mineru_kit_cssassert sum(1 for dependency in app.config["dependencies"] if dependency.get("queue") is True) >= 7diff --git a/tests/unittest/test_kit_gradio_source_preview.cjs b/tests/unittest/test_kit_gradio_source_preview.cjsindex 8c2a39c0..e74c1e7b 100644--- a/tests/unittest/test_kit_gradio_source_preview.cjs+++ b/tests/unittest/test_kit_gradio_source_preview.cjs@@ -3,8 +3,28 @@ const fs = require('node:fs');const path = require('node:path');const vm = require('node:vm');let sequence = 0;+const listeners = {};+const windowListeners = {};+const sourceFrames = [];+const browserWindow = {+ location: {href: 'https://demo.example.test/mineru/', origin: 'https://demo.example.test'},+ addEventListener(type, listener) {+ windowListeners[type] = listener;+ },+};+const browserDocument = {+ addEventListener(type, listener, capture) {+ assert.equal(capture, true);+ listeners[type] = listener;+ },+ querySelectorAll(selector) {+ assert.equal(selector, 'iframe.mineru-source-frame');+ return sourceFrames;+ },+};const preview = vm.runInNewContext(fs.readFileSync(path.join(__dirname, '../../mineru/resources/gradio_source_preview.js'), 'utf8'), {- window: {location: {href: 'https://demo.example.test/mineru/', origin: 'https://demo.example.test'}},+ window: browserWindow,+ document: browserDocument,URL,URLSearchParams,crypto: {randomUUID: () => String(++sequence)},@@ -19,6 +39,66 @@ const third = JSON.parse(preview('begin', {path: '/second.ofd'})[0]);assert.notEqual(third.id, second.id);assert.equal(preview('apply', JSON.stringify({id: third.id, html: 'reload'})), 'reload');+const htmlTicket = JSON.parse(preview('begin', {path: '/page.html'})[0]);+const sourceMarkup = '<div class="mineru-source-viewport"><div class="mineru-source-stage">' ++ '<iframe class="mineru-source-frame" title="HTML preview" srcdoc="<p>source</p>"></iframe></div></div>';+const guardedMarkup = preview('apply', JSON.stringify({id: htmlTicket.id, html: sourceMarkup}));+assert.match(guardedMarkup, new RegExp(`data-mineru-source-preview-id="${htmlTicket.id}"`));+assert.equal(typeof listeners.load, 'function');++let restores = 0;+const sourceViewport = {+ classList: {contains: (name) => name === 'mineru-source-viewport'},+ clientWidth: 600,+ clientHeight: 800,+};+const sourceStage = {+ classList: {contains: (name) => name === 'mineru-source-stage'},+ parentElement: sourceViewport,+ style: {},+};+const sourceFrame = {+ tagName: 'IFRAME',+ classList: {contains: (name) => name === 'mineru-source-frame'},+ dataset: {mineruSourcePreviewId: String(htmlTicket.id), mineruSourceContentWidth: "1200"},+ parentElement: sourceStage,+ style: {},+ contentWindow: {},+ getAttribute: (name) => name === 'srcdoc' ? '<p>source</p>' : null,+ set srcdoc(value) {+ restores += 1;+ assert.equal(value, '<p>source</p>');+ },+};+sourceFrames.push(sourceFrame);+listeners.load({target: sourceFrame});+assert.equal(restores, 0);+assert.equal(sourceFrame.style.width, '100%');+assert.equal(sourceFrame.style.height, '100%');+assert.equal(sourceFrame.style.transform, '');+assert.equal(sourceStage.style.width, '1200px');+assert.equal(sourceStage.style.height, '1600px');+assert.equal(sourceStage.style.transform, 'scale(0.5)');+assert.equal(typeof windowListeners.message, 'function');+windowListeners.message({+ source: sourceFrame.contentWindow,+ data: {type: 'mineru-source-preview-size', width: 1200, height: 2400},+});+assert.equal(sourceFrame.style.width, '100%');+assert.equal(sourceFrame.style.height, '100%');+assert.equal(sourceFrame.style.transformOrigin, '');+assert.equal(sourceFrame.style.transform, '');+assert.equal(sourceStage.style.width, '1200px');+assert.equal(sourceStage.style.height, '1600px');+assert.equal(sourceStage.style.transformOrigin, '0 0');+assert.equal(sourceStage.style.transform, 'scale(0.5)');+listeners.load({target: sourceFrame});+assert.equal(restores, 1);+listeners.load({target: sourceFrame});+assert.equal(restores, 1);+listeners.load({target: sourceFrame});+assert.equal(restores, 2);+const epub = {path: '/tmp/中文 book.epub', url: '/gradio_api/file=/tmp/中文 book.epub'};const viewer = {path: '/tmp/reader.html', url: '/gradio_api/file=/tmp/reader.html'};const epubTicket = JSON.parse(preview('begin', epub)[0]);@@ -29,4 +109,5 @@ assert.match(epubFrame, /epub_spine/);assert.doesNotMatch(epubFrame, /epub_page/);preview('clear');assert.equal(preview('apply', JSON.stringify({id: epubTicket.id, kind: 'epub'}), viewer).__type__, 'update');+console.log('Source preview: switch, clear, re-upload and stale receipts passed');diff --git a/tests/unittest/test_kit_gradio_source_preview.py b/tests/unittest/test_kit_gradio_source_preview.pyindex 36a01d6c..96a43563 100644--- a/tests/unittest/test_kit_gradio_source_preview.py+++ b/tests/unittest/test_kit_gradio_source_preview.py@@ -7,6 +7,7 @@ import jsonimport zipfilefrom pathlib import Path+import socketimport pytestfrom lxml import htmlfrom PIL import Image@@ -51,9 +52,19 @@ def ofd_bytes(text: str = "中文发票 & <script>", *, entity: str =return output.getvalue()+def _frame_element(frame_html: str) -> html.HtmlElement:+ """从可能带缩放外壳的预览标记中取出唯一 iframe。"""+ root = html.fromstring(frame_html)+ if root.tag == "iframe":+ return root+ frames = root.xpath(".//iframe")+ assert len(frames) == 1+ return frames[0]++def _frame_document(frame_html: str) -> str:"""取出沙箱 iframe 的 srcdoc 文档,属性转义在往返解析中被验证。"""- return html.fromstring(frame_html).get("srcdoc")+ return _frame_element(frame_html).get("srcdoc")def test_real_conversion_embeds_pages_and_escapes_text() -> None:@@ -96,43 +107,258 @@ def test_external_entity_is_not_read(tmp_path: Path) -> None:def test_html_preview_injects_csp_into_head_and_keeps_content() -> None:- """源 HTML 注入 CSP 后放入无权限沙箱,正文与属性转义保持不变。"""+ """源 HTML 允许脚本和联网资源,但 sandbox 仍保持 opaque origin 隔离。"""payload = (- "<!DOCTYPE html><html><head><title>报告</title></head>"+ '<!DOCTYPE html><html><head><meta name="referrer" content="always"><title>报告</title></head>''<body><p>中文 & 引号 "quoted"</p><img src="a.png"></body></html>').encode("utf-8")- frame = html.fromstring(build_html_preview(payload))+ markup = build_html_preview(payload)+ root = html.fromstring(markup)+ assert root.get("class") == "mineru-source-viewport"+ assert root.xpath("./div[@class='mineru-source-stage']/iframe[@class='mineru-source-frame']")+ frame = _frame_element(markup)assert frame.get("sandbox") == "allow-scripts"+ assert frame.get("referrerpolicy") == "no-referrer"assert frame.get("class") == "mineru-source-frame"document = html.fromstring(frame.get("srcdoc"))csp = document.xpath("//head/meta[@http-equiv='Content-Security-Policy']")assert len(csp) == 1- assert "default-src 'none'" in csp[0].get("content")- assert "img-src data: blob: https: http:" in csp[0].get("content")+ referrer = document.xpath("//head/meta[@name='referrer']")+ assert len(referrer) == 1 and referrer[0].get("content") == "no-referrer"+ policy = csp[0].get("content")+ assert "default-src 'none'" in policy+ assert "script-src 'unsafe-inline' 'unsafe-eval' https: http:" in policy+ assert "connect-src https: http:" in policy+ assert "img-src data: blob: https: http:" in policy+ assert "frame-src 'none'" in policy and "form-action 'none'" in policyassert '中文 & 引号 "quoted"' in document.text_content()+def test_html_preview_replaces_source_referrer_policy_before_remote_resources() -> None:+ """预览固定使用 no-referrer,避免沿用来源文件的强制 Referer 策略。"""+ payload = (+ '<html><head><meta name="referrer" content="always">'+ '<link rel="stylesheet" href="https://cdn.example.test/site.css"></head><body></body></html>'+ ).encode()+ document = html.fromstring(_frame_document(build_html_preview(payload)))+ head_children = list(document.xpath("//head")[0])+ referrer_index = next(i for i, node in enumerate(head_children) if node.tag == "meta" and node.get("name") == "referrer")+ stylesheet_index = next(i for i, node in enumerate(head_children) if node.tag == "link" and node.get("rel") == "stylesheet")+ assert head_children[referrer_index].get("content") == "no-referrer"+ assert referrer_index < stylesheet_index+ assert not document.xpath("//meta[@name='referrer' and @content='always']")+++def test_html_preview_normalizes_explicit_resource_referrer_policies() -> None:+ """标签覆盖策略和重复 meta 不得覆盖预览的无 Referer 策略。"""+ payload = (+ '<!DOCTYPE html><html><head><META NAME="Referrer" content="always">'+ '<meta name=" referrer " content="origin">'+ '<link rel="preload" href="/a.png" as="image" referrerpolicy="unsafe-url">'+ '<link rel="stylesheet" href="/a.css" referrerpolicy="origin">'+ '<script src="/a.js" referrerpolicy="same-origin"></script></head><body>'+ '<img src="/a.png" referrerpolicy="unsafe-url">'+ '<img src="/b.png" REFERRERPOLICY=""><meta name="referrer" content="always">'+ "</body></html>"+ ).encode()+ document = html.fromstring(_frame_document(build_html_preview(payload)))+ metas = document.xpath("//meta[@name='referrer']")+ assert len(metas) == 1 and metas[0].get("content") == "no-referrer"+ assert document.xpath("//head/*")[0] == metas[0]+ resources = document.xpath("//link | //script[@src] | //img")+ assert len(resources) == 5+ assert all(tag.get("referrerpolicy") == "no-referrer" for tag in resources)++[email protected]("suffix", ["html", "htm", "shtml"])+def test_html_preview_preserves_resources_without_server_requests(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, suffix: str+) -> None:+ """真实上传构建路径不联网,图片候选、查询参数与外部 CSS 均交由浏览器解析。"""++ def reject_connection(*args: object, **kwargs: object) -> None:+ """禁止服务端连接网络,使任何资源下载回归立即失败。"""+ pytest.fail("HTML preview must not fetch resources on the server")++ monkeypatch.setattr(socket.socket, "connect", reject_connection)+ payload = (+ '<html><head><link rel="canonical" href="https://blog.csdn.net/article/1">'+ '<link rel="stylesheet" href="https://csdnimg.cn/base.css"></head><body>'+ '<picture><source media="(min-width:800px)" srcset="https://i-blog.csdnimg.cn/picture.webp 2x">'+ '<img id="image" src="https://i-blog.csdnimg.cn/main.png" '+ 'srcset="https://i-blog.csdnimg.cn/a.png?resize=m_fixed,h_64,w_64 1x, /b.png 2x" '+ 'data-src="/lazy.png" width="1080" height="688"></picture>'+ '<img src="https://profile-avatar.csdnimg.cn/avatar.jpg!1">'+ '<img src="https://csdnimg.cn/identity/blog5.png"></body></html>'+ ).encode()+ source = tmp_path / f"page.{suffix}"+ source.write_bytes(payload)+ receipt = json.loads(asyncio.run(prepare_source_preview(str(source), json.dumps({"id": 1, "path": str(source)}))))+ document = html.fromstring(_frame_document(receipt["html"]))+ original = html.fromstring(payload)+ for selector in ("//picture/source", "//img", "//link[@rel='stylesheet']"):+ assert [dict(tag.attrib) for tag in document.xpath(selector)] == [dict(tag.attrib) for tag in original.xpath(selector)]+ assert "mineru-source-broken-image" not in _frame_document(receipt["html"])+++def test_html_preview_preserves_stylesheet_positions_and_cascade() -> None:+ """混合外部与内联样式保留原始位置、相对 URL 和级联次序。"""+ payload = (+ '<html><head><link rel="stylesheet" href="https://example.test/base.css">'+ "<style>p {color:red}</style></head><body>"+ "<style>p {color:green;background:url(../bg.png)}</style>"+ '<link rel="stylesheet" href="article.css" media="screen" title="article">'+ '<div><link rel="stylesheet" href="code.css"><style>p {color:blue}</style></div>'+ '<link rel="alternate stylesheet" href="alternate.css" title="alternate">'+ '<link rel="stylesheet" href="disabled.css" disabled>'+ '<link rel="preload" href="font.woff2">'+ '<noscript><link rel="stylesheet" href="no-script.css"></noscript>'+ "<p>正文</p></body></html>"+ ).encode()+ document = html.fromstring(_frame_document(build_html_preview(payload)))+ original = html.fromstring(payload)+ for selector in ("//head/link | //head/style", "//body/link | //body/style", "//body/div/*", "//noscript/*"):+ actual = document.xpath(selector)+ expected = original.xpath(selector)+ assert len(actual) == len(expected)+ for actual_tag, expected_tag in zip(actual, expected, strict=True):+ assert actual_tag.tag == expected_tag.tag+ assert actual_tag.text == expected_tag.text+ assert ("disabled" in actual_tag.attrib) == ("disabled" in expected_tag.attrib)+ assert {key: value for key, value in actual_tag.attrib.items() if key != "disabled"} == {+ key: value for key, value in expected_tag.attrib.items() if key != "disabled"+ }+++def test_html_preview_bridge_uses_stable_layout_width_not_document_scroll_width() -> None:+ """Safari 会把横向轮播离屏项计入 scrollWidth,尺寸桥必须改用桌面声明和顶层布局盒。"""+ payload = (+ '<html><head><meta name="applicable-device" content="pc"></head>'+ '<body><div style="width:1200px"><div style="width:12000px"></div></div></body></html>'+ ).encode()+ frame = _frame_element(build_html_preview(payload))+ assert frame.get("data-mineru-source-content-width") == "1200"+ document = html.fromstring(frame.get("srcdoc"))+ hint = document.xpath("//head/meta[@name='mineru-source-preview-width']")+ assert len(hint) == 1 and hint[0].get("content") == "1200"+ bridge = document.xpath("//script[@id='mineru-source-preview-bridge']")[0].text or ""+ assert 'meta[name="mineru-source-preview-width"]' in bridge+ assert 'meta[name="applicable-device"]' in bridge+ assert "return 1200" in bridge+ assert "parent.postMessage" in bridge+ assert "body.children" in bridge+ assert "body.scrollWidth" not in bridge+ assert "root.scrollWidth" not in bridge+ assert "ResizeObserver" not in bridge+++ ("viewport", "expected"),+ [+ ("width=1024, initial-scale=1", "1024"),+ ("initial-scale=1, width=1440", "1440"),+ ],+)+def test_html_preview_injects_numeric_viewport_width_hint(viewport: str, expected: str) -> None:+ """数值 viewport 声明优先于通用桌面宽度,保持源页面原始设计视口。"""+ payload = f'<html><head><meta name="viewport" content="{viewport}"></head><body></body></html>'.encode()+ frame = _frame_element(build_html_preview(payload))+ assert frame.get("data-mineru-source-content-width") == expected+ document = html.fromstring(frame.get("srcdoc"))+ hint = document.xpath("//head/meta[@name='mineru-source-preview-width']")+ assert len(hint) == 1 and hint[0].get("content") == expected++def test_html_preview_keeps_formula_scripts_for_typesetting() -> None:- """MathJax/KaTeX 脚本与 TeX 源文本完整保留,CSP 允许其执行以渲染公式。"""+ """MathJax/KaTeX 源码和 TeX 文本完整保留,CSP 允许其执行并加载远程依赖。"""payload = ("<!DOCTYPE html><html><head>"'<script>window.MathJax = {tex: {inlineMath: [["$", "$"]]}};</script>''<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>'"</head><body><p>质能方程 \\(E=mc^2\\)</p></body></html>").encode("utf-8")- frame = html.fromstring(build_html_preview(payload))+ frame = _frame_element(build_html_preview(payload))assert frame.get("sandbox") == "allow-scripts"document = html.fromstring(frame.get("srcdoc"))- scripts = document.xpath("//script")+ scripts = [script for script in document.xpath("//script") if script.get("id") != "mineru-source-preview-bridge"]assert len(scripts) == 2assert scripts[0].text is not None and "inlineMath" in scripts[0].textassert scripts[1].get("src").endswith("tex-chtml.js")+ assert document.xpath("//script[@id='mineru-source-preview-bridge']")assert "E=mc^2" in document.text_content()csp = document.xpath("//head/meta[@http-equiv='Content-Security-Policy']")[0].get("content")- assert "script-src 'unsafe-inline' 'unsafe-eval' https: http:" in csp+ script_policy = next(item.strip() for item in csp.split(";") if item.strip().startswith("script-src"))+ assert script_policy == "script-src 'unsafe-inline' 'unsafe-eval' https: http:"assert "connect-src https: http:" in csp+def test_html_preview_removes_auto_navigation_but_keeps_normal_scripts_and_events() -> None:+ """只清理自动导航入口,普通页面初始化、交互脚本、外链和文内锚点保持可用。"""+ payload = (+ "<!DOCTYPE html><html><head>"+ '<meta http-equiv="refresh" content="3;url=https://www.csdn.net">'+ "</head>"+ "<body onload=\"document.body.dataset.ready='1'\">"+ '<img src="" onerror="setTimeout(function(){window.location.href=\'https://www.csdn.net\'},3000)">'+ "<button onclick=\"this.classList.toggle('open')\">toggle</button>"+ "<script>window.location.href='https://example.test/redirect'</script>"+ '<a id="external" href="https://example.test/page" rel="nofollow">external</a>'+ '<a id="internal" href="#section">internal</a>'+ '<p id="section">正文仍需展示</p></body></html>'+ ).encode("utf-8")+ frame = _frame_element(build_html_preview(payload))+ assert frame.get("sandbox") == "allow-scripts"+ document = html.fromstring(frame.get("srcdoc"))+ assert not document.xpath("//meta[translate(@http-equiv, 'REFSH', 'refsh')='refresh']")+ assert document.xpath("//img")[0].get("onerror") is None+ assert document.xpath("//body")[0].get("onload") == "document.body.dataset.ready='1'"+ assert document.xpath("//button")[0].get("onclick") == "this.classList.toggle('open')"+ source_scripts = [script for script in document.xpath("//script") if script.get("id") != "mineru-source-preview-bridge"]+ assert any(script.text and "window.location.href" in script.text for script in source_scripts)+ external = document.get_element_by_id("external")+ assert external.get("target") == "_blank"+ assert set(external.get("rel").split()) == {"nofollow", "noopener", "noreferrer"}+ internal = document.get_element_by_id("internal")+ assert internal.get("href") == "#section" and internal.get("target") is None+ assert "正文仍需展示" in document.text_content()+++ "handler",+ [+ "window.location.href='https://example.test'",+ "location.assign('https://example.test')",+ "location.replace('https://example.test')",+ "top.location='https://example.test'",+ "parent.location.href='https://example.test'",+ "window.open('https://example.test')",+ ],+)+def test_html_preview_removes_navigation_event_handler_variants(handler: str) -> None:+ """常见自动导航写法在事件属性中被移除,避免来源页把预览 iframe 替换掉。"""+ payload = f'<html><body><img src="" onerror="{handler}"></body></html>'.encode()+ document = html.fromstring(_frame_document(build_html_preview(payload)))+ assert document.xpath("//img")[0].get("onerror") is None+++def test_html_preview_restores_source_base_from_canonical_or_existing_base() -> None:+ """canonical 用于恢复根路径资源基址,已有绝对 base 时不重复注入。"""+ canonical_payload = (+ '<html><head><link rel="canonical" href="https://example.test/articles/one">'+ '<script src="/assets/app.js"></script></head><body></body></html>'+ ).encode()+ canonical = html.fromstring(_frame_document(build_html_preview(canonical_payload)))+ assert [base.get("href") for base in canonical.xpath("//head/base")] == ["https://example.test/articles/one"]+ assert canonical.xpath("//head/base")[0].getnext().get("http-equiv") == "Content-Security-Policy"++ existing_payload = (+ '<html><head><base href="https://cdn.example.test/root/">'+ '<link rel="canonical" href="https://example.test/ignored"></head><body></body></html>'+ ).encode()+ existing = html.fromstring(_frame_document(build_html_preview(existing_payload)))+ assert [base.get("href") for base in existing.xpath("//head/base")] == ["https://cdn.example.test/root/"]++def test_html_preview_decodes_declared_charset() -> None:"""按头部 charset 声明解码 GBK 等存量文档,未知编码回退 UTF-8 替换。"""payload = '<html><head><meta charset="gbk"></head><body><p>中文内容</p></body></html>'.encode("gbk")