xlsxrb 0.1.8 → 0.1.10

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
+```

data/docs/QUALITY_ASSURANCE.md

@@ -14,13 +14,12 @@ Below is an overview of the inspection mechanisms, when they run, the quality at
 | **Dependabot** | `.github/dependabot.yml` | - | - | ⭕ | Currency / Maintenance | Repository Monitoring | Outdated dependencies or CI actions. |
 | **Unit & Contract Tests** | `rake test:unit test:contract` | ⭕ | ⭕ | - | Accuracy / Functional Reqs | Dynamic Analysis (Assertions) | Method specification violations, unexpected return values, edge-case failures. |
 | **Runtime Type Validation (RBS::Test)** | `rake test:rbs` | △ (Opt-in) | ⭕ | - | Type Safety (Dynamic) | Dynamic Analysis (Runtime Hooks) | Type errors slipping past static checks, divergence between RBS docs and implementation. |
-| **Property-Based Testing (PBT)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
-
+| **Property-Based Testing (PBT)** | `rake test:pbt` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
 | **Security Validation (DoS Protection)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Availability / Safety | Dynamic Analysis (Malicious Input) | Memory/disk exhaustion from ZIP bombs, infinite parsing loops from malformed files. |
 | **Concurrency Validation (Thread/Ractor)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Thread Safety | Dynamic Analysis (Parallel Execution) | Global variable pollution, data mixing during concurrent request processing. |
 | **XSD Schema Validation** | Included in `rake test:unit` | ⭕ | ⭕ | - | Compatibility / Compliance | Structural Validation | "We found a problem with some content in it" errors when opening in Excel. |
 | **E2E Interoperability Tests** | `rake test:e2e` | △ (Opt-in) | ⭕ | - | Compatibility (Real-world) | 3rd-party SDK Execution | Structural defects so severe that the official .NET SDK cannot read them. |
-| **Load / Stress Testing** | Action: `benchmark.yml` | - | ⭕ | - | Performance / Stability | Massive Data Generation (e.g., 10k+ rows) | Out of Memory (OOM) crashes or extreme delays when processing large datasets. |
-| **Memory & Speed Benchmark** | Action: `benchmark.yml` | - | ⭕ | - | Performance | Continuous Profiling | Memory leaks, severe performance degradation due to inefficient loop additions. |
+| **Memory & Performance Tests** | `rake test:perf` / Action: `performance.yml` | ⭕ | ⭕ | - | Performance / Stability | Continuous Profiling (10k+ rows) | Out of Memory (OOM) leaks or unbounded memory retention in streaming mode. |
+| **Ecosystem Benchmarks** | `ruby benchmark.rb` | ⭕ | - | - | Performance Comparison | Multi-Gem Isolated Profiling (1M cells) | Throughput and allocation comparison against competing libraries. |
 | **Visual Regression Testing (VRT)** | `rake test:visual` | - | ⭕ | - | Visual Accuracy (UI/UX) | Headless Rendering / Pixel Diff | Visual bugs like "cell background colors dropping" or "chart layouts breaking" after code changes. |
 

data/docs/SPEC_SOURCES.md

@@ -22,8 +22,11 @@ To address gaps between the official ECMA standard and actual implementations in
    - **Role:** Identifies how Excel actually reads/writes files, including deviations and compatibility behaviors.
    - **Referenced Version:** July 2024 / Version 12.0 (or current release).
 3. **[[MS-OFFCRYPTO]: Office Document Cryptography Structure](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-offcrypto/)**
-   - **Role:** Provides details on encryption, passwords, and hashing algorithms used for document/sheet protection.
+   - **Role:** Provides details on encryption, passwords, and hashing algorithms used for document/sheet protection (Agile Encryption and Standard Encryption).
    - **Referenced Version:** July 2024 / Version 12.0 (or current release).
+4. **[[MS-CFB]: Compound File Binary File Format](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/)**
+   - **Role:** Container format (OLE structured storage) wrapping encrypted Office documents (`EncryptionInfo` and `EncryptedPackage` streams).
+   - **Referenced Version:** July 2024 / Version 14.0 (or current release).
 
 ### ISO/IEC 29500 Note
 ISO/IEC 29500 is contents-wise equivalent to ECMA-376. However, ISO/IEC 29500 requires paid purchase in general, whereas ECMA-376 is freely available. Therefore, we primarily cite ECMA-376 sections.
@@ -40,3 +43,6 @@ When implementing features or fixing bugs that depend on specific behaviors defi
 | Shared Strings | ECMA-376 Part 1 | §18.4 (Shared String Table) | Handling of `<sst>` and `<si>` for cell value reuse |
 | Styles & Formatting | ECMA-376 Part 1 | §18.8 (Styles) | Cell style XF indexes, font, fill, border mappings |
 | Hyperlinks | ECMA-376 Part 1 | §18.3.1.48 (hyperlink) | Worksheet hyperlinks referencing external URLs or internal targets |
+| Document Encryption (Agile) | [MS-OFFCRYPTO] | §2.3.4 (Agile Encryption) | AES-256-CBC, PBKDF2/SHA-512, HMAC-SHA512 data integrity |
+| Document Encryption (Standard) | [MS-OFFCRYPTO] | §2.3.6 (Standard Encryption) | AES-128-ECB, SHA-1 with CryptoAPI 50,000-spin key derivation |
+| Encryption Container | [MS-CFB] | §2 (Compound File Structure) | Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory |

data/docs/assets/benchmark_results.svg

@@ -0,0 +1,144 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 480" width="100%" height="100%">
+  <defs>
+    <linearGradient id="bg-grad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#161b22"/>
+      <stop offset="100%" stop-color="#0d1117"/>
+    </linearGradient>
+  </defs>
+
+  <style>
+    .card { fill: #161b22; stroke: #30363d; stroke-width: 1px; rx: 8px; }
+    .title { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 18px; font-weight: 700; fill: #f0f6fc; }
+    .subtitle { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; fill: #8b949e; }
+    .section-title { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 14px; font-weight: 700; fill: #e6edf3; }
+    .label { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; fill: #c9d1d9; }
+    .label-accent { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; font-weight: 700; fill: #58a6ff; }
+    .value { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 11px; font-weight: 600; fill: #ffffff; }
+    .grid { stroke: #21262d; stroke-width: 1px; stroke-dasharray: 4 4; }
+    .footer { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 11px; fill: #8b949e; }
+  </style>
+
+  <!-- Container -->
+  <rect width="960" height="480" rx="12" fill="url(#bg-grad)" stroke="#30363d" stroke-width="1"/>
+
+  <!-- Main Header -->
+  <text x="480" y="38" text-anchor="middle" class="title">Ruby XLSX Performance Benchmarks (1,000,000 Cells)</text>
+  <text x="480" y="58" text-anchor="middle" class="subtitle">100,000 rows × 10 cols • Mixed business data • Linear time scale (0s – 40s)</text>
+
+  <!-- Left: Write Performance -->
+  <g transform="translate(35, 75)">
+    <rect width="430" height="350" class="card"/>
+    <text x="20" y="30" class="section-title">Write Execution Time</text>
+    <text x="20" y="46" font-family="sans-serif" font-size="10" fill="#8b949e">Time to generate 1M cells (Lower is faster)</text>
+    
+    <line x1="160.0" y1="65" x2="160.0" y2="320" class="grid"/>
+    <text x="160.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">0s</text>
+
+    <line x1="215.0" y1="65" x2="215.0" y2="320" class="grid"/>
+    <text x="215.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">10s</text>
+
+    <line x1="270.0" y1="65" x2="270.0" y2="320" class="grid"/>
+    <text x="270.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">20s</text>
+
+    <line x1="325.0" y1="65" x2="325.0" y2="320" class="grid"/>
+    <text x="325.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">30s</text>
+
+    <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
+    <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
+    
+    <!-- xlsxtream 3.1.0: 1.19s -->
+    <text x="150" y="85" text-anchor="end" class="label">xlsxtream 3.1.0</text>
+    <rect x="160" y="72" width="6.5" height="18" rx="3" fill="#64748b"/>
+    <text x="174.5" y="85" class="value">1.19 s</text>
+
+    <!-- xlsxrb (Streaming): 1.73s -->
+    <text x="150" y="120" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="107" width="9.5" height="18" rx="3" fill="#3b82f6"/>
+    <text x="177.5" y="120" class="value">1.73 s</text>
+
+    <!-- fast_excel 0.5.0: 1.89s -->
+    <text x="150" y="155" text-anchor="end" class="label">fast_excel 0.5.0</text>
+    <rect x="160" y="142" width="10.4" height="18" rx="3" fill="#64748b"/>
+    <text x="178.4" y="155" class="value">1.89 s</text>
+
+    <!-- xlsxrb (In-Memory): 3.84s -->
+    <text x="150" y="190" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="177" width="21.1" height="18" rx="3" fill="#3b82f6"/>
+    <text x="189.1" y="190" class="value">3.84 s</text>
+
+    <!-- write_xlsx 1.15.0: 4.32s -->
+    <text x="150" y="225" text-anchor="end" class="label">write_xlsx 1.15.0</text>
+    <rect x="160" y="212" width="23.8" height="18" rx="3" fill="#64748b"/>
+    <text x="191.8" y="225" class="value">4.32 s</text>
+
+    <!-- caxlsx 4.5.0: 5.15s -->
+    <text x="150" y="260" text-anchor="end" class="label">caxlsx 4.5.0</text>
+    <rect x="160" y="247" width="28.3" height="18" rx="3" fill="#64748b"/>
+    <text x="196.3" y="260" class="value">5.15 s</text>
+
+    <!-- rubyXL 3.4.38: 38.81s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="213.5" height="18" rx="3" fill="#64748b"/>
+    <text x="381.5" y="295" class="value">38.81 s</text>
+  </g>
+
+  <!-- Right: Read Performance -->
+  <g transform="translate(495, 75)">
+    <rect width="430" height="350" class="card"/>
+    <text x="20" y="30" class="section-title">Read Execution Time</text>
+    <text x="20" y="46" font-family="sans-serif" font-size="10" fill="#8b949e">Time to parse 1M cells (Lower is faster)</text>
+    
+    <line x1="160.0" y1="65" x2="160.0" y2="320" class="grid"/>
+    <text x="160.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">0s</text>
+
+    <line x1="215.0" y1="65" x2="215.0" y2="320" class="grid"/>
+    <text x="215.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">10s</text>
+
+    <line x1="270.0" y1="65" x2="270.0" y2="320" class="grid"/>
+    <text x="270.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">20s</text>
+
+    <line x1="325.0" y1="65" x2="325.0" y2="320" class="grid"/>
+    <text x="325.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">30s</text>
+
+    <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
+    <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
+    
+    <!-- xlsxrb (Streaming): 3.17s -->
+    <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="72" width="17.4" height="18" rx="3" fill="#3b82f6"/>
+    <text x="185.4" y="85" class="value">3.17 s</text>
+
+    <!-- simple_xlsx_reader: 4.48s -->
+    <text x="150" y="120" text-anchor="end" class="label">simple_xlsx_reader</text>
+    <rect x="160" y="107" width="24.6" height="18" rx="3" fill="#64748b"/>
+    <text x="192.6" y="120" class="value">4.48 s</text>
+
+    <!-- xlsxrb (In-Memory): 5.71s -->
+    <text x="150" y="155" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="142" width="31.4" height="18" rx="3" fill="#3b82f6"/>
+    <text x="199.4" y="155" class="value">5.71 s</text>
+
+    <!-- creek 2.6.3: 8.14s -->
+    <text x="150" y="190" text-anchor="end" class="label">creek 2.6.3</text>
+    <rect x="160" y="177" width="44.8" height="18" rx="3" fill="#64748b"/>
+    <text x="212.8" y="190" class="value">8.14 s</text>
+
+    <!-- xsv 1.4.1: 14.61s -->
+    <text x="150" y="225" text-anchor="end" class="label">xsv 1.4.1</text>
+    <rect x="160" y="212" width="80.4" height="18" rx="3" fill="#64748b"/>
+    <text x="248.4" y="225" class="value">14.61 s</text>
+
+    <!-- roo 3.0.0: 15.69s -->
+    <text x="150" y="260" text-anchor="end" class="label">roo 3.0.0</text>
+    <rect x="160" y="247" width="86.3" height="18" rx="3" fill="#64748b"/>
+    <text x="254.3" y="260" class="value">15.69 s</text>
+
+    <!-- rubyXL 3.4.38: 37.13s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="204.2" height="18" rx="3" fill="#64748b"/>
+    <text x="372.2" y="295" class="value">37.13 s</text>
+  </g>
+
+  <!-- Footer -->
+  <text x="480" y="455" text-anchor="middle" class="footer">Tested on Ruby 3.4+ in isolated subprocesses • Full GC and peak memory metrics in docs/PEER_LIBRARIES.md</text>
+</svg>

data/docs/visual/VisualGallery.md

@@ -251,6 +251,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#conditional-formatting">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Drawing Shapes</strong></td>
+<td align="center"><img src="../../test/visual/baselines/drawing_shapes/page-1.png" width="160" alt="Drawing Shapes"/></td>
+<td align="center"><a href="#drawing-shapes">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>Embedded Images</strong></td>
 <td align="center"><img src="../../test/visual/baselines/embedded_images/page-1.png" width="160" alt="Embedded Images"/></td>
 <td align="center"><a href="#embedded-images">View Code &amp; Detail</a></td>
@@ -361,6 +366,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#page-paper-size-a3">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Pivot Table</strong></td>
+<td align="center"><img src="../../test/visual/baselines/pivot_table/page-1.png" width="160" alt="Pivot Table"/></td>
+<td align="center"><a href="#pivot-table">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>Row Grouping</strong></td>
 <td align="center"><img src="../../test/visual/baselines/row_grouping/page-1.png" width="160" alt="Row Grouping"/></td>
 <td align="center"><a href="#row-grouping">View Code &amp; Detail</a></td>
@@ -396,6 +406,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#styles-fonts-fills">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Table Styles</strong></td>
+<td align="center"><img src="../../test/visual/baselines/table_styles/page-1.png" width="160" alt="Table Styles"/></td>
+<td align="center"><a href="#table-styles">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>View Show Grid Lines</strong></td>
 <td align="center"><img src="../../test/visual/baselines/view_show_grid_lines/page-1.png" width="160" alt="View Show Grid Lines"/></td>
 <td align="center"><a href="#view-show-grid-lines">View Code &amp; Detail</a></td>
@@ -2844,6 +2859,55 @@ Row 0: A1: 90, B1: 45, C1: 72, D1: 88
 
 <hr/>
 
+## Drawing Shapes
+
+Visual demonstration for Drawing Shapes.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/drawing_shapes/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/drawing_shapes/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "drawing_shapes.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("Shapes") do |sheet|
+    sheet.column(0..7, width: 15)
+    sheet.row(["Diagram with shapes and annotations"])
+    sheet.row([])
+    sheet.shape(preset: "rect", text: "Process Start", from_col: 1, from_row: 2, to_col: 3, to_row: 4)
+    sheet.shape(preset: "rightArrow", text: "Next", from_col: 4, from_row: 3, to_col: 5, to_row: 4)
+    sheet.shape(preset: "roundRect", text: "Processing", from_col: 6, from_row: 2, to_col: 8, to_row: 4)
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "Diagram with shapes and annotations"
+Row 1:
+```
+
+<hr/>
+
 ## Embedded Images
 
 Demonstrates embedding raster PNG images in cell ranges.
@@ -4010,6 +4074,71 @@ Print Options: {}
 
 <hr/>
 
+## Pivot Table
+
+Visual demonstration for Pivot Table.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/pivot_table/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/pivot_table/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "pivot_table.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("SalesData") do |sheet|
+    sheet.column(0..3, width: 18)
+    sheet.row(%w[Region Quarter Sales Rep])
+    sheet.row(["East", "Q1", 1000, "Alice"])
+    sheet.row(["West", "Q1", 1500, "Bob"])
+    sheet.row(["East", "Q2", 1200, "Alice"])
+    sheet.row(["West", "Q2", 1800, "Bob"])
+    sheet.row(["North", "Q1", 800, "Charlie"])
+    sheet.row(["North", "Q2", 950, "Charlie"])
+
+    sheet.pivot_table(
+      "SalesData!A1:D7",
+      row_fields: ["Region"],
+      data_fields: [{ name: "Sales", subtotal: "sum" }],
+      col_fields: ["Quarter"],
+      dest_ref: "F1",
+      name: "RegionalSalesSummary"
+    )
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "Region", B1: "Quarter", C1: "Sales", D1: "Rep"
+Row 1: A2: "East", B2: "Q1", C2: 1000, D2: "Alice"
+Row 2: A3: "West", B3: "Q1", C3: 1500, D3: "Bob"
+Row 3: A4: "East", B4: "Q2", C4: 1200, D4: "Alice"
+Row 4: A5: "West", B5: "Q2", C5: 1800, D5: "Bob"
+Row 5: A6: "North", B6: "Q1", C6: 800, D6: "Charlie"
+Row 6: A7: "North", B7: "Q2", C7: 950, D7: "Charlie"
+```
+
+<hr/>
+
 ## Row Grouping
 
 Demonstrates outline grouping for rows.
@@ -4357,6 +4486,60 @@ Row 1: A2: "Normal Text" (font=, fill=), B2: "Highlighted Text" (font=Calibri, f
 
 <hr/>
 
+## Table Styles
+
+Visual demonstration for Table Styles.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/table_styles/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/table_styles/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "table_styles.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("Table Example") do |sheet|
+    sheet.column(0..3, width: 20)
+    sheet.row(%w[ID Name Department Salary])
+    sheet.row([101, "Alice Smith", "Engineering", 120_000])
+    sheet.row([102, "Bob Jones", "Marketing", 95_000])
+    sheet.row([103, "Carol White", "Sales", 110_000])
+    sheet.row([104, "David Brown", "Engineering", 130_000])
+
+    sheet.table("A1:D5", columns: %w[ID Name Department Salary], name: "EmployeeTable", style: "TableStyleMedium9", total_row: false)
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "ID", B1: "Name", C1: "Department", D1: "Salary"
+Row 1: A2: 101, B2: "Alice Smith", C2: "Engineering", D2: 120000
+Row 2: A3: 102, B3: "Bob Jones", C3: "Marketing", D3: 95000
+Row 3: A4: 103, B4: "Carol White", C4: "Sales", D4: 110000
+Row 4: A5: 104, B5: "David Brown", C5: "Engineering", D5: 130000
+```
+
+<hr/>
+
 ## View Show Grid Lines
 
 Demonstrates disabling visible grid lines in spreadsheet view.