Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

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.py
index 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.py
index 068e796c..9dd7a520 100644
--- a/mineru/kit/gradio/source_preview.py
+++ b/mineru/kit/gradio/source_preview.py
@@ -9,7 +9,9 @@ import json
import re
from collections.abc import Callable
from pathlib import Path
+from urllib.parse import urlsplit
+from bs4 import BeautifulSoup
from loguru import logger
from .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.js
index 8340d10b..7efd5d52 100644
--- a/mineru/resources/gradio_source_preview.js
+++ b/mineru/resources/gradio_source_preview.js
@@ -23,6 +23,98 @@
"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
})[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.py
index 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_css
assert ".mineru-kit-results { min-height: 0; flex: 0 0 auto !important; }" in app._mineru_kit_css
assert ".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_css
assert "flex: 0 0 auto !important;" in app._mineru_kit_css
assert sum(1 for dependency in app.config["dependencies"] if dependency.get("queue") is True) >= 7
diff --git a/tests/unittest/test_kit_gradio_source_preview.cjs b/tests/unittest/test_kit_gradio_source_preview.cjs
index 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="&lt;p&gt;source&lt;/p&gt;"></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.py
index 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 json
import zipfile
from pathlib import Path
+import socket
import pytest
from lxml import html
from PIL import Image
@@ -51,9 +52,19 @@ def ofd_bytes(text: str = "中文发票 &amp; &lt;script&gt;", *, 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>中文 &amp; 引号 "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 policy
assert '中文 & 引号 "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) == 2
assert scripts[0].text is not None and "inlineMath" in scripts[0].text
assert 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")