xlsxrb 0.1.12 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a818d0e9e58b9ada1a11c90db9f9baa55fc76b3a7e62303d33a61f2e6f9896
-  data.tar.gz: c7b5f4af516d9911a1ee37ef5413939e8425bc270304900132e0962fad18905d
+  metadata.gz: a6733f82b936fb790e6192de72890ecedd016f21dd4a5e43ee0f5123a2d35f5e
+  data.tar.gz: 3dd84ebc97a5c10a2777f6bd7557b06660e690f0723f8af6664a244a143adaa6
 SHA512:
-  metadata.gz: 9deec47109a21a62aafb4a93efcee64f61f5ffb4566fd009cd1d5fdb9557e1193a53155d60ff7e4cc565317d49fb4ce8b3b89542234dff6a900981cd9220d14a
-  data.tar.gz: b536ef03e3ae01c49ff8e00c693d86fb72a9248cae1ccf93802962127d9b86ef676b5b17ca4b896613961bab8869139644e439542b1bca5adb6a7452d971f124
+  metadata.gz: 6ca0217ecd3a83a922a1098740d584c6e78fd0695f46acaa661286497a0e0de1c9214990eb7fef622a10ad4a1641f9aae73079ab61b0787570a22e434b446d0e
+  data.tar.gz: 7603890bc9f20d9143656ea83f0fd75410b4636cc66bbd152e79965b4b2bc07013de05f1489560fc896b9f5e1890c9fb6b421ec8dbc49b66ca9dec7912ab617c

data/CHANGELOG.md

@@ -1,20 +1,37 @@
+## [Unreleased]
+
+## [0.1.13] - 2026-09-25
+
+### Added
+- Non-destructive template modification: Support modifying existing XLSX templates while preserving unmapped parts, media, charts, drawings, and VBA macros via `Xlsxrb.modify`.
+- StreamSheet structural metadata accessors: Expose `merged_cells`, `auto_filter`, `data_validations`, and `conditional_formats` on `StreamSheet`.
+- Pre-Push Smart Change Detection: Optimized `bin/pre-push --all` to automatically skip runtime RBS validation and pure logic mutation testing when unrelated files are modified, adding `--last` and `--force` controls.
+
+### Changed
+- True O(1) memory streaming read via chunked entry inflation in `ZipReader` and `WorksheetParser`, preventing unbounded memory retention on large worksheets.
+- Extracted pure DSL normalizers (`Xlsxrb::DslHelpers`) and fast XML unescape utilities (`Ooxml::XmlBuilder.unescape`).
+- Constrained `rexml` runtime dependency to `~> 3.0` and excluded documentation, build assets, and developer configurations from the gem package.
+
+### Removed
+- OpenTelemetry runtime dependency and tracer spans.
+
 ## [0.1.12] - 2026-09-20
 
 ### Added
-- **Mutation Testing Framework (`mutant`)**:
+- Mutation Testing Framework (`mutant`):
   - Full-scale integration of mutant test suite targeting the Functional Core (10 classes and modules, 38 subjects).
-  - Achieved **100.00% Kill Rate (1,091 / 1,091 mutations killed, 0 alive)** without exclusions.
+  - Achieved 100.00% Kill Rate (1,091 / 1,091 mutations killed, 0 alive) without exclusions.
   - Added dedicated root configuration [`.mutant.yml`](.mutant.yml) for streamlined CLI execution (`bundle exec mutant run -- '...'`).
   - Integrated `bundle exec rake mutant:pure` into GitHub Actions CI pipeline (`main.yml`), guaranteeing mutation-tested quality on every push and pull request.
-  - Added comprehensive architecture and testing guide in [`docs/MUTATION_TESTING.md`](docs/MUTATION_TESTING.md).
-- **Pre-Push Quality Verification Script (`bin/pre-push`)**: Added automated pre-push verification script running RuboCop, Steep type checking, RBS sync validation, Unit & Contract tests, RBS runtime type validation, and pure logic mutation testing, with automatic hook installation in `bin/setup`.
+  - Added architecture and testing guide in [`docs/MUTATION_TESTING.md`](docs/MUTATION_TESTING.md).
+- Pre-Push Quality Verification Script (`bin/pre-push`): Added automated pre-push verification script running RuboCop, Steep type checking, RBS sync validation, Unit & Contract tests, RBS runtime type validation, and pure logic mutation testing, with automatic hook installation in `bin/setup`.
 
 ### Changed
-- **Functional Core & Imperative Shell Architecture**:
+- Functional Core & Imperative Shell Architecture:
   - Purified core business logic and domain entities into deterministic, side-effect-free class methods and predicates:
     - Extracted coordinate and validation predicates: `Elements::Cell.valid_value?`, `Cell.valid_coordinates?`, `Cell.calculate_column_letter`, `Cell.calculate_column_index`.
     - Extracted domain validation predicates: `Elements::Row.valid_index?`, `Elements::Column.valid_index?`, `Elements::Worksheet.valid_name?`.
-    - Replaced date/time serial calculations in `Ooxml::Utils` with pure mathematical conversions (Julian Day math for `date_to_serial`, `divmod` arithmetic for `serial_to_datetime`, and rigorous 1900 leap year bug handling).
+    - Replaced date/time serial calculations in `Ooxml::Utils` with pure mathematical conversions (Julian Day math for `date_to_serial`, `divmod` arithmetic for `serial_to_datetime`, and 1900 leap year bug handling).
     - Extracted binary packing utilities in `Ooxml::ZipGenerator` (`le16`, `le32`, and bitfield arithmetic for `dos_datetime`).
     - Extracted pure XML character escaping logic in `Ooxml::XmlBuilder.escape`.
   - Modularized `Ooxml::Writer` into domain-specific mixin modules (`DrawingXml`, `FeaturesXml`, `StylesXml`).
@@ -22,12 +39,12 @@
   - Modularized reader SAX listeners into domain-specific parser components.
 
 ### Fixed
-- **Boundary Validation & Error Reporting**:
+- Boundary Validation & Error Reporting:
   - Strictly validate row number digits in `Elements::Cell.parse_ref` to reject malformed cell coordinate strings (e.g. `A0`, `A01`).
   - Harmonized supported value type checks and nil/empty handling across `Elements::Cell.validate`.
   - Corrected maximum row index boundary error messages in `Elements::Row.validate`.
   - Hardened cryptographic stream boundary checks and corrupted header handling in Standard and Agile encryption modes.
-- **RBS Runtime Type Validation**:
+- RBS Runtime Type Validation:
   - Expanded `Elements::Workbook#initialize`, `#sheet`, and `[]` type annotations to accept `StreamSheet` instances used by streaming readers.
   - Made update block parameter optional in `Elements::Workbook#update_sheet` to allow testing missing block validation.
   - Supported `Numeric` types (Float and Integer) in `ChartBuilder` and `SeriesBuilder` kwargs (`width`, etc.).
@@ -36,15 +53,15 @@
 ## [0.1.11] - 2026-08-19
 
 ### Performance
-- **Sub-Second Streaming Write (< 1.0s / 1,000,000 cells)**:
-  - Achieved sub-second streaming write performance (**0.97 s** median for 1M cells) while maintaining 100% full SST (Shared String Table) XML deduplication and ISO/IEC 29500 compatibility.
+- Sub-Second Streaming Write (< 1.0s / 1,000,000 cells):
+  - Achieved sub-second streaming write performance (0.97 s median for 1M cells) while maintaining 100% full SST (Shared String Table) XML deduplication and ISO/IEC 29500 compatibility.
   - Implemented 1-Pass Direct ZIP streaming pipeline, eliminating all intermediate tempfiles, disk seek-backs, and extra deflate flush cycles.
   - Added dedicated unstyled fast-path in `WorksheetWriter#write_row_values` with precomputed coordinate and integer lookup tables.
   - Pre-registered default date/time formatting styles, completely eliminating redundant per-row scan loops.
   - Streamlined `ZipWriter` instance variable lookups to eliminate per-chunk hash overhead.
   - Added `alias << row` to `WorksheetProxy` and `StreamWriter` for idiomatic Ruby streaming.
-- **High-Speed Streaming Read (1.61s / 1,000,000 cells)**:
-  - Reduced streaming read execution time from **3.40 s** down to **1.61 s** (over 2x speedup).
+- High-Speed Streaming Read (1.61s / 1,000,000 cells):
+  - Reduced streaming read execution time from 3.40 s down to 1.61 s (over 2x speedup).
   - Refactored `Elements::Cell` into an optimized lightweight class with `Cell.fast_create`, reducing 1M cell instantiation overhead by 5.2x (0.92s → 0.17s) while maintaining full pattern matching (`deconstruct`, `deconstruct_keys`) and immutability.
   - Replaced per-byte Ruby scanning in `WorksheetParser.fast_scan_cells_direct` with an Onigmo C-level regular expression scanner (`CELL_FAST_RE`), eliminating 100,000 intermediate XML substring allocations and nested byte loops.
   - Optimized `StreamRow#cells` to populate cell arrays via direct block traversal, eliminating Enumerator object allocations.
@@ -55,56 +72,56 @@
 ## [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**:
+- 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.
+- Multi-Layered Test Suite Expansion:
+  - ECMA-376 XSD Schema Validation: XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
+  - Contract Testing Suite: 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.
+- 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.
+- 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
-- **Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB])**: Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
-  - **Standard Encryption**: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
-  - **Agile Encryption**: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
-  - **Compound File Binary (CFB) Engine**: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
-  - **Transparent Public API Integration**: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
-  - **Security & Threat Model Hardening**:
+- Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB]): Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
+  - Standard Encryption: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
+  - Agile Encryption: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
+  - Compound File Binary (CFB) Engine: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
+  - Transparent Public API Integration: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
+  - Security & Threat Model Hardening:
     - Constant-time hash verification via `OpenSSL.secure_compare` to prevent timing attacks (CWE-208).
     - CSPRNG-backed salt, IV, and session key generation via `SecureRandom` (CWE-330).
-    - Robust DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
+    - DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
     - Strict exception hierarchy (`EncryptedFileError`, `InvalidPasswordError`, `DecryptionError`).
-  - **Cross-Platform & Interoperability Validation**: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
-  - **WebAssembly (ruby.wasm) Support**: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
+  - Cross-Platform & Interoperability Validation: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
+  - WebAssembly (ruby.wasm) Support: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
 
 ## [0.1.8] - 2026-08-18
 
 ### Changed
-- **Unified Symmetric Entrypoints**: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
-- **Streaming-First Defaults**: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
-- **Explicit In-Memory Materialization (`#load`)**: Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
-- **`CoordinateAccess` Module**: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
+- Unified Symmetric Entrypoints: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
+- Streaming-First Defaults: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
+- Explicit In-Memory Materialization (`#load`): Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
+- `CoordinateAccess` Module: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
 
 ### Added
-- **Default Cell Streaming (`Xlsxrb::StreamRow`)**: Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
+- Default Cell Streaming (`Xlsxrb::StreamRow`): Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
 
 ## [0.1.7] - 2026-08-16
 
 ### Added
 - Bundled native Ruby LSP Add-on (`RubyLsp::Xlsxrb::Addon`) for zero-configuration, context-aware method autocompletion and rich markdown documentation in VS Code and LSP-enabled editors for block arguments (`wb.`, `s.`, `sheet.`, `stream_writer.`, `stream_sheet.`).
-- Comprehensive YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
+- YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
 
 ### Developer Experience
 - Enhanced `rbs-inline` type signatures across all facade methods and builder objects with automated RBS generation.
@@ -119,10 +136,10 @@
 - Hash-compatible symbol indexing in `Elements::Row#[]` (`:cells`, `:index`, `:height`, `:attrs`) and `Elements::Cell#[]` (`:value`, `:ref`, `:style_index`).
 
 ### Performance
-- **Streaming Write**: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
-- **In-Memory Write**: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
-- **Streaming Read**: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
-- **In-Memory Read**: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
+- Streaming Write: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
+- In-Memory Write: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
+- Streaming Read: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
+- In-Memory Read: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
 
 ### Documentation
 - Overhauled `benchmark.rb` with `bundler/inline` for deterministic, zero-setup benchmark reproduction pinning peer gem versions.
@@ -142,7 +159,7 @@
 - Full `RBS::Test` runtime type validation enabled for the entire test suite.
 - Extensive Excel limit warnings documented via YARD tags.
 - Formal SemVer API contract with `@api public` tags for user-facing methods.
-- Comprehensive mutation testing (Mutant) and test coverage (SimpleCov) integrations.
+- Mutation testing (Mutant) and test coverage (SimpleCov) integrations.
 
 ### Changed
 - Replaced `method_missing` with statically defined, fully typed methods in `WorksheetProxy`, `ChartBuilder`, and `SeriesBuilder`.

data/README.md

@@ -4,7 +4,7 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 ## Motivation
 
-The Ruby ecosystem already has great XLSX libraries, each designed for specific tradeoffs:
+The Ruby ecosystem has several XLSX libraries designed for specific tradeoffs:
 
 | Library | Read | Write | Streaming | In-Memory |
 | :--- | :---: | :---: | :---: | :---: |
@@ -17,23 +17,27 @@ The Ruby ecosystem already has great XLSX libraries, each designed for specific
 | [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)** | **✅** | **✅** | **✅** | **✅** |
+| [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.
+These libraries make different architectural tradeoffs:
+* 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.
+Maintaining a gem that supports both reading and writing across streaming and in-memory models, alongside OOXML features and specification compatibility, involves significant ongoing maintenance overhead.
 
-`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.
+`xlsxrb` addresses this through automated workflows: AI coding agents handle routine maintenance tasks such as end-to-end testing, visual regression testing, schema compliance checks, and documentation synchronization, enabling sustainable maintenance of both streaming and in-memory architectures.
 
 ### Design Principles
 
-- **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.
+- Zero Runtime Dependencies: Built strictly on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.) with zero third-party runtime dependencies.
+- Streaming Support: Constant $O(1)$ memory streaming for reading and writing spreadsheets.
+- OpenXML Interoperability: Compliant with ISO/IEC 29500 (ECMA-376) and validated against the Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
+- AI-Assisted Maintenance: Uses AI coding agents for automated quality assurance and verification workflows. Operational guidelines are defined in [AGENTS.md](AGENTS.md).
+- Ruby 4.0+: Requires Ruby 4.0 or higher.
+
+### Autonomous Quality Assurance
+
+To maintain its multi-layered QA suite (Steep static typing, 100% mutation kill rate across 38 subjects, ECMA-376 XSD validation, and $O(1)$ streaming memory) without high manual maintenance overhead, xlsxrb defines remediation workflows for AI coding agents ([AGENTS.md](AGENTS.md), [docs/QA_AGENTS.md](docs/QA_AGENTS.md)).
 
 ## Installation
 
@@ -134,7 +138,7 @@ end
 
 ### IDE Autocompletion & Ruby LSP Support
 
-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:
+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:
 
 <p align="center">
   <img src="docs/assets/lsp_autocompletion.png" width="100%" alt="Ruby LSP Autocompletion & Type Signature Hints in VS Code"/>
@@ -142,9 +146,9 @@ Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-confi
 
 ## Feature Support & ECMA-376 Compliance
 
-`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).
+`xlsxrb` supports standard 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 full details, see [docs/SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
 
@@ -162,12 +166,12 @@ To reproduce locally: `ruby benchmark.rb 100000 10`
 
 ## Quality Assurance & Testing
 
-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.
-* **Mutation Testing (Mutant)**: 100% mutant kill rate (1,091/1,091 mutations across 38 subjects) on pure algorithms, predicates, and coordinates ([docs/MUTATION_TESTING.md](docs/MUTATION_TESTING.md)).
-* **Security & DoS Protection**: Formula injection mitigation and ZIP bomb protection.
+Verified by a multi-layered QA architecture:
+* 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.
+* Mutation Testing (Mutant): 100% mutant kill rate (1,091/1,091 mutations across 38 subjects) on pure algorithms, predicates, and coordinates ([docs/MUTATION_TESTING.md](docs/MUTATION_TESTING.md)).
+* Security & DoS Protection: Formula injection mitigation and ZIP bomb protection.
 
 For full architectural details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md).
 

data/lib/xlsxrb/dsl_helpers.rb

@@ -112,5 +112,64 @@ module Xlsxrb
       tbl.merge!(opts)
       tbl
     end
+
+    # Converts a cell range (e.g. "A1:B2" or "A1") to an absolute reference format (e.g. "$A$1:$B$2" or "$A$1").
+    #
+    # @param range [String]
+    # @return [String]
+    #: (String range) -> String
+    def self.absolute_range(range)
+      range.gsub(/(?:\$)?([A-Z]+)(?:\$)?(\d+)\b/, '$\1$\2')
+    end
+
+    # Normalizes row values: if given a column-keyed Hash, converts to a sparse Array.
+    # If already an Array or other non-Hash enumerable, returns as-is without allocations.
+    #
+    # @param values [Array<Object>, Hash{String, Integer, Symbol => Object}, nil]
+    # @return [Array<Object>, nil]
+    #: (untyped values) -> untyped
+    def self.normalize_row_values(values)
+      return values unless values.is_a?(Hash)
+
+      cells_array = []
+      values.each do |k, v|
+        cells_array[Elements::Cell.column_index(k)] = v
+      end
+      cells_array
+    end
+
+    # Normalizes row styles: if given a Hash of column-keyed styles (including Ranges/Arrays),
+    # expands to a sparse Array of styles. If already an Array or nil, returns as-is without allocations.
+    #
+    # @param styles [untyped]
+    # @return [untyped]
+    #: (untyped styles) -> untyped
+    def self.normalize_row_styles(styles)
+      return styles unless styles.is_a?(Hash)
+
+      styles_array = []
+      styles.each do |k, v|
+        if k.is_a?(Range) || k.is_a?(Array)
+          k.each { |idx| styles_array[Elements::Cell.column_index(idx)] = v }
+        else
+          styles_array[Elements::Cell.column_index(k)] = v
+        end
+      end
+      styles_array
+    end
+
+    # Validates row index and height against Excel limits in strict mode.
+    #
+    # @param row_index [Integer]
+    # @param height [Float, Integer, nil]
+    # @param strict_excel_mode [Boolean]
+    # @return [void]
+    #: (Integer row_index, Float | Integer | nil height, ?strict_excel_mode: bool) -> void
+    def self.validate_row_bounds!(row_index, height, strict_excel_mode: true)
+      return unless strict_excel_mode
+
+      raise ArgumentError, "Row index #{row_index} exceeds Excel limit of 1,048,576 rows" if row_index >= 1_048_576
+      raise ArgumentError, "Row height #{height} must be between 0 and 409 points (Excel limitation)" if height && (height.negative? || height > 409)
+    end
   end
 end

data/lib/xlsxrb/elements/workbook.rb

@@ -86,10 +86,21 @@ module Xlsxrb
       #: () -> Elements::Workbook
       def load
         loaded_sheets = sheets.map { |s| s.respond_to?(:load) ? s.load : s }
+        close
         with(sheets: loaded_sheets)
       end
       alias to_workbook load
 
+      # Closes any streaming resources associated with worksheets.
+      #
+      # @return [void]
+      # @api public
+      #: () -> void
+      def close
+        sheets.each { |s| s.close if s.respond_to?(:close) }
+        nil
+      end
+
       # Returns a new Workbook with the specified sheet updated.
       # Yields the matched worksheet to the block, which must return a new Worksheet.
       #

data/lib/xlsxrb/ooxml/shared_strings_parser.rb

@@ -3,14 +3,13 @@
 # rbs_inline: enabled
 
 require_relative "xml_parser"
+require_relative "xml_builder"
 
 module Xlsxrb
   module Ooxml
     # SAX-based parser for xl/sharedStrings.xml.
     # Returns an Array of strings (index = SST index).
     class SharedStringsParser
-      XML_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"', "&apos;" => "'" }.freeze
-
       # Parses all shared strings and returns an Array of strings.
       def self.parse(xml_string, _part_name: "xl/sharedStrings.xml")
         return [] if xml_string.nil? || xml_string.empty?
@@ -89,7 +88,7 @@ module Xlsxrb
                     str = extract_multi_t(xml, si_open_end + 1, si_end)
                   else
                     raw_str = xml.byteslice(t_open_end + 1, t_end - t_open_end - 1).force_encoding("UTF-8")
-                    str = raw_str.include?("&") ? raw_str.gsub(/&(?:amp|lt|gt|quot|apos);/, XML_ENTITIES) : raw_str
+                    str = XmlBuilder.unescape(raw_str)
                   end
                 else
                   str = ""
@@ -128,8 +127,7 @@ module Xlsxrb
           break unless t_end && t_end <= to
 
           raw_chunk = xml.byteslice(t_open_end + 1, t_end - t_open_end - 1).force_encoding("UTF-8")
-          raw_chunk = raw_chunk.gsub(/&(?:amp|lt|gt|quot|apos);/, XML_ENTITIES) if raw_chunk.include?("&")
-          buf << raw_chunk
+          buf << XmlBuilder.unescape(raw_chunk)
           pos = t_end + 4
         end
         buf

data/lib/xlsxrb/ooxml/workbook_writer.rb

@@ -33,13 +33,11 @@ module Xlsxrb
       def self.write(target, sheets:, shared_strings: [], shared_strings_index: nil, styles: nil,
                      defined_names: nil, core_properties: nil, app_properties: nil,
                      custom_properties: nil, workbook_protection: nil, workbook_properties: nil)
-        Xlsxrb.in_span("Ooxml::WorkbookWriter.write") do
-          writer = new(sheets: sheets, shared_strings: shared_strings, shared_strings_index: shared_strings_index, styles: styles,
-                       defined_names: defined_names, core_properties: core_properties,
-                       app_properties: app_properties, custom_properties: custom_properties,
-                       workbook_protection: workbook_protection, workbook_properties: workbook_properties)
-          writer.write_to(target)
-        end
+        writer = new(sheets: sheets, shared_strings: shared_strings, shared_strings_index: shared_strings_index, styles: styles,
+                     defined_names: defined_names, core_properties: core_properties,
+                     app_properties: app_properties, custom_properties: custom_properties,
+                     workbook_protection: workbook_protection, workbook_properties: workbook_properties)
+        writer.write_to(target)
       end
 
       def initialize(sheets:, shared_strings: [], shared_strings_index: nil, styles: nil,