blitz-pdf 0.1.2 → 0.1.3

package/README.md

@@ -431,6 +431,32 @@ relaxed to make progress. A text line that cannot fit the printable height
 fails explicitly. Keep-with-next protects a heading even when the following
 paragraph spans multiple pages.
 
+Trailing `<br>` elements and preserved blank lines keep their layout height;
+the extra cursor line emitted by the text engine after a final break is not
+paginated. Overflow clips constrain line, glyph, and table-row fragmentation.
+Fully clipped glyph runs are omitted from the PDF's selectable text.
+
+Pagination failures include a code at the start of `Error.message`:
+
+- `PAGINATION_LINE_TOO_TALL`: a line exceeds the available printable height.
+- `PAGINATION_NO_PROGRESS`: no valid advancing break exists, including chains
+  of overlapping lines that individually fit the page.
+- `PAGINATION_FORCED_BREAK_INTERSECTS_LINE`: an explicit break cuts a line.
+- `PAGINATION_TABLE_GROUPS_TOO_TALL`: repeated groups leave no room for rows.
+
+These messages include the zero-based page index, document-space page top,
+available height, and, when associated with a DOM line, element tag/ID, internal
+node ID, zero-based line index and measured visible line range. Coordinates and
+heights are CSS pixels. Painted glyph runs without a DOM association and errors
+without a blocking line report those fields as `unavailable`.
+
+The pinned Blitz table layout still differs from Chromium for `td { max-width: 0 }`:
+it can constrain the cell itself to zero content width and wrap short text by
+character, while Chromium distributes the table width across the columns.
+Height-limited containers now paginate their visible content without failing,
+but this does not resolve that separate width-compatibility issue. See the
+[reproduction and investigation](docs/pagination-regressions.md).
+
 The first `<thead>` and `<tfoot>` (or elements styled as `table-header-group`
 and `table-footer-group`) repeat on every fragment of their table. Their actual
 layout, column widths, backgrounds, and selectable text are retained. Use

package/docs/pagination-regressions.md

@@ -0,0 +1,88 @@
+# Pagination regressions in 0.1.2
+
+The regressions are exercised through `renderPdf` in `tests/pagination.test.ts`.
+Rebuild the WASM before running them.
+
+## Final breaks and empty lines
+
+```js
+await renderPdf("<p>Text<br></p>", { format: "A4" });
+```
+
+With the pinned Blitz `e72650a` and Parley 0.12.0, instrumenting this layout
+shows a paragraph height of 19 CSS pixels. Parley supplies two line ranges:
+`[0, 19]` for `Text\n`, and `[19, 38]` with an empty text range and no positioned
+items. Both have a finite, ordinary line height of 19 pixels.
+
+Blitz's `packages/blitz-dom/src/layout/inline.rs` excludes that second line
+from the block's height: it exists to position an editor cursor after a final
+newline, not as another CSS line box. Pagination previously kept it. With the
+default paragraph margins, the document ends inside this extra line; repeated
+attempts to move the break backward eventually stop making progress. The old
+error incorrectly classified this as a line taller than A4.
+
+`css_lines` now uses the same terminal-line test as Blitz, including for
+keep-with-next edges and widow/orphan counts. A real blank line has a newline in
+its text range and remains in pagination with its measured line box. No text,
+invisible anchor, or other character is inserted. Position assertions cover
+multiple blank lines, table cells, and automatic/forced page boundaries.
+
+## Height-limited tables
+
+Use the following HTML in both a browser and `renderPdf(html, { format: "A4" })`:
+
+```html
+<style>
+  .info { width: 75mm; max-height: 75mm; overflow: hidden; }
+  .info table { width: 100%; border-collapse: collapse; }
+  .info td {
+    max-width: 0;
+    word-break: break-all;
+    overflow-wrap: break-word;
+  }
+</style>
+<div class="info">
+  <table>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+  </table>
+</div>
+```
+
+Measured in Chromium 154 on macOS, `getBoundingClientRect()` gives a table
+width of about 283.46 pixels, cell widths of about 141.73 pixels and a total
+height of 123 pixels. Changing `max-width` to `none` produces the same
+dimensions for these equal cell contents.
+
+Blitz's final cell layout instead has width 2 pixels (zero content width plus
+padding), height 78 pixels, and four 19-pixel lines for `Text`. Its table grid
+adapts cells to grid items while retaining `max_size.width`; the inline layout
+therefore receives a zero-width constraint. This confirms a browser
+compatibility difference. It does not establish a general correction to the
+CSS table-width algorithm, which remains a separate upstream task.
+
+The resulting tall table exceeds its container's height. Pagination previously
+used line and row ranges beyond the overflow clip; the document end inside a
+clipped line could cause the same misleading error as the first reproduction.
+Pagination now clips those ranges to the visible padding box and intersects
+glyph bounds with the scene's nested clips. PDF text emission uses the same
+clip bounds to omit fully hidden runs. Regression coverage includes both
+`max-width` values, nested `hidden`/`clip` containers and clipped oversized ink.
+
+The zero-width case now exports, but its column widths still differ from the
+browser. Its test deliberately does not claim that all twelve cells are visible.
+
+## Diagnostic distinctions
+
+`PAGINATION_LINE_TOO_TALL` requires a blocking line whose visible height exceeds
+the available height. `PAGINATION_NO_PROGRESS` covers, for example, staggered
+columns of overlapping 40-pixel lines on an 80-pixel page. A forced break through
+a line has its own `PAGINATION_FORCED_BREAK_INTERSECTS_LINE` code. Tests assert
+the element, page/line indexes, available height and line range, and verify that
+rendering remains usable after an error.
+
+The Argon asset-path issue is outside this change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitz-pdf",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Render HTML and CSS to PDF with Blitz and WebAssembly in Node.js, Bun, and browsers.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "dist",
     "wasm",
     "src",
+    "docs",
     "examples",
     "assets/icon.svg",
     "README.md",