Skip to content

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

feat(webui): visualize merged block connections

myhloliaf617e645c4a
diff --git a/mineru/kit/gradio/i18n.py b/mineru/kit/gradio/i18n.py
index 7f04867f..ce8f89d9 100644
--- a/mineru/kit/gradio/i18n.py
+++ b/mineru/kit/gradio/i18n.py
@@ -64,6 +64,8 @@ MESSAGES: dict[str, tuple[str, str]] = {
"pdf_zoom_in": ("Zoom in", "放大"),
"trace_regions": ("Layout annotations", "版式标注"),
"trace_source": ("Source page", "来源页"),
+ "trace_merged": ("Merged", "合并"),
+ "trace_merged_description": ("Merged from {count} source blocks", "由 {count} 个原始内容块合并"),
"pdf_fit_width": ("Fit width", "适应宽度"),
"pdf_invalid": ("This PDF is damaged or invalid.", "PDF 已损坏或格式无效。"),
"pdf_password": ("This PDF requires a password and cannot be previewed.", "此 PDF 需要密码,暂时无法预览。"),
diff --git a/mineru/resources/gradio_pdf_preview.js b/mineru/resources/gradio_pdf_preview.js
index 8774d865..6e08f9d8 100644
--- a/mineru/resources/gradio_pdf_preview.js
+++ b/mineru/resources/gradio_pdf_preview.js
@@ -70,7 +70,8 @@
try {
const messages = Object.fromEntries([
"preview", "pdf_loading", "pdf_previous", "pdf_next", "pdf_page", "pdf_zoom_out", "pdf_zoom_in",
- "trace_regions", "trace_source", "pdf_fit_width", "pdf_invalid", "pdf_password", "pdf_load_failed",
+ "trace_regions", "trace_source", "trace_merged", "trace_merged_description",
+ "pdf_fit_width", "pdf_invalid", "pdf_password", "pdf_load_failed",
].map((name) => [name, text(name)]));
const viewerUrl = fileUrl(viewer);
const params = new URLSearchParams({ file: fileUrl(file, viewerUrl), messages: JSON.stringify(messages) });
diff --git a/mineru/resources/pdf_preview/trace.mjs b/mineru/resources/pdf_preview/trace.mjs
index a3f9aef2..5715584f 100644
--- a/mineru/resources/pdf_preview/trace.mjs
+++ b/mineru/resources/pdf_preview/trace.mjs
@@ -7,7 +7,9 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
let layoutBySource = new Map();
let layoutByBox = new Map();
let traceableSources = new Set();
+ let mergedEntries = new Map();
let pageIndices = [];
+ let pageNumbers = new Map();
let selectedId = "";
let selectedSourceKey = "";
let hoveredBox = null;
@@ -16,6 +18,15 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
let showAll = true;
const abort = new AbortController();
const options = { signal: abort.signal };
+ let connectionFrame = 0;
+ // SVG 独立覆盖滚动视口,跨页线段可穿过页面边界,且不会随 PDF 缩放改变笔画粗细。
+ const svgNode = (name, attributes = {}) => {
+ const node = document.createElementNS("http://www.w3.org/2000/svg", name);
+ for (const [key, value] of Object.entries(attributes)) node.setAttribute(key, String(value));
+ return node;
+ };
+ const connections = svgNode("svg", { class: "mineru-merge-layer", "aria-hidden": "true" });
+ document.body.append(connections);
const toggle = document.createElement("button");
toggle.type = "button";
toggle.id = "trace-toggle";
@@ -38,6 +49,91 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
const color = region?.color || [0.35, 0.4, 0.45];
return `rgb(${color.map(value => Math.round(value * 255)).join(" ")})`;
};
+ // 同框父子按现有命中顺序优先取最具体的合并节点,单来源块暂时隐藏已选中的连接。
+ const activeMerge = () => {
+ const inspected = [hoveredBox, focusedBox].find(box => box?.isConnected);
+ if (inspected) return inspected.traceIds.map(id => mergedEntries.get(id)).find(Boolean);
+ return mergedEntries.get(selectedId);
+ };
+ // 读取真实页框而非缓存的命中元素,页面画布被回收后仍能使用已加载的页面尺寸。
+ const sourceRect = (source, host) => {
+ const pageNumber = pageNumbers.get(source.page_idx);
+ const page = pageNumber === undefined ? null : viewer.getPageView(pageNumber - 1);
+ const bbox = source.bbox;
+ if (!page?.pdfPage || !page.div.isConnected || bbox[2] <= bbox[0] || bbox[3] <= bbox[1]) return null;
+ const rect = page.div.getBoundingClientRect();
+ if (!rect.width || !rect.height) return null;
+ return {
+ left: rect.left - host.left + bbox[0] * rect.width,
+ top: rect.top - host.top + bbox[1] * rect.height,
+ right: rect.left - host.left + bbox[2] * rect.width,
+ bottom: rect.top - host.top + bbox[3] * rect.height
+ };
+ };
+ // 每段固定使用前块右下角与后块左上角,来源次序直接来自 renderer 的实际合并结果。
+ const drawConnections = () => {
+ connectionFrame = 0;
+ connections.replaceChildren();
+ const entry = activeMerge();
+ connections.dataset.traceId = entry?.id || "";
+ if (!entry) return;
+ const bounds = container.getBoundingClientRect();
+ const host = { left: bounds.left + container.clientLeft, top: bounds.top + container.clientTop };
+ const width = container.clientWidth;
+ const height = container.clientHeight;
+ Object.assign(connections.style, {
+ left: `${host.left}px`, top: `${host.top}px`, width: `${width}px`, height: `${height}px`
+ });
+ const rects = entry.sources.map(source => sourceRect(source, host));
+ for (let index = 1; index < rects.length; index++) {
+ const previous = rects[index - 1];
+ const current = rects[index];
+ if (!previous || !current) continue;
+ const x1 = previous.right;
+ const y1 = previous.bottom;
+ const x2 = current.left;
+ const y2 = current.top;
+ // 整段在视口外时省略 DOM,跨越视口的线段由 SVG 边界自然裁剪。
+ if (Math.max(x1, x2) < 0 || Math.min(x1, x2) > width ||
+ Math.max(y1, y2) < 0 || Math.min(y1, y2) > height) continue;
+ const group = svgNode("g");
+ group.dataset.fromSource = sourceKey(entry.sources[index - 1]);
+ group.dataset.toSource = sourceKey(entry.sources[index]);
+ group.style.setProperty("--trace-color", themeColor(layoutRegion(entry.sources[index - 1])));
+ group.append(
+ svgNode("line", { x1, y1, x2, y2 }),
+ svgNode("circle", { cx: x1, cy: y1, r: 2.5 }),
+ svgNode("circle", { cx: x2, cy: y2, r: 2.5 })
+ );
+ connections.append(group);
+ const x = (x1 + x2) / 2;
+ const y = (y1 + y2) / 2;
+ const label = svgNode("text", { x, y, "text-anchor": "middle", "dominant-baseline": "central" });
+ label.textContent = messages.trace_merged;
+ group.append(label);
+ const labelWidth = label.getComputedTextLength() + 8;
+ // 短线保留端点和无障碍说明,标签只在能完整容纳的中点显示。
+ if (Math.hypot(x2 - x1, y2 - y1) < labelWidth + 12 ||
+ x - labelWidth / 2 < 0 || x + labelWidth / 2 > width || y < 9 || y > height - 9) {
+ label.remove();
+ continue;
+ }
+ group.insertBefore(svgNode("rect", {
+ x: x - labelWidth / 2, y: y - 9, width: labelWidth, height: 18, rx: 3
+ }), label);
+ }
+ };
+ // 一帧内的悬停、滚动、缩放和 PDF.js 重绘共用一次几何测量。
+ const scheduleConnections = () => {
+ if (!connectionFrame) connectionFrame = requestAnimationFrame(drawConnections);
+ };
+ // 失效立即清空旧文档的连接,并撤销尚未执行的绘制。
+ const clearConnections = () => {
+ cancelAnimationFrame(connectionFrame);
+ connectionFrame = 0;
+ connections.replaceChildren();
+ connections.dataset.traceId = "";
+ };
// 两种浮层统一使用显示方向下的归一化坐标。
const placeRegion = (node, bbox) => {
node.style.left = `${bbox[0] * 100}%`;
@@ -52,7 +148,18 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
layoutBySource = new Map();
layoutByBox = new Map();
traceableSources = new Set();
+ mergedEntries = new Map();
+ pageNumbers = new Map(pageIndices.map((pageIdx, index) => [pageIdx, index + 1]));
for (const entry of entries) {
+ const seen = new Set();
+ // 按首次出现的位置保留物理区域,父子共框及重复来源只参与一次连接。
+ const sources = entry.sources.filter(source => {
+ const key = JSON.stringify([source.page_idx, source.bbox]);
+ if (seen.has(key)) return false;
+ seen.add(key);
+ return true;
+ });
+ if (sources.length > 1) mergedEntries.set(entry.id, { ...entry, sources });
for (const source of entry.sources) {
if (!sourcesByPage.has(source.page_idx)) sourcesByPage.set(source.page_idx, []);
sourcesByPage.get(source.page_idx).push({ entry, bbox: source.bbox, source });
@@ -102,6 +209,7 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
layout.remove();
}
layers.clear();
+ clearConnections();
};
// 重绘时从文档状态恢复选中样式,避免依赖已销毁的 DOM 引用。
const updateSelection = () => {
@@ -133,6 +241,7 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
}
if (labelsChanged) positionLabels(layer);
}
+ scheduleConnections();
};
// 可跳转块和辅助块共用悬停、键盘检查入口,已销毁元素的状态自动失效。
const inspectOnFocus = (node) => {
@@ -263,6 +372,8 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
const description = [messages.trace_source, pageIdx + 1, labelsBySource.get(sourceKey(source))]
.filter(Boolean).join(" · ");
box.setAttribute("aria-label", description);
+ const merged = ids.map(id => mergedEntries.get(id)).find(Boolean);
+ if (merged) box.setAttribute("aria-description", messages.trace_merged_description.replace("{count}", merged.sources.length));
placeRegion(box, bbox);
box.addEventListener("click", () => send({ type: "select", id: entry.id, pageIdx, sourceKey: sourceKey(source) }));
inspectOnFocus(box);
@@ -322,10 +433,12 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
region.color.every((value) => Number.isFinite(value) && value >= 0 && value <= 1)
) : [];
indexRegions(layoutRegions);
+ clearLayers();
hoveredBox = null;
focusedBox = null;
toggle.hidden = !layoutRegions.length && !entries.length;
for (const page of viewer.getCachedPageViews()) mount(page.id);
+ scheduleConnections();
} else if (data.type === "select" && entries.some((entry) => entry.id === data.id)) {
pending = null;
selectedId = data.id;
@@ -361,12 +474,20 @@ export function installTrace({ viewer, eventBus, container, documentId, messages
if (!event.error) mount(event.pageNumber);
};
eventBus.on("pagerendered", onRendered);
+ const connectionEvents = ["updateviewarea", "scalechanging", "pagesloaded"];
+ for (const name of connectionEvents) eventBus.on(name, scheduleConnections);
+ container.addEventListener("scroll", scheduleConnections, { ...options, passive: true });
+ const connectionObserver = new ResizeObserver(scheduleConnections);
+ connectionObserver.observe(container);
send({ type: "ready" });
return () => {
// 查看器卸载时释放本次文档拥有的监听器和浮层。
abort.abort();
eventBus.off("pagerendered", onRendered);
+ for (const name of connectionEvents) eventBus.off(name, scheduleConnections);
+ connectionObserver.disconnect();
clearLayers();
+ connections.remove();
toggle.remove();
};
}
diff --git a/mineru/resources/pdf_preview/viewer.css b/mineru/resources/pdf_preview/viewer.css
index bef2e04e..93dff7f7 100644
--- a/mineru/resources/pdf_preview/viewer.css
+++ b/mineru/resources/pdf_preview/viewer.css
@@ -77,6 +77,13 @@ button:focus-visible, input:focus-visible, #viewer-container:focus-visible { out
padding: 1px 3px; border: 1px solid var(--trace-strong); border-radius: 2px;
background: #fff; font-size: 11px; line-height: 13px; text-shadow: none;
}
+/* 合并关系使用固定 CSS 像素覆盖可见视口,装饰层不接收点击或键盘焦点。 */
+.mineru-merge-layer { position: fixed; z-index: 6; overflow: hidden; pointer-events: none; }
+.mineru-merge-layer > g { --trace-strong: color-mix(in srgb, var(--trace-color, #596673) 65%, black); }
+.mineru-merge-layer line { stroke: var(--trace-strong); stroke-width: 1.5px; stroke-dasharray: 6 4; }
+.mineru-merge-layer circle { fill: var(--trace-strong); }
+.mineru-merge-layer rect { fill: #fff; stroke: var(--trace-strong); stroke-width: 1px; }
+.mineru-merge-layer text { fill: var(--trace-strong); font: 11px system-ui, sans-serif; }
#trace-toggle { font-size: 11px; padding: 0 5px; }
@media (max-width: 480px) {
body:has(#trace-toggle:not([hidden])) { --toolbar-height: 80px; }
diff --git a/tests/browser/gradio_merge_checks.js b/tests/browser/gradio_merge_checks.js
new file mode 100644
index 00000000..d42c1187
--- /dev/null
+++ b/tests/browser/gradio_merge_checks.js
@@ -0,0 +1,125 @@
+// 使用 playwright-cli run-code --filename 执行,页面须已通过真实 WebUI 完成 Basic 解析。
+async (page) => {
+ const pdfElement = page.locator("iframe.mineru-pdf-frame");
+ const pdf = await (await pdfElement.elementHandle()).contentFrame();
+ const html = await (await page.locator("iframe.mineru-rendered-html-frame").elementHandle()).contentFrame();
+ const viewport = page.viewportSize();
+ const data = await html.evaluate(() => {
+ const script = [...document.scripts].find(node => node.textContent.includes('"layoutRegions":'));
+ const config = JSON.parse(script.textContent.slice(script.textContent.lastIndexOf(")(") + 2, -2));
+ const entries = [...document.querySelectorAll("[data-docvortex-trace-id]")].map(node => ({
+ id: node.dataset.docvortexTraceId, type: node.dataset.blockType,
+ sources: JSON.parse(node.dataset.docvortexSources)
+ }));
+ return { documentId: config.documentId, pageIndices: config.pageIndices, entries };
+ });
+ const merged = data.entries.filter(entry => entry.sources.length > 1);
+ if (!merged.length) throw new Error("The real parse result has no merged sources to check");
+ const checked = [];
+ // 从真实结果块激活选择,覆盖 HTML 到 PDF 的消息链。
+ const selectEntry = async (entry) => {
+ await html.locator(`[data-docvortex-trace-id="${entry.id}"]`).press("Enter");
+ await pdf.waitForFunction(id => document.querySelector(".mineru-merge-layer")?.dataset.traceId === id, entry.id);
+ };
+ // 通过页码控件取得端点页面的实际尺寸,再把线段中点滚入视口。
+ const showEdge = async (entry, index) => {
+ for (const source of entry.sources.slice(index, index + 2)) {
+ const number = data.pageIndices.indexOf(source.page_idx) + 1;
+ await pdf.locator("#page").fill(String(number));
+ await pdf.locator("#page").press("Enter");
+ await pdf.locator(`.page[data-page-number="${number}"] .mineru-trace-layer`).waitFor({ state: "attached" });
+ }
+ await pdf.evaluate(({ entry, index, pageIndices }) => {
+ const host = document.getElementById("viewer-container");
+ const sources = entry.sources.slice(index, index + 2);
+ const bounds = sources.map(source => document.querySelector(
+ `.page[data-page-number="${pageIndices.indexOf(source.page_idx) + 1}"]`
+ ).getBoundingClientRect());
+ const middle = (bounds[0].top + sources[0].bbox[3] * bounds[0].height +
+ bounds[1].top + sources[1].bbox[1] * bounds[1].height) / 2;
+ host.scrollTop += middle - host.getBoundingClientRect().top - host.clientHeight / 2;
+ }, { entry, index, pageIndices: data.pageIndices });
+ await pdf.locator("#toolbar").hover();
+ };
+ // 直接比较 SVG 端点和实际命中框的角点,允许最多 2 CSS px 的亚像素排版误差。
+ const checkEdges = async (entry) => {
+ await pdf.waitForFunction(({ entry, pageIndices }) => {
+ const svg = document.querySelector(".mineru-merge-layer");
+ if (svg?.dataset.traceId !== entry.id || !svg.children.length) return false;
+ const origin = svg.getBoundingClientRect();
+ for (const group of svg.children) {
+ const from = JSON.parse(group.dataset.fromSource);
+ const to = JSON.parse(group.dataset.toSource);
+ const keys = entry.sources.map(source => JSON.stringify([source.page_idx, source.block_index, source.child_path]));
+ const index = keys.indexOf(JSON.stringify(from));
+ if (index < 0 || keys[index + 1] !== JSON.stringify(to)) throw new Error("Merge source order changed");
+ const rects = entry.sources.slice(index, index + 2).map(source => {
+ const pageNode = document.querySelector(`.page[data-page-number="${pageIndices.indexOf(source.page_idx) + 1}"]`);
+ const node = [...pageNode.querySelectorAll("button[data-trace-id]")].find(node =>
+ node.traceIds.includes(entry.id) && node.source.bbox.every((value, i) => value === source.bbox[i]));
+ if (!node) throw new Error("Missing rendered source hit box");
+ return node.getBoundingClientRect();
+ });
+ const line = group.querySelector("line");
+ const actual = [Number(line.getAttribute("x1")) + origin.left, Number(line.getAttribute("y1")) + origin.top,
+ Number(line.getAttribute("x2")) + origin.left, Number(line.getAttribute("y2")) + origin.top];
+ const expected = [rects[0].right, rects[0].bottom, rects[1].left, rects[1].top];
+ if (actual.some((value, i) => Math.abs(value - expected[i]) > 2)) return false;
+ if (getComputedStyle(line).strokeWidth !== "1.5px") throw new Error("Merge stroke scaled with PDF");
+ const label = group.querySelector("text");
+ if (label && getComputedStyle(label).fontSize !== "11px") throw new Error("Merge label scaled with PDF");
+ }
+ if (getComputedStyle(svg).pointerEvents !== "none") throw new Error("Merge layer intercepts clicks");
+ return true;
+ }, { entry, pageIndices: data.pageIndices });
+ };
+ for (const entry of merged) {
+ await selectEntry(entry);
+ for (let index = 0; index < entry.sources.length - 1; index++) {
+ await showEdge(entry, index);
+ await checkEdges(entry);
+ }
+ checked.push({ id: entry.id, type: entry.type, sources: entry.sources });
+ }
+ // 优先记录跨栏后跨页的最长链,续表样本优先记录有具体几何的正文子块。
+ const representative = [...merged].sort((a, b) => b.sources.length - a.sources.length ||
+ b.sources[0].child_path.length - a.sources[0].child_path.length)[0];
+ await selectEntry(representative);
+ await showEdge(representative, 0);
+ await checkEdges(representative);
+ const prefix = `output/playwright/merge-connections/${data.documentId}`;
+ await pdfElement.screenshot({ path: `${prefix}-desktop.png` });
+ // 鼠标检查单块临时隐藏连接,离开后恢复选择;键盘检查复用同一规则。
+ const single = data.entries.find(entry => entry.sources.length === 1 &&
+ entry.sources[0].page_idx === representative.sources[0].page_idx);
+ if (single) {
+ const box = pdf.locator(`button[data-trace-id="${single.id}"]`).first();
+ if (await box.count()) {
+ await box.hover();
+ await pdf.waitForFunction(() => !document.querySelector(".mineru-merge-layer").children.length);
+ await pdf.locator("#toolbar").hover();
+ await pdf.waitForFunction(id => document.querySelector(".mineru-merge-layer").dataset.traceId === id, representative.id);
+ await box.focus();
+ await pdf.waitForFunction(() => !document.querySelector(".mineru-merge-layer").children.length);
+ await pdf.locator("#trace-toggle").focus();
+ }
+ }
+ await showEdge(representative, 0);
+ await pdf.locator("#trace-toggle").click();
+ await checkEdges(representative);
+ await pdf.locator("#trace-toggle").click();
+ await pdf.locator("#zoom-in").click();
+ await showEdge(representative, 0);
+ await checkEdges(representative);
+ await pdfElement.screenshot({ path: `${prefix}-zoom.png` });
+ await pdf.locator("#fit").click();
+ await page.setViewportSize({ width: 375, height: 900 });
+ await pdfElement.scrollIntoViewIfNeeded();
+ await showEdge(representative, 0);
+ await checkEdges(representative);
+ await pdfElement.screenshot({ path: `${prefix}-narrow.png` });
+ await page.setViewportSize(viewport);
+ await showEdge(representative, 0);
+ await checkEdges(representative);
+ return { documentId: data.documentId, checked, screenshots: prefix, geometryTolerance: 2, zoom: true, narrow: true };
+}
diff --git a/tests/unittest/test_kit_gradio_pdf_preview.cjs b/tests/unittest/test_kit_gradio_pdf_preview.cjs
index 8683fff7..088af66f 100644
--- a/tests/unittest/test_kit_gradio_pdf_preview.cjs
+++ b/tests/unittest/test_kit_gradio_pdf_preview.cjs
@@ -30,6 +30,8 @@ assert.equal(pdfUrl.search, "");
assert.equal(pdfUrl.hash, "");
assert.ok(initial.value.includes('sandbox="allow-scripts allow-same-origin"'));
assert.equal(JSON.parse(parameters.get("messages")).pdf_page, "中文 pdf_page");
+assert.equal(JSON.parse(parameters.get("messages")).trace_merged, "中文 trace_merged");
+assert.equal(JSON.parse(parameters.get("messages")).trace_merged_description, "中文 trace_merged_description");
// Gradio 的事件 FileData 可能缺少挂载前缀,静态入口的基址必须用于结果 PDF。
const relative = { ...first, url: first.url.replace("/prefix", "") };
const relativeParams = new URLSearchParams(iframe(invoke("source", relative, first, viewer)).hash.slice(1));
diff --git a/tests/unittest/test_kit_gradio_trace.cjs b/tests/unittest/test_kit_gradio_trace.cjs
index 30d8353a..007a647f 100644
--- a/tests/unittest/test_kit_gradio_trace.cjs
+++ b/tests/unittest/test_kit_gradio_trace.cjs
@@ -148,6 +148,59 @@ checkHtmlNavigation("52px", -100, 52, "https://mineru.test:8443", "https://miner
console.log("HTML source-page controls respect the outline toolbar and viewport");
// 执行 PDF 溯源入口,用放大后的真实边界语义检查横纵两个方向的定位。
+// 只实现浮层使用的 DOM 接口,所有布局输入由测试显式给定。
+class TraceNode {
+ // 为每个节点保留事件、属性、子节点及可观测的 CSS 状态。
+ constructor(tag = "div") {
+ this.tagName = tag;
+ this.children = [];
+ this.dataset = {};
+ this.style = makeStyle();
+ this.attributes = {};
+ this.handlers = {};
+ this.isConnected = true;
+ this.clientWidth = 500;
+ this.clientHeight = 600;
+ this.offsetWidth = 30;
+ this.offsetHeight = 14;
+ this.classes = new Set();
+ this.classList = {
+ // 模拟显式开关,供选中和悬停断言检查。
+ toggle: (name, enabled) => enabled ? this.classes.add(name) : this.classes.delete(name)
+ };
+ }
+ // 属性统一保存为字符串,与浏览器元素行为一致。
+ setAttribute(name, value) { this.attributes[name] = String(value); }
+ // 记录实际事件处理器,测试通过相同入口驱动交互。
+ addEventListener(name, handler) { this.handlers[name] = handler; }
+ // 挂载节点时维护父子关系,支持重绘后的失效检测。
+ append(...nodes) {
+ for (const node of nodes) { node.parentElement = this; this.children.push(node); }
+ }
+ // 清空子节点时同步断开旧节点。
+ replaceChildren() {
+ for (const child of [...this.children]) child.remove();
+ }
+ // 删除时递归失效所有后代,模拟 PDF.js 页面回收。
+ remove() {
+ this.isConnected = false;
+ this.replaceChildren();
+ if (this.parentElement) this.parentElement.children = this.parentElement.children.filter(node => node !== this);
+ }
+ // 标签底板插到文字前,便于验证真实绘制顺序。
+ insertBefore(node, before) {
+ node.parentElement = this;
+ this.children.splice(this.children.indexOf(before), 0, node);
+ }
+ // 字宽仅用于确定短线阈值,浏览器验收另行检查实际字体几何。
+ getComputedTextLength() { return this.textContent.length * 6; }
+ // 页面查询仅支持生产溯源入口实际使用的画布和命中层。
+ querySelector(selector) {
+ return selector === "canvas" ? {} : this.children.find(node => node.className === selector.slice(1));
+ }
+ // 测试按页设置稳定几何,滚动和缩放直接更新该输入。
+ getBoundingClientRect() { return this.rect; }
+}
const pdfHandlers = {};
const pdfParent = { postMessage() {} };
const scrolls = [];
@@ -156,14 +209,18 @@ const pdfBox = { traceIds: [entry.id], getBoundingClientRect: () => boxRect };
const container = {
scrollTop: 300, scrollLeft: 200, clientWidth: 500, clientHeight: 600,
getBoundingClientRect: () => ({ left: 100, top: 40 }),
- scrollTo: options => scrolls.push(options)
+ scrollTo: options => scrolls.push(options), addEventListener() {}
};
const pdfContext = {
parent: pdfParent, location, AbortController, container,
document: {
createElement: () => ({ setAttribute() {}, addEventListener() {} }),
+ createElementNS: (_namespace, name) => new TraceNode(name),
+ body: new TraceNode(),
getElementById: () => ({ append() {} })
},
+ requestAnimationFrame: () => 1, cancelAnimationFrame() {},
+ ResizeObserver: class { observe() {} },
window: { addEventListener: (name, callback) => { pdfHandlers[name] = callback; } },
viewer: {
getPageView: () => ({ div: { querySelector: () => ({ children: [pdfBox] }) } }),
@@ -190,3 +247,148 @@ boxRect = { left: 950, top: 800, width: 700, height: 80 };
emitPdf({ type: "select", id: entry.id, pageIdx: 2, scroll: true });
assert.equal(scrolls.at(-1).left, 1034);
console.log("PDF source navigation handles horizontal zoom overflow");
+
+// 用同一入口挂载完整页面,覆盖跨栏后跨页的三段链及真实焦点优先级。
+const mergeHandlers = {};
+const mergeEvents = {};
+const animationFrames = new Map();
+let nextFrame = 0;
+let resizeCallback;
+const mergeBody = new TraceNode("body");
+const mergeToolbar = new TraceNode();
+const mergeContainer = new TraceNode();
+Object.assign(mergeContainer, { clientLeft: 0, clientTop: 0, rect: { left: 100, top: 40 } });
+const pageViews = [0, 1].map(index => {
+ const div = new TraceNode();
+ div.rect = { left: 100, top: 40 + index * 602, width: 500, height: 600 };
+ return { id: index + 1, div, pdfPage: {} };
+});
+const mergeContext = {
+ parent: pdfParent, location, AbortController,
+ document: {
+ createElement: name => new TraceNode(name),
+ createElementNS: (_namespace, name) => new TraceNode(name),
+ getElementById: () => mergeToolbar, body: mergeBody
+ },
+ window: { addEventListener: (name, handler) => { mergeHandlers[name] = handler; } },
+ requestAnimationFrame: callback => { animationFrames.set(++nextFrame, callback); return nextFrame; },
+ cancelAnimationFrame: id => animationFrames.delete(id),
+ ResizeObserver: class {
+ // 保存生产观察器回调,用于验证尺寸更新和释放。
+ constructor(callback) { resizeCallback = callback; }
+ // 测试直接控制观察对象的几何。
+ observe() {}
+ // 释放后清除可调用入口。
+ disconnect() { resizeCallback = null; }
+ },
+ container: mergeContainer,
+ viewer: {
+ getPageView: index => pageViews[index], getCachedPageViews: () => pageViews,
+ scrollPageIntoView() {}
+ },
+ eventBus: {
+ on: (name, callback) => { mergeEvents[name] = callback; },
+ off: name => { delete mergeEvents[name]; }
+ },
+ messages: { trace_merged: "合并", trace_merged_description: "由 {count} 个原始内容块合并" }
+};
+vm.runInNewContext(`${pdfScript.replace("export function", "function")}
+globalThis.disposeTrace = installTrace({ viewer, eventBus, container, documentId: "one", messages });`, mergeContext);
+// 消息经过生产身份校验,避免测试绕过初始化和选择流程。
+const emitMerge = data => mergeHandlers.message({ source: pdfParent, origin: location.origin, data: {
+ channel: "mineru-trace", documentId: "one", ...data
+} });
+// 一次刷新执行已排队的回调,并验证更新确实按帧合并。
+const flushConnections = () => {
+ assert.ok(animationFrames.size <= 1);
+ const callbacks = [...animationFrames.values()];
+ animationFrames.clear();
+ for (const callback of callbacks) callback();
+};
+const chain = {
+ id: "chain", depth: 1, sources: [
+ { page_idx: 2, block_index: 4, child_path: [0], bbox: [0.1, 0.4, 0.48, 0.8] },
+ { page_idx: 2, block_index: 7, child_path: [0], bbox: [0.52, 0.1, 0.9, 0.8] },
+ { page_idx: 5, block_index: 1, child_path: [0], bbox: [0.1, 0.1, 0.48, 0.3] }
+ ]
+};
+const single = { id: "single", depth: 0, sources: [{
+ page_idx: 2, block_index: 9, child_path: [], bbox: [0.1, 0.85, 0.4, 0.95]
+}] };
+const parentChain = { id: "parent", depth: 0, sources: chain.sources.map(source => ({ ...source, child_path: [] })) };
+const layoutRegionsForChain = chain.sources.map(source => ({ ...source, type: "text", index: 1, color: [0.6, 0.05, 0.3] }));
+const mergeInit = { type: "init", entries: [parentChain, chain, single], pageIndices: [2, 5], layoutRegions: layoutRegionsForChain };
+emitMerge(mergeInit);
+flushConnections();
+const overlay = mergeBody.children[0];
+assert.equal(overlay.children.length, 0);
+// 两个父子来源占据同框时只挂载一个命中区域,优先采用最深的合并节点。
+const firstHit = pageViews[0].div.querySelector(".mineru-trace-layer");
+const chainBox = firstHit.children.find(node => node.dataset.traceId === "chain");
+const singleBox = firstHit.children.find(node => node.dataset.traceId === "single");
+assert.equal(chainBox.attributes["aria-description"], "由 3 个原始内容块合并");
+chainBox.handlers.pointerenter();
+flushConnections();
+assert.equal(overlay.dataset.traceId, "chain");
+assert.equal(overlay.children.length, 2);
+assert.deepEqual(overlay.children[0].children[0].attributes, { x1: "240", y1: "480", x2: "260", y2: "60" });
+assert.deepEqual(overlay.children[1].children[0].attributes, { x1: "450", y1: "480", x2: "50", y2: "662" });
+assert.equal(overlay.children[0].style["--trace-color"], "rgb(153 13 77)");
+assert.equal(overlay.children[0].children.at(-1).textContent, "合并");
+emitMerge({ type: "select", id: "chain", pageIdx: 2, scroll: false });
+singleBox.handlers.pointerenter();
+flushConnections();
+assert.equal(overlay.children.length, 0);
+singleBox.handlers.pointerleave();
+flushConnections();
+assert.equal(overlay.children.length, 2);
+singleBox.handlers.focus();
+flushConnections();
+assert.equal(overlay.children.length, 0);
+singleBox.handlers.blur();
+mergeToolbar.children[0].handlers.click();
+flushConnections();
+assert.equal(overlay.children.length, 2);
+// 端点由实时页框计算,滚动、缩放和尺寸变化共用同一个动画帧。
+pageViews[0].div.rect = { left: 80, top: -60, width: 600, height: 720 };
+mergeContainer.handlers.scroll();
+mergeEvents.scalechanging();
+resizeCallback();
+flushConnections();
+assert.deepEqual(overlay.children[0].children[0].attributes, { x1: "268", y1: "476", x2: "292", y2: "-28" });
+pageViews[1].pdfPage = null;
+mergeEvents.updateviewarea();
+flushConnections();
+assert.equal(overlay.children.length, 1);
+pageViews[1].pdfPage = {};
+mergeEvents.pagerendered({ pageNumber: 2 });
+flushConnections();
+assert.equal(overlay.children.length, 2);
+// 重复来源不会多画线,几何无效的中间片段阻断两侧线段。
+const duplicateChain = { ...chain, sources: [chain.sources[0], chain.sources[0], ...chain.sources.slice(1)] };
+emitMerge({ ...mergeInit, entries: [duplicateChain] });
+flushConnections();
+assert.equal(overlay.children.length, 2);
+const invalidChain = { ...chain, sources: [chain.sources[0], { ...chain.sources[1], bbox: [0.5, 0.1, 0.5, 0.8] }, chain.sources[2]] };
+emitMerge({ ...mergeInit, entries: [invalidChain] });
+flushConnections();
+assert.equal(overlay.children.length, 0);
+const shortChain = { ...chain, sources: [chain.sources[0], { ...chain.sources[1], bbox: [0.49, 0.81, 0.9, 0.9] }] };
+emitMerge({ ...mergeInit, entries: [shortChain] });
+flushConnections();
+assert.equal(overlay.children.length, 1);
+assert.deepEqual(overlay.children[0].children.map(node => node.tagName), ["line", "circle", "circle"]);
+// 单来源与失败的合并目标都不产生连线,清理时撤销旧帧并解绑观察器。
+emitMerge({ ...mergeInit, entries: [single] });
+emitMerge({ type: "select", id: "single", pageIdx: 2 });
+flushConnections();
+assert.equal(overlay.children.length, 0);
+mergeContainer.handlers.scroll();
+emitMerge({ type: "clear" });
+assert.equal(animationFrames.size, 0);
+assert.equal(overlay.dataset.traceId, "");
+mergeContext.disposeTrace();
+assert.equal(overlay.isConnected, false);
+assert.equal(resizeCallback, null);
+assert.deepEqual(Object.keys(mergeEvents), []);
+console.log("Merge chains preserve source order, corner geometry, interaction priority and lifecycle");