@laminapdf/sdk 0.2.0-alpha.3 → 0.2.0-alpha.4

package/docs/errors/extract-column-order-uncertain.md

@@ -0,0 +1,38 @@
+---
+title: "extract-column-order-uncertain"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-column-order-uncertain/"
+---
+
+# extract-column-order-uncertain
+
+- Type: warning
+- Kind: `unsupported` (something Lamina PDF can't do yet)
+
+## What happened
+
+Extraction read the page's columns in an order its layout rules had to guess, so the page's blocks may be in the wrong order. The blocks the guess concerns have a `confidence` of 0.5 instead of 0.75; the order itself is the rules' best one.
+
+## Why
+
+A PDF stores where each piece of text is drawn, not the order to read it in, so extraction works the order out from the layout: columns first, top to bottom. Three layouts leave that order in doubt, and the warning's `reason` names which one it found:
+
+- `narrow-gutter`: two columns sit closer together than a font size, so lines may have been read straight across both columns.
+- `columns-revisited`: a block across the gutter, such as a pull quote with the text wrapped round it, cut the columns into rows, so the order leaves a column and comes back to it.
+- `near-grid`: blocks that look like an unruled table, with one cell wrapped onto a second line, were read column by column; read by rows, the order would differ.
+
+A page that mixes horizontal and vertical writing raises [`extract-reading-order-ambiguous`](extract-reading-order-ambiguous.md) instead.
+
+## How to fix
+
+Check the page's text, or send the page to a layout model, which reads columns from the page's image. A tagged file read in its structure tree's order never raises this warning. Like every warning, it fails the call in strict mode.
+
+## Example
+
+A newsletter page with two columns set 7 pt apart: each line of the extracted text runs across both columns, and the page is warned with `narrow-gutter`.
+
+## Data fields
+
+- `reason`: `narrow-gutter`, `columns-revisited` or `near-grid`, the first check that doubted the order.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-limit-blocks.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-limit-blocks"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-limit-blocks/"
 ---
 

package/docs/errors/extract-module-not-loaded.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-module-not-loaded"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-module-not-loaded/"
 ---
 

package/docs/errors/extract-needs-ocr.md

@@ -0,0 +1,37 @@
+---
+title: "extract-needs-ocr"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/extract-needs-ocr/"
+---
+
+# extract-needs-ocr
+
+- Type: warning
+- Kind: `unsupported` (something Lamina PDF can't do yet)
+
+## What happened
+
+The page has no text that extraction can use, so the page's Markdown, text and blocks are empty or close to it. Each page's `textLayer` in the extraction says why, and this warning names the pages whose status is `needs-ocr` or `ocr-layer`.
+
+## Why
+
+A page's text comes from its fonts. Some pages draw their words in other ways:
+
+- a scanned page is one image, with no text at all;
+- a page made searchable by OCR has an image under invisible text, which extraction leaves out of the blocks because a reader can't see it;
+- outlined text is drawn as shapes, not glyphs;
+- a font without a Unicode mapping draws glyphs that extraction can't turn into characters.
+
+## How to fix
+
+Send the pages this warning names to OCR or a vision model. On an `ocr-layer` page you can instead keep the existing OCR layer: extraction lists its text under `dropped` as `invisible` when you set `drop: { keepSpans: true }` (`DropOptions::keep_spans` in Rust). Like every warning, it fails the call in strict mode.
+
+## Example
+
+A scanned contract: every page is `needs-ocr`, and the extraction's Markdown is empty.
+
+## Data fields
+
+- `status`: the page's text-layer status, `needs-ocr` or `ocr-layer`.
+
+The `location` has the page's `pageIndex`.

package/docs/errors/extract-reading-order-ambiguous.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-reading-order-ambiguous"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-reading-order-ambiguous/"
 ---
 

package/docs/errors/extract-struct-tree-ignored.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-struct-tree-ignored"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-struct-tree-ignored/"
 ---
 

package/docs/errors/extract-table-ambiguous.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-table-ambiguous"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-table-ambiguous/"
 ---
 

package/docs/errors/extract-table-limit.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-table-limit"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-table-limit/"
 ---
 

package/docs/errors/extract-untagged-content.md

@@ -1,6 +1,6 @@
 ---
 title: "extract-untagged-content"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/extract-untagged-content/"
 ---
 

package/docs/errors/fetch-failed.md

@@ -1,6 +1,6 @@
 ---
 title: "fetch-failed"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/fetch-failed/"
 ---
 
@@ -15,11 +15,11 @@ A range source of `@laminapdf/sdk` (`httpRangeSource`) couldn't get bytes it ask
 
 ## Why
 
-Opening a remote file range by range depends on the server: it must allow the `Range` request (and, across origins, expose `Content-Range`, `Content-Length` and `ETag` through CORS), and must not compress the response (`Content-Encoding` breaks byte ranges). Lamina PDF never retries on its own; the error says the bytes are not available.
+Opening a remote file range by range depends on the server: it must allow the `Range` request and must not compress the response (`Content-Encoding` breaks byte ranges). Across origins, it must also allow the `If-Range` header that every request after the first carries, and expose `Content-Range`, `Content-Length` and `ETag` through CORS. Lamina PDF never retries on its own; the error says the bytes are not available.
 
 ## How to fix
 
-Check that the URL is reachable from where the code runs and that the server sends `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers: Range` and `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`. Serve PDFs without `Content-Encoding`. Retry the call yourself if the failure was transient.
+Check that the URL is reachable from where the code runs and that the server sends `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers: Range, If-Range` and `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`. Serve PDFs without `Content-Encoding`. Retry the call yourself if the failure was transient.
 
 ## Example
 

package/docs/errors/flate-truncated.md

@@ -1,6 +1,6 @@
 ---
 title: "flate-truncated"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/flate-truncated/"
 ---
 

package/docs/errors/flow-content-too-large.md

@@ -0,0 +1,34 @@
+---
+title: "flow-content-too-large"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-content-too-large/"
+---
+
+# flow-content-too-large
+
+- Type: error
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::flow` found a figure, a single line of text or a table row taller than the body of a page: the space between the top and bottom margins. No page can hold it, so the flow stopped and added no pages. A line or row counts together with the footnotes it cites, since its notes go at the foot of its page.
+
+## Why
+
+A flow moves a figure to the next page when it doesn't fit, and splits a paragraph only between lines. A figure or a line taller than a whole page would fit on no page at all, and cutting it would hide part of it.
+
+## How to fix
+
+Make the figure narrower with `Figure::with_width`, so its height shrinks with it. For a line, use a smaller text size or a smaller line height. For a footnote, shorten the note or split it into two. Or give the page more room with a taller page size or smaller top and bottom margins.
+
+## Example
+
+```rust
+let tall = Image::rgba(1, 10, &[0; 40])?; // ten times as tall as it is wide
+let flow = Flow::new(PageTemplate::new(PageSize::A6)).block(FlowBlock::Figure(Figure::new(tall, "A bar")));
+builder.flow(&flow)?; // flow-content-too-large
+```
+
+## Data fields
+
+- `what`: what is too tall: `line`, `figure`, `table row`, or `footnote` when a line or table row and its footnotes fit on no page together.

package/docs/errors/flow-keep-broken.md

@@ -0,0 +1,34 @@
+---
+title: "flow-keep-broken"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-keep-broken/"
+---
+
+# flow-keep-broken
+
+- Type: warning
+- Kind: `usage` (the caller misused the API)
+
+## What happened
+
+`Builder::flow` met blocks it was asked to keep on one page, and together they are taller than a page. The flow split them across pages anyway. Blocks are kept together by a `FlowBlock::Keep` group, or by a heading or a paragraph set to keep with the block after it.
+
+## Why
+
+Blocks that can't fit on one page can't be kept on one page. No layout can keep them together, so the flow doesn't look for one. It lays them out as it would without the rule, and every page still ends on a whole line.
+
+## How to fix
+
+Keep fewer blocks together: split a long `Keep` group into smaller ones, or turn off `keep_with_next` on a paragraph in a long chain. Or make the page taller, or its margins smaller, so the group fits.
+
+## Example
+
+```rust
+let group = FlowBlock::Keep(vec![long_intro, long_paragraph]); // taller than a page
+let report = builder.flow(&Flow::new(template).block(group))?;
+assert_eq!(report.warnings[0].code(), "flow-keep-broken");
+```
+
+## Data fields
+
+- `page`: the page the blocks start on, counted from 0 within the flow.

package/docs/errors/flow-layout-unstable.md

@@ -0,0 +1,38 @@
+---
+title: "flow-layout-unstable"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/flow-layout-unstable/"
+---
+
+# flow-layout-unstable
+
+- Type: error
+- Kind: `internal` (a bug in Lamina PDF or a broken invariant)
+
+## What happened
+
+`Builder::flow` laid out a flow with a contents page four times, and the page numbers on the contents page still changed. The flow stopped and added no pages.
+
+## Why
+
+A contents page lists each heading with the page it starts on, but those pages aren't known until the flow is laid out. So the flow lays everything out, writes the numbers it found into the contents page, and lays out again to check them. Each entry keeps the same room for its number however wide the number is, so the contents page's length never depends on the numbers, and the second layout finds the same pages.
+
+The flow still checks up to four layouts. This error means the numbers kept changing anyway, which points to a fault in Lamina PDF's layout rather than in your document.
+
+## How to fix
+
+Report the flow that fails, with the blocks and page template that produce it. Until it is fixed, a page break after the contents block may avoid the error, since the headings after it then start on pages of their own.
+
+## Example
+
+```rust
+let flow = Flow::new(template)
+    .block(FlowBlock::Contents(Contents::new(&style)))
+    .block(FlowBlock::PageBreak) // the headings start on their own pages
+    .block(FlowBlock::Heading(1, Paragraph::plain("Introduction", &heading)));
+builder.flow(&flow)?;
+```
+
+## Data fields
+
+None.

package/docs/errors/font-invalid.md

@@ -1,6 +1,6 @@
 ---
 title: "font-invalid"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/font-invalid/"
 ---
 

package/docs/errors/font-mismatch.md

@@ -1,6 +1,6 @@
 ---
 title: "font-mismatch"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/font-mismatch/"
 ---
 

package/docs/errors/font-not-embeddable.md

@@ -1,6 +1,6 @@
 ---
 title: "font-not-embeddable"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/font-not-embeddable/"
 ---
 

package/docs/errors/font-not-embedded.md

@@ -1,6 +1,6 @@
 ---
 title: "font-not-embedded"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/font-not-embedded/"
 ---
 

package/docs/errors/font-not-shapable.md

@@ -1,6 +1,6 @@
 ---
 title: "font-not-shapable"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/font-not-shapable/"
 ---
 

package/docs/errors/glyph-out-of-range.md

@@ -1,6 +1,6 @@
 ---
 title: "glyph-out-of-range"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/glyph-out-of-range/"
 ---
 

package/docs/errors/glyph-without-unicode.md

@@ -1,6 +1,6 @@
 ---
 title: "glyph-without-unicode"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/glyph-without-unicode/"
 ---
 
@@ -11,20 +11,22 @@ url: "https://docs.laminapdf.com/reference/codes/glyph-without-unicode/"
 
 ## What happened
 
-Under PDF/A-2u or PDF/UA-1, a glyph was drawn that stands for no text of its own, or whose text is U+0000, U+FEFF or U+FFFE. Shaping can draw one cluster (a group of characters that display as one unit) with several glyphs. The text then belongs to the first glyph, and the others stand for none.
+Under PDF/A-2u or PDF/UA-1, a glyph was drawn with no Unicode value, or with one that holds U+0000, U+FEFF or U+FFFE.
+
+A glyph that maps to the empty value doesn't fail. Shaping can draw one character with several glyphs: Noto Sans Arabic draws a beh as a dotless body and a dot. The body then carries the letter and the dot maps to the empty value, so the letter is read once.
 
 ## Why
 
-Software can search, copy or read text aloud only when every glyph maps to a usable Unicode value. The PDF/A-2u archival standard (ISO 19005-2 §6.2.11.7.2) and the PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.21.7) both need that mapping. These are conditions 31-027 to 31-029 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures. Lamina PDF maps a glyph that stands for no text to an empty value, which these profiles reject.
+Software can search, copy or read text aloud only when every glyph maps to a usable Unicode value. The PDF/A-2u archival standard (ISO 19005-2 §6.2.11.7.2) and the PDF/UA-1 standard for accessible PDF (ISO 14289-1 §7.21.7) both need that mapping. These are conditions 31-027 to 31-029 of the Matterhorn Protocol, the PDF Association's checklist of PDF/UA failures.
 
 ## How to fix
 
-Check the text for control characters and byte-order marks. If shaping draws several glyphs for one cluster, choose a font that draws each cluster as one glyph. An archive that needs no accessibility can use PDF/A-2b instead, which doesn't need Unicode for every glyph. PDF/UA-1 has no such relaxed variant, so a PDF/UA-1 document needs the font change.
+Remove the NUL characters (U+0000) from the text, and check what it was decoded from: a NUL usually means a UTF-16 string read as UTF-8, or the end of a C string. An archive that needs no accessibility can use PDF/A-2b instead, which doesn't need Unicode for every glyph. PDF/UA-1 has no such relaxed variant.
 
 ## Example
 
 ```rust
-surface.text("\u{FEFF}Report", &font, Pt::new(12.0), at)?;
+surface.text("\u{0}Report", &font, Pt::new(12.0), at)?;
 builder.finish()?; // glyph-without-unicode under Profile::PdfA2u
 ```
 

package/docs/errors/heading-level-skipped.md

@@ -1,6 +1,6 @@
 ---
 title: "heading-level-skipped"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/heading-level-skipped/"
 ---
 

package/docs/errors/image-data-length.md

@@ -1,6 +1,6 @@
 ---
 title: "image-data-length"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/image-data-length/"
 ---
 

package/docs/errors/image-too-large.md

@@ -1,6 +1,6 @@
 ---
 title: "image-too-large"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/image-too-large/"
 ---
 

package/docs/errors/inline-image-unterminated.md

@@ -1,6 +1,6 @@
 ---
 title: "inline-image-unterminated"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/inline-image-unterminated/"
 ---
 

package/docs/errors/input-unreadable.md

@@ -1,6 +1,6 @@
 ---
 title: "input-unreadable"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/input-unreadable/"
 ---
 

package/docs/errors/instance-reset.md

@@ -1,6 +1,6 @@
 ---
 title: "instance-reset"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/instance-reset/"
 ---
 

package/docs/errors/invalid-argument.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-argument"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-argument/"
 ---
 

package/docs/errors/invalid-axis-value.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-axis-value"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-axis-value/"
 ---
 

package/docs/errors/invalid-box.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-box"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-box/"
 ---
 

package/docs/errors/invalid-color.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-color"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-color/"
 ---
 

package/docs/errors/invalid-command-line.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-command-line"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-command-line/"
 ---
 

package/docs/errors/invalid-date.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-date"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-date/"
 ---
 

package/docs/errors/invalid-entry.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-entry"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-entry/"
 ---
 

package/docs/errors/invalid-feature.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-feature"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-feature/"
 ---
 

package/docs/errors/invalid-font.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-font"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-font/"
 ---
 

package/docs/errors/invalid-geometry.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-geometry"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-geometry/"
 ---
 

package/docs/errors/invalid-icc-profile.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-icc-profile"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-icc-profile/"
 ---
 

package/docs/errors/invalid-image.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-image"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-image/"
 ---
 

package/docs/errors/invalid-op-log.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-op-log"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-op-log/"
 ---
 

package/docs/errors/invalid-page-label.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-page-label"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-page-label/"
 ---
 

package/docs/errors/invalid-page-labels.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-page-labels"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-page-labels/"
 ---
 

package/docs/errors/invalid-page-range.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-page-range"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-page-range/"
 ---
 

package/docs/errors/invalid-rotate.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-rotate"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-rotate/"
 ---
 

package/docs/errors/invalid-spans.md

@@ -0,0 +1,39 @@
+---
+title: "invalid-spans"
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/reference/codes/invalid-spans/"
+---
+
+# invalid-spans
+
+- Type: error
+- Kind: `usage` (the caller passed something invalid)
+
+## What happened
+
+The styled spans passed to `break_spans` don't cover the paragraph's text exactly once, in order, or name fonts it can't use. One of these is true:
+
+- two spans leave a gap, overlap, or come out of order;
+- the last span stops before the end of the text, or runs past it;
+- a span starts or ends inside a character, or between a letter and its accent;
+- a span lists no fonts, or a font index past the end of the list.
+
+## Why
+
+Each character's font, size and language come from the span that holds it. A character in no span, or in two, would have no style or two styles, so Lamina PDF refuses the spans rather than guess. A letter and its accent are drawn as one glyph cluster, so they can't take two styles. An index past the end of the font list names no font.
+
+## How to fix
+
+List the spans in the order of the text. Start the first at byte 0, start each span where the one before it ends, and end the last at the text's length. Take span ends from `grapheme_boundaries` or `str::len`, so that they fall between clusters. List at least one font per span, each an index into the font list. An empty text needs no spans.
+
+## Example
+
+```rust
+let text = "Hello, world";
+let spans = [StyledSpan::new(0..5), StyledSpan::new(6..12)]; // byte 5 is in no span
+break_spans(&shaper, &fonts, text, &spans, &options)?; // invalid-spans
+```
+
+## Data fields
+
+- `at`: the byte offset where the spans stop covering the text, or where the span with a bad font list starts.

package/docs/errors/invalid-structure-nesting.md

@@ -1,6 +1,6 @@
 ---
 title: "invalid-structure-nesting"
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 url: "https://docs.laminapdf.com/reference/codes/invalid-structure-nesting/"
 ---