CavinHuang · CavinHuang · Aug 22, 2026 · Aug 22, 2026 · Aug 22, 2026 · Aug 22, 2026
diff --git a/packages/sdk/src/tools/html-to-markdown.test.ts b/packages/sdk/src/tools/html-to-markdown.test.ts
@@ -104,3 +104,34 @@ describe("normalizeTablesHtml span budgets (#303)", () => {
     expect(out).not.toContain("colspan");
   });
 });
+
+describe("document-level span budget (#458)", () => {
+  // Each table expands to a legal 10,000-cell grid (single-table budget intact).
+  const smallTable = (label: string) =>
+    `<table><tr><td rowspan="100" colspan="100">${label}</td></tr></table>`;
+
+  test("many legal small tables cannot stack expansions past the document budget", () => {
+    // 25 tables fill the document budget exactly; the 26th must be skipped.
+    const tables = Array.from({ length: 26 }, (_, i) => smallTable(`t${i}`)).join("");
+    const out = normalizeTablesHtml(tables);
+    expect(out).toContain("t0");
+    expect(out).toContain("t25"); // skipped table's content is kept, not dropped
+    expect(out).toContain("[table span budget reached: 1 table(s) left unnormalized]");
+    expect(out.split('rowspan="100"').length - 1).toBe(1); // only the skipped table keeps its spans
+  }, 120_000);
+
+  test("tables exactly filling the document budget still all expand", () => {
+    const tables = Array.from({ length: 25 }, (_, i) => smallTable(`t${i}`)).join("");
+    const out = normalizeTablesHtml(tables);
+    expect(out).not.toContain("rowspan");
+    expect(out).not.toContain("colspan");
+    expect(out).not.toContain("table span budget");
+  }, 120_000);
+
+  test("a per-table over-budget table is also reported by the truncation marker", () => {
+    const cells = Array.from({ length: 30 }, (_, i) => `<td rowspan="100" colspan="100">c${i}</td>`).join("");
+    const out = normalizeTablesHtml(`<p>intro</p><table><tr>${cells}</tr></table>`);
+    expect(out).toContain('rowspan="100"');
+    expect(out).toContain("[table span budget reached: 1 table(s) left unnormalized]");
+  });
+});
diff --git a/packages/sdk/src/tools/html-to-markdown.ts b/packages/sdk/src/tools/html-to-markdown.ts
@@ -44,8 +44,14 @@ function normalizeCell(cell: HTMLElement): void {
 
 /** Per-cell upper bound for rowspan/colspan (HTML spec clamps similarly). */
 const MAX_SPAN = 100;
-/** Expanded-grid budget; tables beyond it skip normalization untouched. */
+/**
+ * Expanded-grid budgets; a table past either skips normalization untouched.
+ * The per-table cap bounds a single expansion's materialization; the
+ * document-level total keeps many legal small tables from stacking expansions
+ * into an unbounded sum (#458).
+ */
 const MAX_TABLE_GRID_CELLS = 250_000;
+const MAX_DOCUMENT_TABLE_CELLS = 250_000;
 
 function clampSpan(attribute: string | null): number {
   return Math.min(MAX_SPAN, Math.max(1, Number.parseInt(attribute ?? "1", 10) || 1));
@@ -56,7 +62,7 @@ function clampSpan(attribute: string | null): number {
  * expansion would blow past the cell budget (hostile span attributes must not
  * materialize millions of grid slots).
  */
-function buildTableGrid(rows: HTMLElement[]): { grid: Array<Array<HTMLElement | undefined>>; primary: Set<string> } | null {
+function buildTableGrid(rows: HTMLElement[]): { grid: Array<Array<HTMLElement | undefined>>; primary: Set<string>; cells: number } | null {
   const grid: Array<Array<HTMLElement | undefined>> = [];
   const primary = new Set<string>();
   let placedCells = 0;
@@ -79,7 +85,7 @@ function buildTableGrid(rows: HTMLElement[]): { grid: Array<Array<HTMLElement |
       colIndex += colSpan;
     }
   }
-  return { grid, primary };
+  return { grid, primary, cells: placedCells };
 }
 
 /**
@@ -91,13 +97,27 @@ export function normalizeTablesHtml(html: string, url = "https://lume.invalid/")
   const dom = new JSDOM(`<body>${html}</body>`, { url });
   const doc = dom.window.document;
 
+  // Document-level budget (#458): per-table caps alone let any number of legal
+  // tables stack expansions without bound. Once the shared total is exhausted,
+  // remaining tables are left untouched and the truncation is marked in the
+  // output instead of silently dropped.
+  let documentCells = 0;
+  let unnormalizedTables = 0;
   for (const table of Array.from(doc.querySelectorAll("table"))) {
     const rows = Array.from(table.querySelectorAll("tr"));
     if (rows.length === 0) continue;
+    if (documentCells >= MAX_DOCUMENT_TABLE_CELLS) {
+      unnormalizedTables++;
+      continue;
+    }
     for (const cell of Array.from(table.querySelectorAll("td,th"))) normalizeCell(cell as HTMLElement);
 
     const expanded = buildTableGrid(rows as HTMLElement[]);
-    if (!expanded) continue;
+    if (!expanded || documentCells + expanded.cells > MAX_DOCUMENT_TABLE_CELLS) {
+      unnormalizedTables++;
+      continue;
+    }
+    documentCells += expanded.cells;
     const { grid, primary } = expanded;
 
     let width = 0;
@@ -142,6 +162,12 @@ export function normalizeTablesHtml(html: string, url = "https://lume.invalid/")
     }
   }
 
+  if (unnormalizedTables > 0) {
+    const marker = doc.createElement("p");
+    marker.textContent = `[table span budget reached: ${unnormalizedTables} table(s) left unnormalized]`;
+    doc.body.appendChild(marker);
+  }
+
   return doc.body.innerHTML;
 }