djvu-rs 0.28.0 → 0.30.1

package/README.md

@@ -1,6 +1,8 @@
 # djvu-rs
 
 [![Crates.io](https://badgen.net/crates/v/djvu-rs)](https://crates.io/crates/djvu-rs)
+[![PyPI](https://img.shields.io/pypi/v/djvu-rs)](https://pypi.org/project/djvu-rs/)
+[![npm](https://img.shields.io/npm/v/djvu-rs)](https://www.npmjs.com/package/djvu-rs)
 [![docs.rs](https://docs.rs/djvu-rs/badge.svg)](https://docs.rs/djvu-rs)
 [![CI](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml)
 [![Benchmarks](https://img.shields.io/badge/benchmarks-dashboard-blue)](https://matyushkin.github.io/djvu-rs/dev/bench/)
@@ -8,16 +10,19 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Read, render, convert, and create DjVu files. Pure-Rust library with a CLI,
-WebAssembly, and Python bindings — MIT licensed, no GPL dependencies, written
-from the public DjVu v3 specification.
+WebAssembly, and Python bindings — on [crates.io](https://crates.io/crates/djvu-rs),
+[PyPI](https://pypi.org/project/djvu-rs/), and [npm](https://www.npmjs.com/package/djvu-rs)
+as `djvu-rs`. MIT licensed, no GPL dependencies, written from the public DjVu v3
+specification.
 
 | Your task | How |
 |-----------|-----|
 | Convert DjVu → PDF, EPUB, TIFF, PNG, CBZ | [`djvu render`](#cli) or [`djvu_to_pdf`](#pdf-export) / [`djvu_to_epub`](#epub-export) / [`djvu_to_tiff`](#tiff-export) |
 | Extract text (plain, hOCR, ALTO XML) | [`djvu text`](#cli) or [`page.text()`](#text-extraction), [`to_hocr` / `to_alto`](#hocr-and-alto-xml-export) |
 | Render pages to RGBA pixels | [`render_pixmap`](#quick-start) — sync, [async](#async-render), or [parallel](#feature-flags) |
+| Build a zoomable viewer (tiles) | [`djvu_tile`](#tile-rendering) — cached, prefetchable, cancellable tile rendering |
 | Show DjVu in the browser | [WebAssembly bindings](#webassembly), incl. lazy HTTP-Range loading |
-| Read DjVu from Python | [PyO3 bindings, built from source](#python) |
+| Read DjVu from Python | `pip install djvu-rs` — [PyO3 bindings](#python) |
 | Create DjVu from images (PNG/JPEG/TIFF) | [`djvu encode`](#cli) or [`PageEncoder`](#encoding--low-level-api) |
 | Add an OCR text layer to a scan | [`djvu ocr`](#ocr-recognition-backends) (Tesseract) |
 | Merge, split, edit documents | [`djvu merge` / `djvu split`](#cli), `DocumentEditor`, `DjVuDocumentMut` |
@@ -134,6 +139,8 @@ djvu split book.djvu --pages 10-25 --output chapter.djvu
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup --dry-run
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup
 djvu optimize book.djvu --output optimized.djvu --preset archival --target-size 26214400
+# (--max-ssim-loss is reserved for the planned archival re-encode; the current
+#  lossless cleanup is pixel-exact by construction and reports this)
 djvu optimize book.djvu --output optimized.djvu --max-ssim-loss 0.001
 
 # Encode an image (PNG, JPEG, or TIFF) into a single-page DjVu (bilevel JB2, lossless)
@@ -155,6 +162,12 @@ djvu encode scan.png --quality quality --binarization sauvola --bg-inpaint --out
 # Cap the IW44 background at a bits-per-pixel budget (smaller file, lower quality)
 djvu encode scan.jpg --quality quality --bg-bpp 0.8 --output scan.djvu
 
+# Composite transparent PNG/TIFF pixels onto a solid colour (hex or white/black)
+djvu encode logo.png --background white --output logo.djvu
+
+# Refuse ICC-profiled input instead of silently dropping the profile
+djvu encode scan.png --icc reject --output scan.djvu
+
 # Encode a directory of images into a bundled DJVM with shared Djbz
 djvu encode pages/ --output book.djvu --shared-dict-pages 2
 
@@ -422,6 +435,45 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+### Tile rendering
+
+For viewer engines: [`djvu_tile`](https://docs.rs/djvu-rs/latest/djvu_rs/djvu_tile/)
+renders a page as a display-space tile grid over the region renderer. Tile
+pixels are byte-identical to the same rectangle of a full-page render, in any
+request order.
+
+```rust,no_run
+use djvu_rs::{DjVuDocument, djvu_render::RenderOptions};
+use djvu_rs::djvu_tile::{TileLayout, render_tile_cached};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let data = std::fs::read("book.djvu")?;
+    let doc = DjVuDocument::parse(&data)?;
+    let page = doc.page(0)?;
+
+    let opts = RenderOptions { width: 2400, height: 3200, ..Default::default() };
+    let layout = TileLayout::new(page, &opts, 256)?;
+
+    for row in 0..layout.rows() {
+        for col in 0..layout.cols() {
+            let tile = render_tile_cached(page, &opts, 256, col, row)?;
+            // tile.data — RGBA bytes of exactly this tile rectangle
+            let _ = tile;
+        }
+    }
+    Ok(())
+}
+```
+
+`render_tile_cached` memoizes composited tiles per page; the cache is
+tile-granular and controllable (`tile_cache_usage`, `set_tile_cache_budget`,
+`clear_tile_cache`, `invalidate_tile_region`). `render_tile_with` +
+`TileRenderControls` / `TileCancelToken` add progressive quality steps and
+cooperative cancellation, and with the `parallel` feature `prefetch_tiles` /
+`prefetch_tiles_cancellable` warm the cache in the background with a bounded
+worker pool. The full contract lives in
+[`docs/tile-rendering.md`](docs/tile-rendering.md).
+
 ## Encoding & low-level API
 
 ### JB2 bilevel image encoder
@@ -541,6 +593,16 @@ whole is not transactional). Opening an indirect index directly with
 `DjVuDocumentMut::from_bytes` and calling `page_mut` remains unsupported; see
 [`docs/indirect-djvm-mutation.md`](docs/indirect-djvm-mutation.md).
 
+The reverse direction is covered too: `djvm::to_indirect` splits a bundled
+`FORM:DJVM` into an indirect index plus standalone component files, keeping
+component ids, names, titles, and the document `NAVM` stable. Related
+bundled-document operations in the same module: `djvm::remove_pages` deletes
+pages with an explicit `UnreachablePolicy` (preserve or garbage-collect shared
+components that lose their last including page),
+`djvm::dedup_shared_components` merges byte-identical shared components, and
+`djvm::DjvmStreamWriter` writes a bundle to any `io::Write` sink with memory
+bounded to the spooled component being appended.
+
 ### Typed document editing
 
 `DocumentEditor` provides a versioned, typed operation list with a semantic
@@ -666,8 +728,9 @@ Honest boundaries, so you can decide fast:
 
 - **Library + CLI, not a viewer.** There is no GUI; the WASM demo is the
   closest thing to one.
-- **Python bindings are source-only for now.** The `djvu-py` package is not
-  published to PyPI yet — install it from the repository checkout.
+- **Python bindings cover the reading surface only.** Open, render, and text
+  extraction ship in the PyPI wheels; encode, mutation, and PDF/EPUB/TIFF
+  export stay on the Rust crate / CLI for now.
 - **Indirect DJVM mutation is indirect-only via two paths.**
   `DjVuDocumentMut::from_bytes` + `page_mut` on an indirect index errors;
   use `from_indirect_resolved` (rebundles) or `IndirectRewritePlan` (rewrites
@@ -676,7 +739,9 @@ Honest boundaries, so you can decide fast:
   and single-page `FORM:DJVU` only; indirect returns a clean `Unsupported`
   error.
 - **`create_indirect` does not emit shared `DJVI` dictionary components** —
-  build a bundled document with `djvu merge` when pages share a dictionary.
+  build a bundled document with `djvu merge` when pages share a dictionary, or
+  convert an existing bundled document with `djvm::to_indirect`, which
+  preserves shared components.
 - **Encoder size parity is corpus- and profile-dependent.** Run the
   reproducible [`encoder parity scorecard`](docs/encoder-parity.md) to compare
   the same raster through DjVuLibre 3.5.29's `c44`/`cjb2` and the archival-safe
@@ -756,7 +821,10 @@ combinations and targets), and is enforced in CI. In short:
   [`tests/panic_free_corpus.rs`](tests/panic_free_corpus.rs), proptests, and
   libFuzzer/OSS-Fuzz targets.
 - **Resource limits** — decode/render inherit documented, bounded memory/work
-  ceilings; exceeding one returns a typed error naming the codec and axis. See
+  ceilings; exceeding one returns a typed error naming the codec and axis. The
+  ceilings are caller-configurable: pass `ResourceLimits` via `ParseOptions` to
+  `DjVuDocument::parse_with_options` (pages inherit them at render time), or
+  use `render_pixmap_with_limits` / `render_into_with_limits` directly. See
   [`SECURITY.md`](SECURITY.md#decode-time-resource-ceilings).
 
 ## Performance
@@ -797,7 +865,9 @@ MIT. See [LICENSE](LICENSE).
 
 Written from the public DjVu v3 specification:
 - https://www.sndjvu.org/spec.html
-- https://djvu.sourceforge.net/spec/DjVu3Spec.djvu (the spec is itself a DjVu file)
+- https://web.archive.org/web/20251005122807/http://www.djvu.org/docs/DjVu3Spec.djvu
+  (the spec is itself a DjVu file; archived copy — djvu.org and
+  djvu.sourceforge.net no longer serve the original)
 
 No code derived from GPL-licensed DjVuLibre or any other GPL source.
 All algorithms are independent implementations from the spec.

package/package.json

@@ -2,7 +2,7 @@
   "name": "djvu-rs",
   "type": "module",
   "description": "Read, render, convert, and create DjVu files. Pure-Rust DjVu decoder/encoder with CLI, WebAssembly, and Python bindings. DjVu to PDF, EPUB, TIFF, PNG, and text. MIT licensed, no GPL dependencies.",
-  "version": "0.28.0",
+  "version": "0.30.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scalar/README.md

@@ -1,6 +1,8 @@
 # djvu-rs
 
 [![Crates.io](https://badgen.net/crates/v/djvu-rs)](https://crates.io/crates/djvu-rs)
+[![PyPI](https://img.shields.io/pypi/v/djvu-rs)](https://pypi.org/project/djvu-rs/)
+[![npm](https://img.shields.io/npm/v/djvu-rs)](https://www.npmjs.com/package/djvu-rs)
 [![docs.rs](https://docs.rs/djvu-rs/badge.svg)](https://docs.rs/djvu-rs)
 [![CI](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml)
 [![Benchmarks](https://img.shields.io/badge/benchmarks-dashboard-blue)](https://matyushkin.github.io/djvu-rs/dev/bench/)
@@ -8,16 +10,19 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Read, render, convert, and create DjVu files. Pure-Rust library with a CLI,
-WebAssembly, and Python bindings — MIT licensed, no GPL dependencies, written
-from the public DjVu v3 specification.
+WebAssembly, and Python bindings — on [crates.io](https://crates.io/crates/djvu-rs),
+[PyPI](https://pypi.org/project/djvu-rs/), and [npm](https://www.npmjs.com/package/djvu-rs)
+as `djvu-rs`. MIT licensed, no GPL dependencies, written from the public DjVu v3
+specification.
 
 | Your task | How |
 |-----------|-----|
 | Convert DjVu → PDF, EPUB, TIFF, PNG, CBZ | [`djvu render`](#cli) or [`djvu_to_pdf`](#pdf-export) / [`djvu_to_epub`](#epub-export) / [`djvu_to_tiff`](#tiff-export) |
 | Extract text (plain, hOCR, ALTO XML) | [`djvu text`](#cli) or [`page.text()`](#text-extraction), [`to_hocr` / `to_alto`](#hocr-and-alto-xml-export) |
 | Render pages to RGBA pixels | [`render_pixmap`](#quick-start) — sync, [async](#async-render), or [parallel](#feature-flags) |
+| Build a zoomable viewer (tiles) | [`djvu_tile`](#tile-rendering) — cached, prefetchable, cancellable tile rendering |
 | Show DjVu in the browser | [WebAssembly bindings](#webassembly), incl. lazy HTTP-Range loading |
-| Read DjVu from Python | [PyO3 bindings, built from source](#python) |
+| Read DjVu from Python | `pip install djvu-rs` — [PyO3 bindings](#python) |
 | Create DjVu from images (PNG/JPEG/TIFF) | [`djvu encode`](#cli) or [`PageEncoder`](#encoding--low-level-api) |
 | Add an OCR text layer to a scan | [`djvu ocr`](#ocr-recognition-backends) (Tesseract) |
 | Merge, split, edit documents | [`djvu merge` / `djvu split`](#cli), `DocumentEditor`, `DjVuDocumentMut` |
@@ -134,6 +139,8 @@ djvu split book.djvu --pages 10-25 --output chapter.djvu
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup --dry-run
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup
 djvu optimize book.djvu --output optimized.djvu --preset archival --target-size 26214400
+# (--max-ssim-loss is reserved for the planned archival re-encode; the current
+#  lossless cleanup is pixel-exact by construction and reports this)
 djvu optimize book.djvu --output optimized.djvu --max-ssim-loss 0.001
 
 # Encode an image (PNG, JPEG, or TIFF) into a single-page DjVu (bilevel JB2, lossless)
@@ -155,6 +162,12 @@ djvu encode scan.png --quality quality --binarization sauvola --bg-inpaint --out
 # Cap the IW44 background at a bits-per-pixel budget (smaller file, lower quality)
 djvu encode scan.jpg --quality quality --bg-bpp 0.8 --output scan.djvu
 
+# Composite transparent PNG/TIFF pixels onto a solid colour (hex or white/black)
+djvu encode logo.png --background white --output logo.djvu
+
+# Refuse ICC-profiled input instead of silently dropping the profile
+djvu encode scan.png --icc reject --output scan.djvu
+
 # Encode a directory of images into a bundled DJVM with shared Djbz
 djvu encode pages/ --output book.djvu --shared-dict-pages 2
 
@@ -422,6 +435,45 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+### Tile rendering
+
+For viewer engines: [`djvu_tile`](https://docs.rs/djvu-rs/latest/djvu_rs/djvu_tile/)
+renders a page as a display-space tile grid over the region renderer. Tile
+pixels are byte-identical to the same rectangle of a full-page render, in any
+request order.
+
+```rust,no_run
+use djvu_rs::{DjVuDocument, djvu_render::RenderOptions};
+use djvu_rs::djvu_tile::{TileLayout, render_tile_cached};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let data = std::fs::read("book.djvu")?;
+    let doc = DjVuDocument::parse(&data)?;
+    let page = doc.page(0)?;
+
+    let opts = RenderOptions { width: 2400, height: 3200, ..Default::default() };
+    let layout = TileLayout::new(page, &opts, 256)?;
+
+    for row in 0..layout.rows() {
+        for col in 0..layout.cols() {
+            let tile = render_tile_cached(page, &opts, 256, col, row)?;
+            // tile.data — RGBA bytes of exactly this tile rectangle
+            let _ = tile;
+        }
+    }
+    Ok(())
+}
+```
+
+`render_tile_cached` memoizes composited tiles per page; the cache is
+tile-granular and controllable (`tile_cache_usage`, `set_tile_cache_budget`,
+`clear_tile_cache`, `invalidate_tile_region`). `render_tile_with` +
+`TileRenderControls` / `TileCancelToken` add progressive quality steps and
+cooperative cancellation, and with the `parallel` feature `prefetch_tiles` /
+`prefetch_tiles_cancellable` warm the cache in the background with a bounded
+worker pool. The full contract lives in
+[`docs/tile-rendering.md`](docs/tile-rendering.md).
+
 ## Encoding & low-level API
 
 ### JB2 bilevel image encoder
@@ -541,6 +593,16 @@ whole is not transactional). Opening an indirect index directly with
 `DjVuDocumentMut::from_bytes` and calling `page_mut` remains unsupported; see
 [`docs/indirect-djvm-mutation.md`](docs/indirect-djvm-mutation.md).
 
+The reverse direction is covered too: `djvm::to_indirect` splits a bundled
+`FORM:DJVM` into an indirect index plus standalone component files, keeping
+component ids, names, titles, and the document `NAVM` stable. Related
+bundled-document operations in the same module: `djvm::remove_pages` deletes
+pages with an explicit `UnreachablePolicy` (preserve or garbage-collect shared
+components that lose their last including page),
+`djvm::dedup_shared_components` merges byte-identical shared components, and
+`djvm::DjvmStreamWriter` writes a bundle to any `io::Write` sink with memory
+bounded to the spooled component being appended.
+
 ### Typed document editing
 
 `DocumentEditor` provides a versioned, typed operation list with a semantic
@@ -666,8 +728,9 @@ Honest boundaries, so you can decide fast:
 
 - **Library + CLI, not a viewer.** There is no GUI; the WASM demo is the
   closest thing to one.
-- **Python bindings are source-only for now.** The `djvu-py` package is not
-  published to PyPI yet — install it from the repository checkout.
+- **Python bindings cover the reading surface only.** Open, render, and text
+  extraction ship in the PyPI wheels; encode, mutation, and PDF/EPUB/TIFF
+  export stay on the Rust crate / CLI for now.
 - **Indirect DJVM mutation is indirect-only via two paths.**
   `DjVuDocumentMut::from_bytes` + `page_mut` on an indirect index errors;
   use `from_indirect_resolved` (rebundles) or `IndirectRewritePlan` (rewrites
@@ -676,7 +739,9 @@ Honest boundaries, so you can decide fast:
   and single-page `FORM:DJVU` only; indirect returns a clean `Unsupported`
   error.
 - **`create_indirect` does not emit shared `DJVI` dictionary components** —
-  build a bundled document with `djvu merge` when pages share a dictionary.
+  build a bundled document with `djvu merge` when pages share a dictionary, or
+  convert an existing bundled document with `djvm::to_indirect`, which
+  preserves shared components.
 - **Encoder size parity is corpus- and profile-dependent.** Run the
   reproducible [`encoder parity scorecard`](docs/encoder-parity.md) to compare
   the same raster through DjVuLibre 3.5.29's `c44`/`cjb2` and the archival-safe
@@ -756,7 +821,10 @@ combinations and targets), and is enforced in CI. In short:
   [`tests/panic_free_corpus.rs`](tests/panic_free_corpus.rs), proptests, and
   libFuzzer/OSS-Fuzz targets.
 - **Resource limits** — decode/render inherit documented, bounded memory/work
-  ceilings; exceeding one returns a typed error naming the codec and axis. See
+  ceilings; exceeding one returns a typed error naming the codec and axis. The
+  ceilings are caller-configurable: pass `ResourceLimits` via `ParseOptions` to
+  `DjVuDocument::parse_with_options` (pages inherit them at render time), or
+  use `render_pixmap_with_limits` / `render_into_with_limits` directly. See
   [`SECURITY.md`](SECURITY.md#decode-time-resource-ceilings).
 
 ## Performance
@@ -797,7 +865,9 @@ MIT. See [LICENSE](LICENSE).
 
 Written from the public DjVu v3 specification:
 - https://www.sndjvu.org/spec.html
-- https://djvu.sourceforge.net/spec/DjVu3Spec.djvu (the spec is itself a DjVu file)
+- https://web.archive.org/web/20251005122807/http://www.djvu.org/docs/DjVu3Spec.djvu
+  (the spec is itself a DjVu file; archived copy — djvu.org and
+  djvu.sourceforge.net no longer serve the original)
 
 No code derived from GPL-licensed DjVuLibre or any other GPL source.
 All algorithms are independent implementations from the spec.

package/simd128/README.md

@@ -1,6 +1,8 @@
 # djvu-rs
 
 [![Crates.io](https://badgen.net/crates/v/djvu-rs)](https://crates.io/crates/djvu-rs)
+[![PyPI](https://img.shields.io/pypi/v/djvu-rs)](https://pypi.org/project/djvu-rs/)
+[![npm](https://img.shields.io/npm/v/djvu-rs)](https://www.npmjs.com/package/djvu-rs)
 [![docs.rs](https://docs.rs/djvu-rs/badge.svg)](https://docs.rs/djvu-rs)
 [![CI](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/matyushkin/djvu-rs/actions/workflows/ci.yml)
 [![Benchmarks](https://img.shields.io/badge/benchmarks-dashboard-blue)](https://matyushkin.github.io/djvu-rs/dev/bench/)
@@ -8,16 +10,19 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Read, render, convert, and create DjVu files. Pure-Rust library with a CLI,
-WebAssembly, and Python bindings — MIT licensed, no GPL dependencies, written
-from the public DjVu v3 specification.
+WebAssembly, and Python bindings — on [crates.io](https://crates.io/crates/djvu-rs),
+[PyPI](https://pypi.org/project/djvu-rs/), and [npm](https://www.npmjs.com/package/djvu-rs)
+as `djvu-rs`. MIT licensed, no GPL dependencies, written from the public DjVu v3
+specification.
 
 | Your task | How |
 |-----------|-----|
 | Convert DjVu → PDF, EPUB, TIFF, PNG, CBZ | [`djvu render`](#cli) or [`djvu_to_pdf`](#pdf-export) / [`djvu_to_epub`](#epub-export) / [`djvu_to_tiff`](#tiff-export) |
 | Extract text (plain, hOCR, ALTO XML) | [`djvu text`](#cli) or [`page.text()`](#text-extraction), [`to_hocr` / `to_alto`](#hocr-and-alto-xml-export) |
 | Render pages to RGBA pixels | [`render_pixmap`](#quick-start) — sync, [async](#async-render), or [parallel](#feature-flags) |
+| Build a zoomable viewer (tiles) | [`djvu_tile`](#tile-rendering) — cached, prefetchable, cancellable tile rendering |
 | Show DjVu in the browser | [WebAssembly bindings](#webassembly), incl. lazy HTTP-Range loading |
-| Read DjVu from Python | [PyO3 bindings, built from source](#python) |
+| Read DjVu from Python | `pip install djvu-rs` — [PyO3 bindings](#python) |
 | Create DjVu from images (PNG/JPEG/TIFF) | [`djvu encode`](#cli) or [`PageEncoder`](#encoding--low-level-api) |
 | Add an OCR text layer to a scan | [`djvu ocr`](#ocr-recognition-backends) (Tesseract) |
 | Merge, split, edit documents | [`djvu merge` / `djvu split`](#cli), `DocumentEditor`, `DjVuDocumentMut` |
@@ -134,6 +139,8 @@ djvu split book.djvu --pages 10-25 --output chapter.djvu
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup --dry-run
 djvu optimize book.djvu --output optimized.djvu --preset lossless-cleanup
 djvu optimize book.djvu --output optimized.djvu --preset archival --target-size 26214400
+# (--max-ssim-loss is reserved for the planned archival re-encode; the current
+#  lossless cleanup is pixel-exact by construction and reports this)
 djvu optimize book.djvu --output optimized.djvu --max-ssim-loss 0.001
 
 # Encode an image (PNG, JPEG, or TIFF) into a single-page DjVu (bilevel JB2, lossless)
@@ -155,6 +162,12 @@ djvu encode scan.png --quality quality --binarization sauvola --bg-inpaint --out
 # Cap the IW44 background at a bits-per-pixel budget (smaller file, lower quality)
 djvu encode scan.jpg --quality quality --bg-bpp 0.8 --output scan.djvu
 
+# Composite transparent PNG/TIFF pixels onto a solid colour (hex or white/black)
+djvu encode logo.png --background white --output logo.djvu
+
+# Refuse ICC-profiled input instead of silently dropping the profile
+djvu encode scan.png --icc reject --output scan.djvu
+
 # Encode a directory of images into a bundled DJVM with shared Djbz
 djvu encode pages/ --output book.djvu --shared-dict-pages 2
 
@@ -422,6 +435,45 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+### Tile rendering
+
+For viewer engines: [`djvu_tile`](https://docs.rs/djvu-rs/latest/djvu_rs/djvu_tile/)
+renders a page as a display-space tile grid over the region renderer. Tile
+pixels are byte-identical to the same rectangle of a full-page render, in any
+request order.
+
+```rust,no_run
+use djvu_rs::{DjVuDocument, djvu_render::RenderOptions};
+use djvu_rs::djvu_tile::{TileLayout, render_tile_cached};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let data = std::fs::read("book.djvu")?;
+    let doc = DjVuDocument::parse(&data)?;
+    let page = doc.page(0)?;
+
+    let opts = RenderOptions { width: 2400, height: 3200, ..Default::default() };
+    let layout = TileLayout::new(page, &opts, 256)?;
+
+    for row in 0..layout.rows() {
+        for col in 0..layout.cols() {
+            let tile = render_tile_cached(page, &opts, 256, col, row)?;
+            // tile.data — RGBA bytes of exactly this tile rectangle
+            let _ = tile;
+        }
+    }
+    Ok(())
+}
+```
+
+`render_tile_cached` memoizes composited tiles per page; the cache is
+tile-granular and controllable (`tile_cache_usage`, `set_tile_cache_budget`,
+`clear_tile_cache`, `invalidate_tile_region`). `render_tile_with` +
+`TileRenderControls` / `TileCancelToken` add progressive quality steps and
+cooperative cancellation, and with the `parallel` feature `prefetch_tiles` /
+`prefetch_tiles_cancellable` warm the cache in the background with a bounded
+worker pool. The full contract lives in
+[`docs/tile-rendering.md`](docs/tile-rendering.md).
+
 ## Encoding & low-level API
 
 ### JB2 bilevel image encoder
@@ -541,6 +593,16 @@ whole is not transactional). Opening an indirect index directly with
 `DjVuDocumentMut::from_bytes` and calling `page_mut` remains unsupported; see
 [`docs/indirect-djvm-mutation.md`](docs/indirect-djvm-mutation.md).
 
+The reverse direction is covered too: `djvm::to_indirect` splits a bundled
+`FORM:DJVM` into an indirect index plus standalone component files, keeping
+component ids, names, titles, and the document `NAVM` stable. Related
+bundled-document operations in the same module: `djvm::remove_pages` deletes
+pages with an explicit `UnreachablePolicy` (preserve or garbage-collect shared
+components that lose their last including page),
+`djvm::dedup_shared_components` merges byte-identical shared components, and
+`djvm::DjvmStreamWriter` writes a bundle to any `io::Write` sink with memory
+bounded to the spooled component being appended.
+
 ### Typed document editing
 
 `DocumentEditor` provides a versioned, typed operation list with a semantic
@@ -666,8 +728,9 @@ Honest boundaries, so you can decide fast:
 
 - **Library + CLI, not a viewer.** There is no GUI; the WASM demo is the
   closest thing to one.
-- **Python bindings are source-only for now.** The `djvu-py` package is not
-  published to PyPI yet — install it from the repository checkout.
+- **Python bindings cover the reading surface only.** Open, render, and text
+  extraction ship in the PyPI wheels; encode, mutation, and PDF/EPUB/TIFF
+  export stay on the Rust crate / CLI for now.
 - **Indirect DJVM mutation is indirect-only via two paths.**
   `DjVuDocumentMut::from_bytes` + `page_mut` on an indirect index errors;
   use `from_indirect_resolved` (rebundles) or `IndirectRewritePlan` (rewrites
@@ -676,7 +739,9 @@ Honest boundaries, so you can decide fast:
   and single-page `FORM:DJVU` only; indirect returns a clean `Unsupported`
   error.
 - **`create_indirect` does not emit shared `DJVI` dictionary components** —
-  build a bundled document with `djvu merge` when pages share a dictionary.
+  build a bundled document with `djvu merge` when pages share a dictionary, or
+  convert an existing bundled document with `djvm::to_indirect`, which
+  preserves shared components.
 - **Encoder size parity is corpus- and profile-dependent.** Run the
   reproducible [`encoder parity scorecard`](docs/encoder-parity.md) to compare
   the same raster through DjVuLibre 3.5.29's `c44`/`cjb2` and the archival-safe
@@ -756,7 +821,10 @@ combinations and targets), and is enforced in CI. In short:
   [`tests/panic_free_corpus.rs`](tests/panic_free_corpus.rs), proptests, and
   libFuzzer/OSS-Fuzz targets.
 - **Resource limits** — decode/render inherit documented, bounded memory/work
-  ceilings; exceeding one returns a typed error naming the codec and axis. See
+  ceilings; exceeding one returns a typed error naming the codec and axis. The
+  ceilings are caller-configurable: pass `ResourceLimits` via `ParseOptions` to
+  `DjVuDocument::parse_with_options` (pages inherit them at render time), or
+  use `render_pixmap_with_limits` / `render_into_with_limits` directly. See
   [`SECURITY.md`](SECURITY.md#decode-time-resource-ceilings).
 
 ## Performance
@@ -797,7 +865,9 @@ MIT. See [LICENSE](LICENSE).
 
 Written from the public DjVu v3 specification:
 - https://www.sndjvu.org/spec.html
-- https://djvu.sourceforge.net/spec/DjVu3Spec.djvu (the spec is itself a DjVu file)
+- https://web.archive.org/web/20251005122807/http://www.djvu.org/docs/DjVu3Spec.djvu
+  (the spec is itself a DjVu file; archived copy — djvu.org and
+  djvu.sourceforge.net no longer serve the original)
 
 No code derived from GPL-licensed DjVuLibre or any other GPL source.
 All algorithms are independent implementations from the spec.