fullbleed 2.2.2__tar.gz → 2.2.4__tar.gz

{fullbleed-2.2.2 → fullbleed-2.2.4}/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "fullbleed"
-version = "2.2.2"
+version = "2.2.4"
 dependencies = [
  "fullbleed_audit_contract",
  "subsetter",

{fullbleed-2.2.2 → fullbleed-2.2.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fullbleed"
-version = "2.2.2"
+version = "2.2.4"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"

{fullbleed-2.2.2 → fullbleed-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullbleed
-Version: 2.2.2
+Version: 2.2.4
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
@@ -136,6 +136,24 @@ size-changing records render 200x faster. See
 [`docs/performance-architecture.md`](docs/performance-architecture.md) for the packed vector IR,
 typed-binding, virtual-linker, and shader roadmap.
 
+Fullbleed 2.2.4 adds a third compiler lane for
+size-changing records: `CompiledDocument.render_pdf_reflow_bindings(...)`. It parses and recovers
+the template DOM once and compiles encountered structural flow variants into guarded fixed-point
+display programs. Matching records bind directly into those programs; workers execute pre-shaped
+text/TJ paint slots, cached static PDF page segments, page-local Deflate, and one ordered linker.
+Explicit trusted structural slots use `data-fb-bind-html="slot"`. A value that no compiled variant
+can safely place runs ordinary fixed-point layout once to add another variant.
+
+On the independent 1,000-distinct-record case study, the final ABI3 wheel's 29-sample hot
+direct-file run had a 168.839 ms median: **5,923 records/s and 10,365 pages/s**, with a 12,510
+pages/s best. It produced
+the exact 1,750-page 500/300/150/50 reflow distribution and verified all 24,900 markers. The
+throughput-tuned 6,870,320-byte PDF was deterministic across all samples. With the compact
+compression setting, compiled output was also byte-for-byte identical to ordinary rendering:
+5,298,961 bytes and SHA-256 `bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138`.
+This is a hot compiled-variant result, not a claim for previously unseen structure; the first
+compile-on-demand batch measured 407.521 ms (4,294 pages/s).
+
 ## Install
 
 New to Python or setting up on a fresh machine? Start with `docs/install-non-technical.md`.
@@ -147,7 +165,7 @@ python -m pip install fullbleed
 From a local wheel:
 
 ```bash
-python -m pip install C:\path\to\fullbleed-2.2.2-cp310-abi3-win_amd64.whl
+python -m pip install C:\path\to\fullbleed-2.2.4-cp310-abi3-win_amd64.whl
 ```
 
 From a source checkout with Rust installed, no Python build package is needed:
@@ -198,7 +216,9 @@ vendors `inter` into `vendor/fonts/Inter-Variable.ttf`, writes license notices
 and seeds `assets.lock.json` with pinned hashes.
 The scaffolded `report.py` also runs a component mount smoke validation before
 main render and writes `output/component_mount_validation.json` (fails fast on
-missing glyphs, placement overflow, or CSS miss signals parsed from debug logs).
+missing glyphs, actual pagination overflow, or CSS miss signals). On current engines,
+render-time pagination is authoritative for overflow; conservative JIT placement bounds
+remain the compatibility fallback for older engines.
 Scaffolded components now include `components/primitives.py` with reusable
 layout/content helpers (`Stack`, `Row`, `Text`, table/list helpers, key/value rows, etc.).
 Each scaffolded project also includes `SCAFFOLDING.md`, which should be your
@@ -1005,13 +1025,22 @@ Module exports:
 | `render_pdf_batch(copies, deterministic_hash=None)` | `bytes` |
 | `render_pdf_bindings(bindings, deterministic_hash=None)` | `bytes` |
 | `render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |
+| `render_pdf_reflow_bindings(bindings, deterministic_hash=None)` | `bytes` |
+| `render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |
 
 The compiled lane runs parsing/layout once. `render_pdf_batch` virtualizes identical untagged page
-content. The binding methods instead accept columnar `dict[str, list[str]]` data and emit distinct
+content. The fixed binding methods accept columnar `dict[str, list[str]]` data and emit distinct
 fixed-geometry text overlays per record while sharing static paint. They require exact slot keys,
 equal non-zero column lengths, page-local WinAnsi-compatible text, and an untagged profile; bound
 values do not trigger reflow.
 
+The reflow binding methods use the same exact-column contract but execute the compiled parsed-DOM
+program. `{{slot}}` values are literal text and may reshape, wrap, resize blocks, and change page
+counts. Empty elements can opt into trusted generated markup with
+`data-fb-bind-html="slot"`; those values replace the element's children. One DOM is reused per
+native worker and record output is linked in input order through a bounded queue. See
+[`docs/python-api.md`](docs/python-api.md) for the trust boundary and current limitations.
+
 When `deterministic_hash` is set, engine writes PDF SHA-256 to the provided file path.
 
 `AssetBundle` methods:

{fullbleed-2.2.2 → fullbleed-2.2.4}/README.md

@@ -99,6 +99,24 @@ size-changing records render 200x faster. See
 [`docs/performance-architecture.md`](docs/performance-architecture.md) for the packed vector IR,
 typed-binding, virtual-linker, and shader roadmap.
 
+Fullbleed 2.2.4 adds a third compiler lane for
+size-changing records: `CompiledDocument.render_pdf_reflow_bindings(...)`. It parses and recovers
+the template DOM once and compiles encountered structural flow variants into guarded fixed-point
+display programs. Matching records bind directly into those programs; workers execute pre-shaped
+text/TJ paint slots, cached static PDF page segments, page-local Deflate, and one ordered linker.
+Explicit trusted structural slots use `data-fb-bind-html="slot"`. A value that no compiled variant
+can safely place runs ordinary fixed-point layout once to add another variant.
+
+On the independent 1,000-distinct-record case study, the final ABI3 wheel's 29-sample hot
+direct-file run had a 168.839 ms median: **5,923 records/s and 10,365 pages/s**, with a 12,510
+pages/s best. It produced
+the exact 1,750-page 500/300/150/50 reflow distribution and verified all 24,900 markers. The
+throughput-tuned 6,870,320-byte PDF was deterministic across all samples. With the compact
+compression setting, compiled output was also byte-for-byte identical to ordinary rendering:
+5,298,961 bytes and SHA-256 `bb3c441313a08fb00d3bd15f23a567981f3bbbd550908e3a9fe7a07ca5d7f138`.
+This is a hot compiled-variant result, not a claim for previously unseen structure; the first
+compile-on-demand batch measured 407.521 ms (4,294 pages/s).
+
 ## Install
 
 New to Python or setting up on a fresh machine? Start with `docs/install-non-technical.md`.
@@ -110,7 +128,7 @@ python -m pip install fullbleed
 From a local wheel:
 
 ```bash
-python -m pip install C:\path\to\fullbleed-2.2.2-cp310-abi3-win_amd64.whl
+python -m pip install C:\path\to\fullbleed-2.2.4-cp310-abi3-win_amd64.whl
 ```
 
 From a source checkout with Rust installed, no Python build package is needed:
@@ -161,7 +179,9 @@ vendors `inter` into `vendor/fonts/Inter-Variable.ttf`, writes license notices
 and seeds `assets.lock.json` with pinned hashes.
 The scaffolded `report.py` also runs a component mount smoke validation before
 main render and writes `output/component_mount_validation.json` (fails fast on
-missing glyphs, placement overflow, or CSS miss signals parsed from debug logs).
+missing glyphs, actual pagination overflow, or CSS miss signals). On current engines,
+render-time pagination is authoritative for overflow; conservative JIT placement bounds
+remain the compatibility fallback for older engines.
 Scaffolded components now include `components/primitives.py` with reusable
 layout/content helpers (`Stack`, `Row`, `Text`, table/list helpers, key/value rows, etc.).
 Each scaffolded project also includes `SCAFFOLDING.md`, which should be your
@@ -968,13 +988,22 @@ Module exports:
 | `render_pdf_batch(copies, deterministic_hash=None)` | `bytes` |
 | `render_pdf_bindings(bindings, deterministic_hash=None)` | `bytes` |
 | `render_pdf_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |
+| `render_pdf_reflow_bindings(bindings, deterministic_hash=None)` | `bytes` |
+| `render_pdf_reflow_bindings_to_file(bindings, path, deterministic_hash=None)` | `int` |
 
 The compiled lane runs parsing/layout once. `render_pdf_batch` virtualizes identical untagged page
-content. The binding methods instead accept columnar `dict[str, list[str]]` data and emit distinct
+content. The fixed binding methods accept columnar `dict[str, list[str]]` data and emit distinct
 fixed-geometry text overlays per record while sharing static paint. They require exact slot keys,
 equal non-zero column lengths, page-local WinAnsi-compatible text, and an untagged profile; bound
 values do not trigger reflow.
 
+The reflow binding methods use the same exact-column contract but execute the compiled parsed-DOM
+program. `{{slot}}` values are literal text and may reshape, wrap, resize blocks, and change page
+counts. Empty elements can opt into trusted generated markup with
+`data-fb-bind-html="slot"`; those values replace the element's children. One DOM is reused per
+native worker and record output is linked in input order through a bounded queue. See
+[`docs/python-api.md`](docs/python-api.md) for the trust boundary and current limitations.
+
 When `deterministic_hash` is set, engine writes PDF SHA-256 to the provided file path.
 
 `AssetBundle` methods:

{fullbleed-2.2.2 → fullbleed-2.2.4}/pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["build_backend"]
 
 [project]
 name = "fullbleed"
-version = "2.2.2"
+version = "2.2.4"
 description = "Deterministic static HTML/CSS-to-PDF renderer built in Rust"
 readme = "README.md"
 requires-python = ">=3.10"

{fullbleed-2.2.2 → fullbleed-2.2.4}/python/fullbleed/_abi.py

@@ -161,7 +161,7 @@ class WatermarkSpec(metaclass=_NativeFacadeType):
 
 
 class CompiledDocument(metaclass=_NativeFacadeType):
-    """Immutable fixed-point display document produced by ``PdfEngine.compile_pdf``."""
+    """Compiled fixed-paint and content-reflow programs from ``PdfEngine.compile_pdf``."""
 
     __slots__ = ("_handle",)
 
@@ -219,6 +219,27 @@ class CompiledDocument(metaclass=_NativeFacadeType):
             deterministic_hash,
         )
 
+    def render_pdf_reflow_bindings(self, /, bindings, deterministic_hash=None):
+        """Render columnar text bindings with content-driven layout and pagination."""
+        return _call(
+            self._handle,
+            "CompiledDocument.render_pdf_reflow_bindings",
+            bindings,
+            deterministic_hash,
+        )
+
+    def render_pdf_reflow_bindings_to_file(
+        self, /, bindings, path, deterministic_hash=None
+    ):
+        """Stream a compiled content-reflow batch directly to ``path``."""
+        return _call(
+            self._handle,
+            "CompiledDocument.render_pdf_reflow_bindings_to_file",
+            bindings,
+            path,
+            deterministic_hash,
+        )
+
 
 class PdfEngine(metaclass=_NativeFacadeType):
     __slots__ = ("_handle",)

{fullbleed-2.2.2 → fullbleed-2.2.4}/python/fullbleed/ui/core.py

@@ -885,7 +885,11 @@ def validate_component_mount(
     asset_unresolved_count = int(asset_summary.get("unresolved_count") or 0)
     asset_unsupported_count = int(asset_summary.get("unsupported_count") or 0)
     asset_reference_count = int(asset_summary.get("image_reference_count") or 0)
-    if pagination_overflow_count > overflow_count:
+    # The native pagination trace describes layout overflow directly. Legacy
+    # JIT placement bounds are a fallback for older engines and can be wider
+    # than the painted glyph outlines because glyph runs use conservative
+    # diagnostic padding.
+    if pagination_trace_available:
         overflow_count = pagination_overflow_count
         overflow_samples = pagination_overflow_samples
     if pagination_trace_available:

{fullbleed-2.2.2 → fullbleed-2.2.4}/src/flate_native.rs

@@ -1,11 +1,17 @@
+use std::cell::RefCell;
+use std::sync::OnceLock;
+
 const ADLER_BASE: u32 = 65_521;
 const DEFAULT_ADLER_CHUNK: usize = 1 << 20;
+const ADLER_NMAX: usize = 5_552;
 
 const LZ77_CHUNK_BYTES: usize = 128 * 1024;
 const MIN_MATCH: usize = 3;
 const MAX_MATCH: usize = 258;
 const MAX_DISTANCE: usize = 32 * 1024;
 const MAX_CHAIN_STEPS: usize = 64;
+const DEFAULT_COMPILED_FLOW_CHAIN_STEPS: usize = 4;
+const COMPILED_FLOW_THROUGHPUT_MIN_BYTES: usize = 4 * 1024;
 const HASH_BITS: usize = 15;
 const HASH_SIZE: usize = 1 << HASH_BITS;
 
@@ -41,19 +47,19 @@ impl AdlerPartial {
     }
 
     fn for_bytes(data: &[u8]) -> Self {
-        let mut a: u32 = 1;
-        let mut b: u32 = 0;
-        for &byte in data {
-            a += byte as u32;
-            if a >= ADLER_BASE {
-                a -= ADLER_BASE;
+        let mut a = 1_u64;
+        let mut b = 0_u64;
+        for chunk in data.chunks(ADLER_NMAX) {
+            for &byte in chunk {
+                a += u64::from(byte);
+                b += a;
             }
-            b += a;
-            b %= ADLER_BASE;
+            a %= u64::from(ADLER_BASE);
+            b %= u64::from(ADLER_BASE);
         }
         Self {
-            a,
-            b,
+            a: a as u32,
+            b: b as u32,
             len: data.len(),
         }
     }
@@ -166,87 +172,155 @@ fn hash3(data: &[u8], i: usize) -> usize {
 
 fn match_len(data: &[u8], a: usize, b: usize, max_len: usize) -> usize {
     let mut l = 0usize;
+    while l + 8 <= max_len {
+        let left = u64::from_le_bytes(
+            data[a + l..a + l + 8]
+                .try_into()
+                .expect("eight-byte match window"),
+        );
+        let right = u64::from_le_bytes(
+            data[b + l..b + l + 8]
+                .try_into()
+                .expect("eight-byte match window"),
+        );
+        let difference = left ^ right;
+        if difference != 0 {
+            return l + (difference.trailing_zeros() as usize >> 3);
+        }
+        l += 8;
+    }
     while l < max_len && data[a + l] == data[b + l] {
         l += 1;
     }
     l
 }
 
-fn plan_lz77_chunk(data: &[u8]) -> ChunkPlan {
-    let n = data.len();
-    if n == 0 {
-        return ChunkPlan { tokens: Vec::new() };
+struct Lz77Workspace {
+    head: Vec<i32>,
+    head_epoch: Vec<u32>,
+    prev: Vec<i32>,
+    epoch: u32,
+}
+
+impl Lz77Workspace {
+    fn new() -> Self {
+        Self {
+            head: vec![-1; HASH_SIZE],
+            head_epoch: vec![0; HASH_SIZE],
+            prev: Vec::new(),
+            epoch: 0,
+        }
     }
 
-    let mut head = vec![-1_i32; HASH_SIZE];
-    let mut prev = vec![-1_i32; n];
-    let mut tokens = Vec::with_capacity(n / 2);
+    fn begin_page(&mut self, len: usize) -> u32 {
+        self.epoch = self.epoch.wrapping_add(1);
+        if self.epoch == 0 {
+            self.head_epoch.fill(0);
+            self.epoch = 1;
+        }
+        if self.prev.len() < len {
+            self.prev.resize(len, -1);
+        }
+        self.epoch
+    }
 
-    let mut i = 0usize;
-    while i < n {
-        if i + MIN_MATCH > n {
-            tokens.push(Token::Literal(data[i]));
-            i += 1;
-            continue;
+    fn plan(&mut self, data: &[u8], max_chain_steps: usize) -> ChunkPlan {
+        let n = data.len();
+        if n == 0 {
+            return ChunkPlan { tokens: Vec::new() };
         }
+        let epoch = self.begin_page(n);
+        let mut tokens = Vec::with_capacity(n / 2);
+
+        let mut i = 0usize;
+        while i < n {
+            if i + MIN_MATCH > n {
+                tokens.push(Token::Literal(data[i]));
+                i += 1;
+                continue;
+            }
 
-        let h = hash3(data, i);
-        let mut cand = head[h];
-        prev[i] = cand;
-        head[h] = i as i32;
+            let h = hash3(data, i);
+            let mut cand = if self.head_epoch[h] == epoch {
+                self.head[h]
+            } else {
+                -1
+            };
+            self.prev[i] = cand;
+            self.head[h] = i as i32;
+            self.head_epoch[h] = epoch;
+
+            let mut best_len = 0usize;
+            let mut best_dist = 0usize;
+            let mut steps = 0usize;
+
+            while cand >= 0 && steps < max_chain_steps {
+                let c = cand as usize;
+                let dist = i - c;
+                if dist > MAX_DISTANCE {
+                    break;
+                }
 
-        let mut best_len = 0usize;
-        let mut best_dist = 0usize;
-        let mut steps = 0usize;
+                if data[c] == data[i] && data[c + 1] == data[i + 1] && data[c + 2] == data[i + 2] {
+                    let max_len = MAX_MATCH.min(n - i);
+                    let len = match_len(data, c, i, max_len);
+                    if len >= MIN_MATCH && (len > best_len || (len == best_len && dist < best_dist))
+                    {
+                        best_len = len;
+                        best_dist = dist;
+                        if best_len == MAX_MATCH {
+                            break;
+                        }
+                    }
+                }
 
-        while cand >= 0 && steps < MAX_CHAIN_STEPS {
-            let c = cand as usize;
-            let dist = i - c;
-            if dist > MAX_DISTANCE {
-                break;
+                cand = self.prev[c];
+                steps += 1;
             }
 
-            if data[c] == data[i] && data[c + 1] == data[i + 1] && data[c + 2] == data[i + 2] {
-                let max_len = MAX_MATCH.min(n - i);
-                let len = match_len(data, c, i, max_len);
-                if len >= MIN_MATCH && (len > best_len || (len == best_len && dist < best_dist)) {
-                    best_len = len;
-                    best_dist = dist;
-                    if best_len == MAX_MATCH {
-                        break;
+            if best_len >= MIN_MATCH {
+                tokens.push(Token::Match {
+                    len: best_len as u16,
+                    dist: best_dist as u16,
+                });
+
+                let end = (i + best_len).min(n);
+                let mut j = i + 1;
+                while j < end {
+                    if j + MIN_MATCH <= n {
+                        let hj = hash3(data, j);
+                        self.prev[j] = if self.head_epoch[hj] == epoch {
+                            self.head[hj]
+                        } else {
+                            -1
+                        };
+                        self.head[hj] = j as i32;
+                        self.head_epoch[hj] = epoch;
                     }
+                    j += 1;
                 }
-            }
 
-            cand = prev[c];
-            steps += 1;
-        }
-
-        if best_len >= MIN_MATCH {
-            tokens.push(Token::Match {
-                len: best_len as u16,
-                dist: best_dist as u16,
-            });
-
-            let end = (i + best_len).min(n);
-            let mut j = i + 1;
-            while j < end {
-                if j + MIN_MATCH <= n {
-                    let hj = hash3(data, j);
-                    prev[j] = head[hj];
-                    head[hj] = j as i32;
-                }
-                j += 1;
+                i += best_len;
+            } else {
+                tokens.push(Token::Literal(data[i]));
+                i += 1;
             }
-
-            i += best_len;
-        } else {
-            tokens.push(Token::Literal(data[i]));
-            i += 1;
         }
+
+        ChunkPlan { tokens }
     }
+}
 
-    ChunkPlan { tokens }
+thread_local! {
+    static LZ77_WORKSPACE: RefCell<Lz77Workspace> = RefCell::new(Lz77Workspace::new());
+}
+
+fn plan_lz77_chunk_with_chain(data: &[u8], max_chain_steps: usize) -> ChunkPlan {
+    LZ77_WORKSPACE.with(|workspace| {
+        workspace
+            .borrow_mut()
+            .plan(data, max_chain_steps.clamp(1, MAX_CHAIN_STEPS))
+    })
 }
 
 fn reverse_bits(mut value: u16, len: u8) -> u16 {
@@ -348,10 +422,32 @@ fn estimate_deflate_capacity(input_len: usize) -> usize {
 }
 
 pub(crate) fn zlib_deflate_parallel(data: &[u8]) -> Vec<u8> {
+    zlib_deflate_with_chain(data, MAX_CHAIN_STEPS)
+}
+
+pub(crate) fn zlib_deflate_compiled_flow(data: &[u8]) -> Vec<u8> {
+    static COMPILED_FLOW_CHAIN_STEPS: OnceLock<usize> = OnceLock::new();
+    let steps = *COMPILED_FLOW_CHAIN_STEPS.get_or_init(|| {
+        std::env::var("FULLBLEED_COMPILED_FLOW_DEFLATE_CHAIN")
+            .ok()
+            .and_then(|value| value.parse::<usize>().ok())
+            .unwrap_or(DEFAULT_COMPILED_FLOW_CHAIN_STEPS)
+            .clamp(1, MAX_CHAIN_STEPS)
+    });
+    let steps = if data.len() < COMPILED_FLOW_THROUGHPUT_MIN_BYTES {
+        MAX_CHAIN_STEPS
+    } else {
+        steps
+    };
+    zlib_deflate_with_chain(data, steps)
+}
+
+fn zlib_deflate_with_chain(data: &[u8], max_chain_steps: usize) -> Vec<u8> {
     let ranges = chunk_ranges(data.len(), LZ77_CHUNK_BYTES);
 
-    let plans =
-        crate::parallel::map_ordered(&ranges, |(start, end)| plan_lz77_chunk(&data[*start..*end]));
+    let plans = crate::parallel::map_ordered(&ranges, |(start, end)| {
+        plan_lz77_chunk_with_chain(&data[*start..*end], max_chain_steps)
+    });
 
     let adler = adler32_parallel(data, DEFAULT_ADLER_CHUNK);
 
@@ -812,6 +908,21 @@ mod tests {
         );
     }
 
+    #[test]
+    fn zlib_compiled_flow_chain_levels_roundtrip_deterministically() {
+        let src = b"BT /F1 10 Tf 72 720 Td [(REFLOW-000001)] TJ ET\n".repeat(2_000);
+        for steps in [1, 4, 8, 16, 32, 64] {
+            let a = zlib_deflate_with_chain(&src, steps);
+            let b = zlib_deflate_with_chain(&src, steps);
+            assert_eq!(a, b, "deterministic at {steps} chain steps");
+            assert_eq!(
+                zlib_inflate(&a, src.len()).expect("native inflate"),
+                src,
+                "roundtrip at {steps} chain steps",
+            );
+        }
+    }
+
     #[test]
     fn zlib_lz77_roundtrip_empty() {
         let src: Vec<u8> = Vec::new();