xlsxrb 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9930be8e04f9dee4e380c4789398da0b6a95b0c54d2a157265a2d1ee14340132
-  data.tar.gz: '086f0abccab70ef69d1e885b9f8d0ec69a77e81e3067fa718764c24c0f37a13f'
+  metadata.gz: f865582e17bc03ede4f300f348f6166a666d82cd088f42a501a6518979a7b999
+  data.tar.gz: 25ba8105a6ca0318aa9bb4766a0de59da4818d18d226d212f1ec941fde3082c9
 SHA512:
-  metadata.gz: 2097ccb3e8b3e5344e5d55c459db6b06c298b116074bcc41a06fafa034eda67bf0c46d7eaa58184aebc970812cfa91f68388c4a6b4e7d7069a45114507aa9e83
-  data.tar.gz: d95b39449b15b2eec1415d1ae65e398cc2c006adefd19b54340727fc4ee2135322040a73bf0b3d2b0ca8f6d171153e88b8f64badb53b7fb841e9d7b8a87afd55
+  metadata.gz: 6e35bcdabcff60af9084c9860fcf1838abfb507065a2eabb1004f40f16ab6cf6f7a11d136bbd83e97f46f0e460b906601db1584ef23b00c05076bfc240417baf
+  data.tar.gz: 8d4597dad8fe327f4ad887934a7f2bc18fcd65b606ef265ab38bcef0a0ae2565dc09f9e7f04dd8dc5bf7c3403fadc2a265d3ce074c9fd623489d8f4004065802

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.1.10] - 2026-08-19
+
+### Added
+- **Peer Libraries Ecosystem Guide ([docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md))**: Introduced a respectful overview of the Ruby XLSX ecosystem featuring official self-descriptions, architectural tradeoffs (SST vs. Inline Strings, Streaming vs. In-Memory), and reproducible benchmarks across 9 popular Ruby XLSX gems.
+- **Visual Assets & Screen Previews**:
+  - Embedded interactive WebAssembly Playground live demo preview in `README.md`.
+  - Added real-world Ruby LSP autocompletion and RBS type hint preview in `README.md`.
+  - Created accurate, neutral linear-scale SVG benchmark performance chart.
+- **Enterprise-Grade Test Suite Expansion**:
+  - **ECMA-376 XSD Schema Validation**: Comprehensive XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
+  - **Contract Testing Suite**: Comprehensive parity verification between Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
+  - **Property-Based Testing (PBT)**: Expanded automated random generation tests for Row/Column invariants, styles, and edge cases.
+  - **Visual Regression Testing (VRT)**: Added new visual baselines for table styles, drawing shapes, and pivot tables.
+  - **E2E Interoperability Suite**: Added tests for namespace-prefixed XML streaming, conditional formatting, and table structures.
+
+### Fixed
+- **WebAssembly (ruby.wasm) Compatibility**: Bundled `pp` and `prettyprint` standard libraries in `ruby.wasm` package to resolve REXML LoadError during browser-based evaluation.
+
+### Changed
+- **Streamlined README**: Refactored README from 363 to 175 lines, focusing on core motivation, clean 4-column feature matrix, concise usage examples, and direct links to specialized documentation.
+
 ## [0.1.9] - 2026-08-18
 
 ### Added

data/README.md

@@ -4,83 +4,61 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 ## Motivation
 
-The Ruby ecosystem already has great XLSX libraries. Each is well-designed for its purpose:
-
-| Library                                                    | Read | Write | Model                 | Write String Storage | Rich Formatting | Password Encryption |
-| ---------------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- | :-----------------: |
-| [roo](https://rubygems.org/gems/roo)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) | ❌ |
-| [creek](https://rubygems.org/gems/creek)                   | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) | ❌ |
-| [xsv](https://rubygems.org/gems/xsv)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) | ❌ |
-| [simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader) | ✅ | ❌ | Streaming         | N/A (Read-only)      | ❌ (Plain data & types) | ❌ |
-| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx)         | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) | ❌ |
-| [write_xlsx](https://rubygems.org/gems/write_xlsx)         | ❌   | ✅    | In-Memory             | SST                  | ✅ (Charts, Styles) | ❌ |
-| [xlsxtream](https://rubygems.org/gems/xlsxtream)           | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) | ❌ |
-| [fast_excel](https://rubygems.org/gems/fast_excel)         | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) | ❌ |
-| [rubyXL](https://rubygems.org/gems/rubyXL)                 | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) | ❌ |
-| **[xlsxrb](https://github.com/niku/xlsxrb)**               | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** | ✅ **(Standard & Agile)** |
-
-Each of these libraries makes deliberate tradeoffs, and they do so thoughtfully:
-* **Memory & Execution Model (Streaming vs In-Memory)**: Streaming libraries write or read rows sequentially on-the-fly to maintain a constant, low-memory footprint regardless of row count. In-memory libraries build complete document object trees, offering flexible random access and cell updates at the cost of high RAM usage on large sheets.
-* **String Storage Architecture (SST vs Inline Strings)**:
-  * **SST (Shared String Table)**: De-duplicates strings into a central dictionary (`xl/sharedStrings.xml`), referencing them by numeric IDs in cell entries (`<c t="s"><v>0</v></c>`). This is standard Microsoft Excel behavior, producing significantly smaller raw XML documents (50–100% smaller) and reducing Excel's memory footprint when opening spreadsheets.
-  * **Inline Strings**: Writes text directly into cell payloads (`<c t="inlineStr"><is><t>...</t></is></c>`). Bypassing the dictionary enables blazing-fast raw throughput for simple data exports, but inflates uncompressed XML size and limits advanced formatting (e.g. styling, cell merges, charts).
-
-Traditionally, attempting to build a "complete package" that offers both reading and writing, rich features, high performance, strict compatibility, and comprehensive documentation presents an inherent open-source challenge: the cumulative maintenance overhead often exceeds the capacity of individual human maintainers.
-
-`xlsxrb` is born from a different premise. We believe that Advanced Agentic AI (AI Coders) can help manage this maintenance demand. By utilizing AI agents to automate rigorous E2E testing, visual regression testing, specification compliance checks, and documentation updates, we can reconcile these competing engineering requirements. This allows us to build and continuously maintain a feature-rich, high-performance, and deeply compatible "all-in-one" XLSX library that remains sustainable for the long run.
+The Ruby ecosystem already has great XLSX libraries, each designed for specific tradeoffs:
+
+| Library | Read | Write | Streaming | In-Memory |
+| :--- | :---: | :---: | :---: | :---: |
+| [roo](https://rubygems.org/gems/roo) | ✅ | ❌ | ✅ | ❌ |
+| [creek](https://rubygems.org/gems/creek) | ✅ | ❌ | ✅ | ❌ |
+| [xsv](https://rubygems.org/gems/xsv) | ✅ | ❌ | ✅ | ❌ |
+| [simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader) | ✅ | ❌ | ✅ | ❌ |
+| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx) | ❌ | ✅ | ❌ | ✅ |
+| [write_xlsx](https://rubygems.org/gems/write_xlsx) | ❌ | ✅ | ❌ | ✅ |
+| [xlsxtream](https://rubygems.org/gems/xlsxtream) | ❌ | ✅ | ✅ | ❌ |
+| [fast_excel](https://rubygems.org/gems/fast_excel) | ❌ | ✅ | ✅ | ❌ |
+| [rubyXL](https://rubygems.org/gems/rubyXL) | ✅ | ✅ | ❌ | ✅ |
+| **[xlsxrb](https://github.com/niku/xlsxrb)** | **✅** | **✅** | **✅** | **✅** |
+
+Each of these libraries makes deliberate architectural choices:
+* **Streaming Model**: Writes or reads rows sequentially on-the-fly to maintain a constant $O(1)$, low-memory footprint regardless of dataset size.
+* **In-Memory Model**: Builds a complete document object model, offering flexible random access, cell updates, and document templates at the cost of memory usage on large spreadsheets.
+
+Traditionally, maintaining an all-in-one gem that offers both reading and writing across both streaming and in-memory models, alongside rich OOXML features, high performance, and strict compatibility, presents an inherent open-source challenge: the cumulative maintenance overhead often exceeds the capacity of individual human maintainers.
+
+`xlsxrb` is built on a modern premise: **Advanced Agentic AI (AI Coders) can sustainably handle this maintenance demand.** By utilizing AI agents to automate end-to-end testing, visual regression testing, specification compliance verification, and documentation updates, `xlsxrb` delivers a fast, specification-compliant, and fully-featured XLSX library built for long-term sustainability.
 
 ### Design Principles
 
-- Minimal Dependencies (Zero Core Logic Dependencies): This library avoids heavy third-party XLSX/XML/ZIP gems, building all core parsing and writing features purely on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.). The only runtime dependency is `opentelemetry-api`, which provides zero-overhead observability. If you do not configure an OpenTelemetry SDK in your application, it acts as a lightweight no-op, keeping the runtime footprint extremely small.
-- Streaming Support: Both reading and writing are designed to handle large files efficiently by streaming data, keeping memory usage low and predictable.
-- Memory-Efficient XML Parsing: For reading operations, the library uses a custom byte-level streaming parser for worksheet rows (with targeted SAX parsing where appropriate) instead of DOM-based parsing, so entire XML documents are never loaded into memory. This enables true streaming capability for large spreadsheets.
-- Strict Microsoft Excel & OpenXML Interoperability: It is designed to closely follow the Microsoft Office implementation of the ISO 29500 standard. We ensure absolute bidirectional compatibility (both reading and writing) with Microsoft Excel by continuously validating files against the official Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
-- AI-Agent Assisted Maintenance (Managing the Engineering Tradeoff): Building a library that is specification-compliant, rich in features, highly compatible, well-documented, and extremely fast typically presents a substantial maintenance challenge. `xlsxrb` addresses this inherent constraint by leveraging Advanced Agentic AI (AI Coders) to automate testing, feature expansion, and compatibility verification. This AI-assisted development process supports the project's long-term sustainability and high software quality.
-- Modern Ruby 4.0+: Built for the future with Ruby 4.0 or higher.
+- **Minimal Dependencies**: Zero core logic dependencies. Built purely on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.). The only runtime dependency is `opentelemetry-api` (zero-overhead no-op when unconfigured).
+- **Streaming Support**: True $O(1)$ constant memory streaming for both reading and writing massive spreadsheets.
+- **Strict OpenXML Interoperability**: Fully compliant with ISO/IEC 29500 (ECMA-376) and validated continuously against the official Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
+- **AI-Assisted Sustainability**: Leveraging AI coding agents for automated quality assurance, E2E validation, and continuous feature expansion.
+- **Modern Ruby**: Built for Ruby 4.0 or higher.
 
 ## Installation
 
 ```bash
 bundle add xlsxrb
+# Or without Bundler: gem install xlsxrb
 ```
 
-Or without Bundler:
-
-```bash
-gem install xlsxrb
-```
-
-On Ruby 4+, some components used by `xlsxrb` and its test suite are shipped as bundled gems rather than built-in default libraries. When using Bundler, those bundled gems are resolved and installed in the usual way.
-
 ## Interactive Playground (WebAssembly)
 
-You can try `xlsxrb` directly in your browser without installing anything!
+Try `xlsxrb` directly in your browser without installing anything!
 
 [👉 Try the Live Demo / Interactive Playground](https://niku.github.io/xlsxrb/docs/visual/VisualGallery_md.html)
 
-We have integrated an interactive WebAssembly-powered playground into our RDoc documentation. You can edit the code examples, run them in the browser sandbox, and download the generated `.xlsx` spreadsheets immediately.
+<p align="center">
+  <img src="docs/assets/playground_preview.png" width="100%" alt="Interactive WebAssembly Playground with Live LibreOffice Preview"/>
+</p>
 
-To launch the playground locally:
-1. Generate the WebAssembly bundle and interactive RDoc:
-   ```bash
-   bundle exec rake doc
-   ```
-2. Start the local preview server:
-   ```bash
-   bundle exec rake doc:preview
-   ```
-3. Open [http://localhost:8000](http://localhost:8000) in your browser, hover over any code block, and click the "Live Preview" or "Download XLSX" buttons!
+You can also browse 50+ rendered visual examples across all features in the [Visual Examples Gallery](docs/visual/VisualGallery.md).
 
 ## Usage
 
-`xlsxrb` supports both low-memory Streaming (recommended for large files) and full In-Memory document manipulation (for random-access cell modifications or updating existing sheets).
-
-For visual demonstrations of various features, check the [Visual Examples Gallery](docs/visual/VisualGallery.md).
+### Quick Start: Streaming (Recommended for Large Files)
 
-### Quick Start: Streaming (Recommended)
-
-#### Streaming Write
-Generate large files efficiently with $O(1)$ constant memory by writing data directly to the stream:
+#### Streaming Write ($O(1)$ Memory)
 ```ruby
 require "xlsxrb"
 
@@ -93,12 +71,10 @@ Xlsxrb.write("large_output.xlsx") do |writer|
 end
 ```
 
-#### Streaming Read
-Read rows and cells lazily one at a time with $O(1)$ constant memory (even for wide sheets with thousands of columns):
+#### Streaming Read ($O(1)$ Memory)
 ```ruby
 require "xlsxrb"
 
-# Stream row-by-row and cell-by-cell (O(1) memory)
 Xlsxrb.read("large_file.xlsx") do |sheet|
   sheet.each_row do |row|
     row.each_cell do |cell|
@@ -106,39 +82,14 @@ Xlsxrb.read("large_file.xlsx") do |sheet|
     end
   end
 end
-
-# Or stream all cells across the sheet directly
-Xlsxrb.read("large_file.xlsx") do |sheet|
-  sheet.each_cell do |cell|
-    puts "#{cell.ref} = #{cell.value}"
-  end
-end
 ```
 
-### Ruby-Idiomatic Core APIs
-
-`xlsxrb` provides clean, standard Ruby interfaces (`Enumerable`, `Row#to_a`, `sheet["A1"]`) that feel natural to every Ruby developer without learning complex library-specific APIs:
+### In-Memory Building & Modifying
 
-#### Reading Spreadsheets
+#### Creating & Exporting (Rails / Mailers)
 ```ruby
 require "xlsxrb"
 
-# 1. Read from file path, IO, or raw binary string (O(1) constant memory streaming)
-workbook = Xlsxrb.read("data.xlsx")
-sheet = workbook.sheets.first
-
-# 2. Extract sheet data into 2D array of values via standard Enumerable
-matrix = sheet.map(&:to_a) # => [["Name", "Score"], ["Alice", 100], ["Bob", 95]]
-
-# 3. Explicitly load into memory for coordinate random access (e.g. sheet["A1"])
-doc_sheet = sheet.load
-doc_sheet["A1"]         # => #<Xlsxrb::Elements::Cell value="Name" ...>
-doc_sheet["A1"].value   # => "Name"
-```
-
-#### Writing & In-Memory Export (Rails & Mailers)
-```ruby
-# Build workbook
 wb = Xlsxrb.build do |b|
   b.sheet("Report") do |s|
     s.row(["Metric", "Value"])
@@ -146,217 +97,84 @@ wb = Xlsxrb.build do |b|
   end
 end
 
-# Save directly to file:
+# Save to file or get binary string for Rails send_data
 Xlsxrb.write("report.xlsx", wb)
-
-# Or export to binary string (ideal for Rails send_data & ActionMailer):
 binary_data = Xlsxrb.write(wb)
 ```
 
-### In-Memory Building & Modifying
-
-`xlsxrb` provides a powerful, immutable-by-default API for modifying existing Excel files or building templates in-memory. 
-
 #### Modifying an Existing File
-You can update specific cells or sheets using the functional `Xlsxrb.modify` API, which yields the parsed `Elements::Workbook`.
-
 ```ruby
 require "xlsxrb"
 
-# Create a template.xlsx for this example
-Xlsxrb.build { |builder| builder.sheet("Invoice") }.write("template.xlsx")
-
 Xlsxrb.modify("template.xlsx", "output.xlsx") do |workbook|
   workbook.update_sheet("Invoice") do |sheet|
-    # Update specific cells (returns updated sheet)
-    sheet = sheet.update_cell("C4", value: "INV-10042")
-    sheet = sheet.update_cell("C5", value: Date.today)
-    
-    # Or append new rows
-    sheet.with(rows: sheet.rows + [
-      Xlsxrb::Elements::Row.new(index: sheet.rows.size, cells: [])
-    ])
+    sheet.update_cell("C4", value: "INV-10042")
+         .update_cell("C5", value: Date.today)
   end
 end
 ```
 
-#### Hash & Range Styling (Syntactic Sugar)
-You can directly apply inline styles or use Ranges for multiple columns without boilerplate:
+### Password Protection & Encryption ([MS-OFFCRYPTO])
 
-```ruby
-Xlsxrb.build do |builder|
-  # Use [] accessor for sheets
-  builder["Report"].row(
-    ["ID", "Name", "Score", "Rank"],
-    # Apply 'header' style to first two columns, and bold inline style to the third
-    styles: { 0..1 => "header", 2 => { font: { bold: true, color: "red" } } }
-  )
-  
-  # Set multiple column widths at once using Ranges
-  builder["Report"].column("A".."D", width: 15.0)
-end
-```
-
-### Password Protection & Document Encryption ([MS-OFFCRYPTO])
-
-`xlsxrb` natively supports reading and writing password-protected Excel files with zero external C-extension dependencies, fully compliant with **[MS-OFFCRYPTO]** (Standard Encryption & Agile Encryption) and **[MS-CFB]** (Compound File Binary Format):
+Natively supports reading and writing encrypted XLSX files (Standard & Agile Encryption) with zero external C-extensions:
 
-#### Writing Password-Protected Spreadsheets
 ```ruby
-# 1. Streaming write with password protection
-Xlsxrb.write("confidential.xlsx", password: "SecretPassword123") do |writer|
-  writer.sheet("Financials") do |sheet|
-    sheet.row(["Account", "Balance"])
-    sheet.row(["Assets", 5_000_000])
-  end
-end
+require "xlsxrb"
 
-# 2. In-Memory write with password protection
-wb = Xlsxrb.build do |b|
-  b.sheet("Private") { |s| s.row(["Confidential", 100]) }
+# Write password-protected file
+Xlsxrb.write("confidential.xlsx", password: "SecretPassword123") do |writer|
+  writer.sheet("Financials") { |sheet| sheet.row(["Assets", 5_000_000]) }
 end
-encrypted_binary = Xlsxrb.write(wb, password: "SecretPassword123")
-```
 
-#### Reading Password-Protected Spreadsheets
-```ruby
-# 1. Read directly with password (O(1) constant memory streaming)
+# Read password-protected file
 Xlsxrb.read("confidential.xlsx", password: "SecretPassword123") do |sheet|
   sheet.each_row { |row| puts row.cells.map(&:value) }
 end
-
-# 2. In-Memory load with password
-workbook = Xlsxrb.read("confidential.xlsx", password: "SecretPassword123").load
-puts workbook.sheets.first["A1"].value
-
-# Attempting to read without password or with invalid password raises clear exceptions:
-# Xlsxrb::EncryptedFileError   -> Missing password
-# Xlsxrb::InvalidPasswordError -> Incorrect password
 ```
 
 ### IDE Autocompletion & Ruby LSP Support
 
-`xlsxrb` bundles a native **Ruby LSP Add-on** (`RubyLsp::Xlsxrb::Addon`) and full **RBS signatures**, enabling zero-configuration method autocompletion and rich Markdown documentation in VS Code and other LSP-enabled editors.
+Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-configuration method autocompletion and hover documentation in VS Code and other editors:
 
-Whether you use standard descriptive block variable names (`|stream_writer|`, `|sheet|`, `|workbook|`) or short names (`|wb|`, `|s|`), your editor will automatically provide complete method suggestions and parameter hints:
-
-```ruby
-Xlsxrb.write("output.xlsx") do |writer| # or |wb|
-  writer.sheet("Data") do |sheet|      # or |s|
-    sheet.row(["Product", "Price"], styles: :bold)
-    sheet.auto_filter("A1:B100")
-  end
-end
-```
+<p align="center">
+  <img src="docs/assets/lsp_autocompletion.png" width="100%" alt="Ruby LSP Autocompletion & Type Signature Hints in VS Code"/>
+</p>
 
 ## Feature Support & ECMA-376 Compliance
 
-`xlsxrb` is designed for full interoperability and strict compliance with the ECMA-376 (Office Open XML) Transitional specification. It supports nearly all major spreadsheet features required for business reports:
-
-* Cells & Layout: Formulas, Hyperlinks, Merge Cells, Freeze & Split Panes, Page Setup (margins, headers/footers, scaling, gridlines).
-* Data & Controls: Auto Filters, Data Validations (dropdowns, range limits), Sheet Protection.
-* Formatting & Styling: Rich Text, Cell Tables, Conditional Formatting (color scales, data bars, icon sets).
-* Graphics & Charts: Embedded Images, Shapes & Drawings, Sparklines, Charts (Line, Bar, Pie, Area, Radar, Scatter).
-* Workbook Level: Defined Names, Print Areas, Workbook Protection, and Document Metadata (core, app, custom properties).
+`xlsxrb` supports nearly all major business spreadsheet features:
+* **Layout & Structure**: Formulas, Hyperlinks, Merge Cells, Freeze/Split Panes, Page Setup, Auto Filters, Data Validations, Sheet/Workbook Protection.
+* **Styling & Media**: Rich Text, Cell Styles & Fills, Conditional Formatting (color scales, data bars), Embedded Images, Charts (Line, Bar, Pie, Radar, Scatter).
 
-For detailed specification references and policies, see [SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
+For full details, see [docs/SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
 
 ## Benchmarks
 
-The following benchmarks measure the time, peak memory, and GC count required to process a 1,000,000 cells (100,000 rows × 10 columns) spreadsheet across popular Ruby Excel libraries. Each test is executed across 3 independent runs in isolated subprocesses; median values are reported along with the mean execution time.
-
-### Write Performance (1,000,000 cells)
-
-| Library                | Model       | Write String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
-| ---------------------- | ----------- | -------------------- | ------------- | ----------- | ----------- | -------- |
-| xlsxtream 3.1.0        | Streaming   | Inline String        | 1.19 s        | 1.20 s      | 18.2 MB     | 1072.0   |
-| xlsxrb (Streaming)     | Streaming   | SST (Shared)         | 1.73 s        | 1.65 s      | 94.4 MB     | 39.0     |
-| fast_excel 0.5.0 (C)   | Streaming   | SST (Shared)         | 1.89 s        | 1.89 s      | 148.2 MB    | 245.0    |
-| xlsxrb (In-Memory)     | In-Memory   | SST (Shared)         | 3.84 s        | 3.83 s      | 278.3 MB    | 32.0     |
-| write_xlsx 1.15.0      | In-Memory   | SST (Shared)         | 4.32 s        | 4.34 s      | 201.2 MB    | 33.0     |
-| caxlsx 4.5.0           | In-Memory   | Inline String        | 5.15 s        | 5.12 s      | 188.6 MB    | 23.0     |
-| rubyXL 3.4.38          | In-Memory   | Inline String        | 38.81 s       | 37.82 s     | 2186.8 MB   | 103.0    |
-
-> **Note**: All libraries are evaluated in their **default, out-of-the-box configuration**. Under the same Microsoft Excel-standard Shared String Table (SST) architecture, Pure Ruby `xlsxrb` (Streaming: 1.73s, In-Memory: 3.84s) writes 1,000,000 cells faster than the C-extension `fast_excel` (1.89s) and in-memory gems like `write_xlsx` (4.32s) and `caxlsx` (5.15s).
+Benchmark processing 1,000,000 cells (100,000 rows × 10 cols) across popular Ruby gems:
 
-### Read Performance (1,000,000 cells)
+<p align="center">
+  <img src="docs/assets/benchmark_results.svg" width="100%" alt="Ruby XLSX Performance Benchmarks"/>
+</p>
 
-| Library                  | Model       | Time (Median) | Time (Mean) | Peak Memory | GC Count |
-| ------------------------ | ----------- | ------------- | ----------- | ----------- | -------- |
-| xlsxrb (Streaming)       | Streaming   | 3.17 s        | 3.22 s      | 91.4 MB     | 43.0     |
-| simple_xlsx_reader 5.1.0 | Streaming   | 4.48 s        | 4.45 s      | 38.5 MB     | 1669.0   |
-| xlsxrb (In-Memory)       | In-Memory   | 5.71 s        | 5.89 s      | 224.8 MB    | 63.0     |
-| creek 2.6.3              | Streaming   | 8.14 s        | 8.02 s      | 834.6 MB    | 477.0    |
-| xsv 1.4.1                | Streaming   | 14.61 s       | 14.50 s     | 76.1 MB     | 2224.0   |
-| roo 3.0.0                | Streaming   | 15.69 s       | 13.36 s     | 119.7 MB    | 441.0    |
-| rubyXL 3.4.38            | In-Memory   | 37.13 s       | 40.35 s     | 2537.6 MB   | 146.0    |
+For detailed metrics (peak memory, GC count, mean/median times) and architectural tradeoffs (SST vs. Inline Strings), see [docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md).
 
-### Running the Benchmarks Locally (Reproducibility)
-
-The benchmark suite leverages [`bundler/inline`](https://bundler.io/v2.5/guides/bundler_in_a_single_file_ruby_script.html) to automatically manage and download all peer ecosystem gems without modifying the project's core `Gemfile` or requiring manual global `gem install` steps. Each library is executed in an isolated subprocess (`Bundler.with_unbundled_env`) across multiple runs with standard business dataset rows (integers, strings, floats, booleans, dates) to ensure clean memory and GC measurements without cross-contamination.
-
-To run the complete benchmark suite:
-```bash
-ruby benchmark.rb 100000 10
-```
+To reproduce locally: `ruby benchmark.rb 100000 10`
 
-## Security (Protection against CSV/Excel Injection)
+## Quality Assurance & Testing
 
-Unlike CSV files which lack type definitions and force Excel to guess types (often inadvertently executing strings starting with `=`), `.xlsx` files generated by `xlsxrb` are strictly typed.
+Backed by an enterprise-grade QA architecture to guarantee absolute reliability:
+* **Official Microsoft Open XML SDK Validation**: Validates generated OOXML structures against Microsoft's official SDK.
+* **Visual Regression Testing (VRT)**: Headless LibreOffice Calc pixel-by-pixel rendering checks.
+* **Contract & Round-Trip Tests**: Verifies parity between Streaming and In-Memory APIs and round-trip read/write accuracy.
+* **Security & DoS Protection**: Formula injection mitigation and ZIP bomb protection.
 
-When you pass a Ruby `String` to `xlsxrb`, it explicitly writes it as a `String` (`t="s"`) into the OOXML file. Therefore, **even if a string starts with `=`, Excel will never evaluate it as a formula**. To write a formula, you must explicitly use `Xlsxrb::Elements::Formula.new`. This design completely mitigates CSV/Formula Injection vulnerabilities by default without requiring additional sanitization.
+For full architectural details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md).
 
-### External Link Updates (`update_links`)
+## Development & Contributing
 
-As an extra layer of "defense in depth", `xlsxrb` configures the workbook to **never automatically update external links** when opened (`updateLinks="never"`). This is intentionally set to `never` by default to prevent Excel from silently reaching out to external resources or executing DDE (Dynamic Data Exchange) links, which is a known vector for malware.
-
-If you absolutely need external links to update automatically, you can explicitly override this (though **it is highly discouraged due to security risks**):
-
-```ruby
-Xlsxrb.write("file.xlsx") do |wb|
-  # WARNING: Enabling this can expose users to malicious external reference vulnerabilities!
-  wb.workbook_property(:update_links, "always") 
-  # ...
-end
-```
-
-## Testing & Quality Assurance
-
-To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a highly rigorous, enterprise-grade Quality Assurance (QA) and testing architecture.
-
-### Multi-Tier Testing Strategy
-* **Round-Trip Testing**: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
-* **Contract Consistency**: Ensures semantic output consistency between the Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
-* **Property-Based Testing (PBT)**: Automatically generates random data to catch edge cases (e.g., huge numbers, special characters) preventing unexpected crashes.
-* **Concurrency Validation**: Thread and Ractor safety checks to guarantee no global variable pollution during parallel execution.
-* **Security & DoS Protection**: Hardened against malicious files, including memory exhaustion (ZIP Bombs) and infinite parsing loops.
-
-### Strict Interoperability & Rendering
-* **Official Open XML SDK Validation (E2E)**: Every generated spreadsheet is structurally validated against the official Microsoft Open XML SDK to prevent file corruption warnings in Microsoft Excel.
-* **Visual Regression Testing (VRT)**: Spreadsheets are rendered via a headless LibreOffice Calc engine and compared pixel-by-pixel against visual baselines to catch subtle rendering regressions.
-
-### Performance & Types
-* **Continuous Performance & Memory Validation**: Memory retention and processing throughput are profiled in CI on large datasets to prevent regressions and OOM leaks.
-* **Runtime Type Validation**: Strong dynamic typing using `RBS::Test` to ensure the library's types are perfectly sound at runtime.
-
-For a comprehensive breakdown of our QA matrix, see [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md). For details on running tests locally, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
-
-## Development
-
-We welcome contributions! The project is configured with a ready-to-use Dev Container to streamline local environment setup.
-
-For contribution guidelines, E2E testing policies, and the step-by-step development workflow (including how to run the Dev Container from your terminal), please refer to [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/niku/xlsxrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for local setup (Dev Container support), testing workflows, and contribution guidelines.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
-
-Everyone interacting in the Xlsxrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -295,7 +295,8 @@ task :wasm do
   # B. Copy necessary standard libraries dynamically from host's $LOAD_PATH
   stdlib_files = [
     "date.rb", "delegate.rb", "forwardable.rb", "securerandom.rb",
-    "random/formatter.rb", "set.rb", "tempfile.rb", "tmpdir.rb", "fileutils.rb"
+    "random/formatter.rb", "set.rb", "tempfile.rb", "tmpdir.rb", "fileutils.rb",
+    "pp.rb", "prettyprint.rb"
   ]
   stdlib_files.each do |name|
     path = $LOAD_PATH.find { |p| File.exist?(File.join(p, name)) }

data/docs/PEER_LIBRARIES.md

@@ -0,0 +1,121 @@
+# Ruby XLSX Ecosystem & Peer Libraries
+
+The Ruby ecosystem is fortunate to have a rich set of mature, well-engineered XLSX libraries. Each library represents deliberate architectural choices tailored for specific problem spaces.
+
+This document provides a respectful overview of the peer libraries in the Ruby ecosystem, explains the underlying engineering tradeoffs (such as Streaming vs. In-Memory and Shared String Tables vs. Inline Strings), and shares comprehensive benchmark measurements.
+
+---
+
+## The Peer Libraries
+
+| Library | I/O | Official Self-Description / Focus | Best Fit (In Our View) |
+| :--- | :---: | :--- | :--- |
+| **[roo](https://rubygems.org/gems/roo)** | `R` | *"Roo can access the contents of various spreadsheet files (Excelx, LibreOffice, OpenOffice, CSV)."* | Unified interface for reading across diverse spreadsheet formats. |
+| **[creek](https://rubygems.org/gems/creek)** | `R` | *"A Ruby gem that streams and parses large Excel (xlsx and xlsm) files fast and efficiently."* | Streaming large spreadsheet uploads row-by-row with lightweight SAX parsing. |
+| **[xsv](https://rubygems.org/gems/xsv)** | `R` | *"A fast and lightweight xlsx parser that provides nothing a CSV parser wouldn't."* | High-speed, CSV-like tabular data ingestion without styling overhead. |
+| **[simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader)** | `R` | *"Read xlsx data the Ruby way"* — parses sheets into Ruby primitives with low memory. | Memory-conscious tabular data extraction directly into Ruby types. |
+| **[caxlsx / axlsx](https://rubygems.org/gems/caxlsx)** | `W` | *"Excel OOXML (xlsx) with charts, styles, images and autowidth columns"* with full schema validation. | Generating rich, styled business reports with charts, images, and visual design. |
+| **[write_xlsx](https://rubygems.org/gems/write_xlsx)** | `W` | Pure Ruby port of Perl's `Excel::Writer::XLSX` to create files in modern Excel 2007+ format. | Creating complex spreadsheets requiring exact Excel feature parity. |
+| **[xlsxtream](https://rubygems.org/gems/xlsxtream)** | `W` | *"A streaming XLSX spreadsheet writer"* allowing very efficient writing of CSV-style data. | Ultra-fast, low-memory streaming exports of massive tabular datasets. |
+| **[fast_excel](https://rubygems.org/gems/fast_excel)** | `W` | *"Ultra Fast Excel Writer"* — C-extension wrapper for `libxlsxwriter` with constant memory mode. | Maximum-throughput spreadsheet generation when C-extensions are available. |
+| **[rubyXL](https://rubygems.org/gems/rubyXL)** | `RW` | *"Allows the parsing, creation, and manipulation of Microsoft Excel (.xlsx/.xlsm) Documents."* | Full document DOM inspection, in-memory cell modification, and template editing. |
+| **[xlsxrb](https://github.com/niku/xlsxrb)** | `RW` | Pure Ruby library unifying streaming read/write ($O(1)$ memory) and in-memory manipulation with native encryption. | Unified reading, writing, template modification, and password encryption in pure Ruby. |
+
+
+---
+
+## Architectural Tradeoffs
+
+Spreadsheet libraries must balance multiple competing dimensions: memory consumption, execution speed, formatting capabilities, and strict specification compliance.
+
+### 1. Memory & Execution Model: Streaming vs. In-Memory
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Execution Models                       │
+├──────────────────────────────┬──────────────────────────────┤
+│       Streaming Model        │       In-Memory Model        │
+├──────────────────────────────┼──────────────────────────────┤
+│ • Processes rows on-the-fly  │ • Builds complete DOM tree   │
+│ • O(1) constant RAM footprint│ • Enables random cell access │
+│ • Cannot seek backward       │ • High RAM on large datasets │
+│ • Ideal for batch exports/ETL│ • Ideal for templates/edits  │
+└──────────────────────────────┴──────────────────────────────┘
+```
+
+* **Streaming Model** (`xlsxrb`, `xlsxtream`, `simple_xlsx_reader`, `roo`, `creek`, `xsv`):
+  Rows and cells are processed sequentially and flushed/discarded immediately. This keeps memory usage completely flat and predictable, regardless of whether the file has 10 rows or 1,000,000 rows. However, random access (e.g., modifying `cell("A1")` after writing row 100) is not possible.
+* **In-Memory Model** (`xlsxrb`, `caxlsx`, `write_xlsx`, `rubyXL`):
+  The entire workbook structure is parsed into Ruby objects, providing complete flexibility to inspect, modify, insert, or reorder cells and worksheets. The tradeoff is that memory consumption scales with the number of cells.
+
+---
+
+### 2. String Storage Architecture: Shared String Table (SST) vs. Inline Strings
+
+The OpenXML (ECMA-376) specification defines two ways to store text in cells:
+
+```xml
+<!-- 1. Shared String Table (SST): Deduplicated dictionary reference -->
+<c r="A1" t="s"><v>0</v></c>
+
+<!-- 2. Inline String: Raw text payload inside the cell -->
+<c r="A1" t="inlineStr"><is><t>Hello World</t></is></c>
+```
+
+#### Shared String Table (SST)
+* **How it works**: Strings across all worksheets are collected into a single central dictionary (`xl/sharedStrings.xml`). Cells only store numeric integer IDs pointing to dictionary entries.
+* **Strengths**:
+  * **Smaller file footprint**: Deduplication significantly reduces the uncompressed XML size (typically 50% to 80% smaller for business datasets with repetitive categories, statuses, dates, and labels).
+  * **Standard Microsoft Excel behavior**: Excel defaults to SST. Opening SST-based spreadsheets in Excel consumes less memory and renders faster.
+  * **Rich Text & Shared Styles**: Supports rich text formatting within strings.
+* **Tradeoff**:
+  * Writing requires managing a string table dictionary or making a multi-pass serialization, adding slight CPU overhead during generation.
+
+#### Inline Strings
+* **How it works**: Text is written directly into each `<c>` element (`<is><t>...</t></is>`) as the stream proceeds.
+* **Strengths**:
+  * **Raw Throughput**: Bypassing string deduplication allows immediate row-by-row flushing with minimal CPU overhead (as demonstrated by `xlsxtream`).
+* **Tradeoff**:
+  * Produces significantly larger raw XML files when strings repeat, and some third-party spreadsheet viewers or legacy tools have limited support for inline strings compared to SST.
+
+---
+
+## Detailed Benchmark Results
+
+The following benchmarks evaluate processing **1,000,000 cells** (100,000 rows × 10 columns) containing standard business data (integers, strings, floats, booleans, and dates) across 3 isolated subprocess runs.
+
+### Write Performance (1,000,000 cells)
+
+| Library | Version | Model | String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **xlsxtream** | 3.1.0 | Streaming | Inline String | **1.19 s** | 1.20 s | **18.2 MB** | 1072.0 |
+| **xlsxrb (Streaming)** | - | Streaming | SST (Shared) | **1.73 s** | 1.65 s | 94.4 MB | 39.0 |
+| **fast_excel** | 0.5.0 | Streaming | SST (Shared) | 1.89 s | 1.89 s | 148.2 MB | 245.0 |
+| **xlsxrb (In-Memory)** | - | In-Memory | SST (Shared) | 3.84 s | 3.83 s | 278.3 MB | 32.0 |
+| **write_xlsx** | 1.15.0 | In-Memory | SST (Shared) | 4.32 s | 4.34 s | 201.2 MB | 33.0 |
+| **caxlsx** | 4.5.0 | In-Memory | Inline String | 5.15 s | 5.12 s | 188.6 MB | 23.0 |
+| **rubyXL** | 3.4.38 | In-Memory | Inline String | 38.81 s | 37.82 s | 2186.8 MB | 103.0 |
+
+### Read Performance (1,000,000 cells)
+
+| Library | Version | Model | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **xlsxrb (Streaming)** | - | Streaming | **3.17 s** | 3.22 s | 91.4 MB | 43.0 |
+| **simple_xlsx_reader** | 5.1.0 | Streaming | 4.48 s | 4.45 s | **38.5 MB** | 1669.0 |
+| **xlsxrb (In-Memory)** | - | In-Memory | 5.71 s | 5.89 s | 224.8 MB | 63.0 |
+| **creek** | 2.6.3 | Streaming | 8.14 s | 8.02 s | 834.6 MB | 477.0 |
+| **xsv** | 1.4.1 | Streaming | 14.61 s | 14.50 s | 76.1 MB | 2224.0 |
+| **roo** | 3.0.0 | Streaming | 15.69 s | 13.36 s | 119.7 MB | 441.0 |
+| **rubyXL** | 3.4.38 | In-Memory | 37.13 s | 40.35 s | 2537.6 MB | 146.0 |
+
+---
+
+## Reproducing Benchmarks Locally
+
+The benchmark suite leverages [`bundler/inline`](https://bundler.io/v2.5/guides/bundler_in_a_single_file_ruby_script.html) to run each library in an isolated subprocess (`Bundler.with_unbundled_env`), eliminating cross-gem pollution and ensuring accurate memory measurements.
+
+To run the suite on your machine:
+
+```bash
+ruby benchmark.rb 100000 10
+```