xlsxrb 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ded1e540cdab22988eb7c5bfcfe9951a6a24ccae3f1d631962d174780dc5562
-  data.tar.gz: 9757007ef792b32b665e0a291d5fa242053a49ae1c48e91e8471bfb19ed4f235
+  metadata.gz: 985967acd75137e7175ca5ed93493f4fcc001696499e1afdfe0c9d4e5fbaad97
+  data.tar.gz: f59bddd81cc312ecda261ef6875daffdfeff6571650298aa0cd56956318db07a
 SHA512:
-  metadata.gz: 68ab59ce1086f06379241af5140d4c2dc69757bff606c385e90a13014c50cda15a54deeaf299d85f40f023c54081917ae5b2cd71408dcc48bcba6a7634e69eed
-  data.tar.gz: 6cfd71118b60aa30a94463902c5f808ebad242f32f6f6fe7b74f6e0733bd30de5db8f9e2e6b4149ec16df1bccd0e50f08d5e4aec6bcff58a8501f40ad350c7eb
+  metadata.gz: c88eb2065c70cf4d0fab24508fc168601483fdade7e81593a186272d7fd11de72f9898f178ff591f466d4d3abd14c885c6193238572256a3a08eee56073355d1
+  data.tar.gz: a7c80be810fb05b948680492fb917f38f362460f1c095962fc090ed3d399317f83466c47f8b7ad3229c8a3bfa013a6ed23daaa174ef5d9278ef7ccf3ab36f6d8

data/README.md

@@ -18,14 +18,18 @@ The Ruby ecosystem already has great XLSX libraries. Each is well-designed for i
 
 Each of these libraries makes deliberate tradeoffs, and they do so thoughtfully. Some focus exclusively on highly efficient reading or writing by streaming data, while others provide a rich API for complex, in-memory document modifications.
 
-`xlsxrb` is for cases where you need **both** reading and writing in a single library, while also keeping memory usage predictable for large files.
+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.
 
 ### 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.
-- **Modern Ruby 4.0+:** Built for the future with Ruby 4.0 or higher.
+- 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.
 
 ## Installation
 
@@ -43,7 +47,9 @@ On Ruby 4+, some components used by `xlsxrb` and its test suite are shipped as b
 
 ## Interactive Playground (WebAssembly)
 
-You can try `xlsxrb` directly in your browser without installing anything! 
+You can 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.
 
@@ -56,37 +62,18 @@ To launch the playground locally:
    ```bash
    bundle exec rake doc:preview
    ```
-3. Open [http://localhost:8000](http://localhost:8000) in your browser and click the **"Try it in Browser"** button on any code example!
+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!
 
 ## Usage
 
-For visual demonstrations of various features and their generated output side-by-side with code examples, check the [Visual Examples Gallery](docs/visual/VisualGallery.md).
-
-`xlsxrb` offers two different approaches to reading and writing XLSX files: **Streaming** and **In-Memory**.
+`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).
 
-In most cases, the **Streaming** approach is the best choice because it is highly memory efficient, avoiding loading entire files or structures into RAM. You should always try the Streaming approach first.
+For visual demonstrations of various features, check the [Visual Examples Gallery](docs/visual/VisualGallery.md).
 
-However, if your use case requires **Random Access** (e.g., reading a cell at `Z100`, then returning to `A1`) or you need to build or modify an entire document iteratively before writing, the **In-Memory** approach is required.
-
-### 1. Streaming (Recommended)
-
-#### Streaming Read
-
-Read rows one at a time without loading the entire file into memory:
-
-```ruby
-require "xlsxrb"
-
-# Yields Xlsxrb::Elements::Row objects for the first sheet
-Xlsxrb.foreach("large_file.xlsx", sheet: 0) do |row|
-  puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
-end
-```
+### Quick Start: Streaming (Recommended)
 
 #### Streaming Write
-
 Generate large files efficiently by writing data directly to the file stream:
-
 ```ruby
 require "xlsxrb"
 
@@ -99,275 +86,81 @@ Xlsxrb.generate("large_output.xlsx") do |writer|
 end
 ```
 
-_For more advanced streaming features (such as adding charts, sparklines, or complex styling during stream generation), see the [Visual Examples Gallery](docs/visual/VisualGallery.md)._
-
-### 2. In-Memory
-
-#### Reading into memory
-
-Parse the entire workbook for random access by cell reference:
-
-```ruby
-require "xlsxrb"
-
-workbook = Xlsxrb.read("example.xlsx")
-sheet = workbook.sheets.first
-
-# Random access by cell reference
-puts "Value at C10: #{sheet.cell_value("C10")}"
-```
-
-#### Writing from memory
-
-Construct a workbook hierarchy in memory using the DSL and write it:
-
-```ruby
-require "xlsxrb"
-
-workbook = Xlsxrb.build do |w|
-  w.add_sheet("My Sheet") do |s|
-    s.add_row(["Hello", "World"])
-  end
-end
-
-Xlsxrb.write("output.xlsx", workbook)
-```
-
-#### Modifying an existing workbook
-
-Read an existing file, make changes, and write it back:
-
+#### Streaming Read
+Read rows one at a time without loading the entire file into memory:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.modify("template.xlsx", "output.xlsx") do |wb|
-  sheet = wb.sheet(0)
-  row0 = sheet.row_at(0)
-
-  new_cell = Xlsxrb::Elements::Cell.new(row_index: 0, column_index: 1, value: "Updated")
-  new_row = row0.with(cells: row0.cells.map { |c| c.column_index == 1 ? new_cell : c })
-  new_sheet = sheet.with(rows: sheet.rows.map { |r| r.index == 0 ? new_row : r })
-
-  wb.with(sheets: wb.sheets.map.with_index { |s, i| i == 0 ? new_sheet : s })
-end
-```
-
-_For details on adding charts or shapes in-memory, see the [Visual Examples Gallery](docs/visual/VisualGallery.md)._
-
-## Specification
-
-## Sheet Features
-
-All sheet-level features work identically in both the streaming (`Xlsxrb.generate`) and in-memory (`Xlsxrb.build`) APIs. Detailed code examples, runnable scripts, and side-by-side visual rendering results (screenshots) for all sheet-level features are available in the [Visual Gallery (docs/visual/VisualGallery.md)](docs/visual/VisualGallery.md).
-
-- **[Formulas](docs/visual/VisualGallery.md#cell-formulas)** - Write standard or Excel formulas with automatic evaluation.
-- **[Hyperlinks](docs/visual/VisualGallery.md#basic-data)** - Attach web URLs or jump to internal worksheet cell locations.
-- **[Auto Filter](docs/visual/VisualGallery.md#interactive-autofilter)** - Add interactive filter drop-down menus to column ranges.
-- **[Data Validation](docs/visual/VisualGallery.md#interactive-validation-list)** - Restrict allowed cell values (lists, range limits, dates, times, custom expressions) with custom warning popups.
-- **[Conditional Formatting](docs/visual/VisualGallery.md#cf-begins-with)** - Highlight cells automatically using rule comparisons, color scales, data bars, icon sets, or formula expressions.
-- **[Tables](docs/visual/VisualGallery.md#borders)** - Wrap cell ranges in structured tables with column headers and preset visual styles.
-- **[Pivot Tables](docs/visual/VisualGallery.md#pivot-tables)** - Summarize data ranges dynamically with row/column grouping and subtotals.
-- **[Comments](docs/visual/VisualGallery.md#interactive-comments)** - Attach hover-activated popup notes to specific cells.
-- **[Merge Cells](docs/visual/VisualGallery.md#merge-freeze)** - Combine rectangular cell ranges into single styled cells.
-- **[Freeze & Split Panes](docs/visual/VisualGallery.md#merge-freeze)** - Freeze top rows or left columns (or split viewport by pixel offsets) to keep headers visible.
-- **[Page margins & Print Setup](docs/visual/VisualGallery.md#page-setup)** - Set portrait/landscape orientation, margins, paper sizes, scaling (fit-to-page), and odd/even headers & footers.
-- **[Print Options](docs/visual/VisualGallery.md#page-grid-lines-print)** - Toggle gridlines, row/column headings visibility when printing, and centering.
-- **[Sheet Protection](docs/visual/VisualGallery.md#sheet-protection)** - Lock sheet structures, formatting, or objects (optionally with SHA-512 hashed passwords).
-- **[Page Breaks](docs/visual/VisualGallery.md#page-setup)** - Insert manual horizontal or vertical page breaks.
-- **[Images](docs/visual/VisualGallery.md#embedded-images)** - Embed and anchor floating images (PNG, JPEG) with custom dimensions.
-- **[Sparklines](docs/visual/VisualGallery.md#sparkline-column)** - Insert inline column or line trend charts into single cells.
-- **[Shapes & Drawings](docs/visual/VisualGallery.md#shapes)** - Draw rectangles, ellipses, and other presets with solid fills, lines, and custom text.
-- **[Sheet Properties and View Settings](docs/visual/VisualGallery.md#sheet-tab-colors)** - Customize per-sheet properties (tab colors, hide gridlines, default zoom levels).
-
-## Workbook Features
-
-Workbook-level methods are called directly on the writer/builder object (not inside `add_sheet`).
-
-### Defined Names, Print Area, and Print Titles
-
-```ruby
-Xlsxrb.generate("named.xlsx") do |w|
-  w.add_sheet("Data") do |s|
-    s.add_row(["Name", "Score"])
-    s.add_row(["Alice", 95])
-  end
-
-  # General named range
-  w.add_defined_name("TaxRate", "0.1", hidden: false)
-
-  # Print area for the sheet named "Data"
-  w.set_print_area("A1:B10", sheet: "Data")
-
-  # Repeat first row and first column when printing
-  w.set_print_titles(rows: "1:1", cols: "A:A", sheet: "Data")
-end
-```
-
-### Workbook Protection
-
-Lock the workbook structure (prevents adding/removing/renaming sheets).
-
-```ruby
-Xlsxrb.generate("locked_workbook.xlsx") do |w|
-  w.add_sheet("Sheet1") { |s| s.add_row(["Data"]) }
-
-  w.set_workbook_protection(lock_structure: true, lock_windows: false)
+Xlsxrb.foreach("large_file.xlsx", sheet: 0) do |row|
+  puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
 end
 ```
 
-### Document Properties (Core, App, and Custom)
+*(For In-Memory document building, cell modifications, or template updating, please refer to the detailed RDoc API documentation).*
 
-Embed metadata into the XLSX file's document properties panels.
+## Feature Support & ECMA-376 Compliance
 
-```ruby
-Xlsxrb.generate("with_props.xlsx") do |w|
-  w.add_sheet("Sheet1") { |s| s.add_row(["Hello"]) }
-
-  # Core properties (Dublin Core — visible in File > Info)
-  w.set_core_property(:title,    "Quarterly Report")
-  w.set_core_property(:subject,  "Sales data Q1 2026")
-  w.set_core_property(:creator,  "Alice")
-  w.set_core_property(:keywords, "sales, report, 2026")
-  w.set_core_property(:description, "Auto-generated by xlsxrb")
-
-  # App properties (application-level metadata)
-  w.set_app_property(:application, "MyApp/2.0")
-  w.set_app_property(:company,     "Acme Corp")
-
-  # Custom properties (arbitrary key/value pairs)
-  w.add_custom_property("ReportVersion", "42", type: :integer)
-  w.add_custom_property("ApprovedBy",    "Bob", type: :string)
-  w.add_custom_property("Published",     true,  type: :bool)
-end
-```
+`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:
 
-This project aims to be compliant with [ECMA-376](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) (Office Open XML file formats). Specifically, the library targets the **Transitional** version of the specification rather than the **Strict** version. The Transitional version (detailed in Part 4) is the format most commonly produced and consumed by existing spreadsheet applications, making it the practical choice for real-world interoperability.
+* 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).
 
 For detailed specification references and policies, see [SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
 
 ## Benchmarks
 
-The following benchmarks measure the time and memory required to process both 100,000 cells (10,000 rows × 10 columns) and 1,000,000 cells (100,000 rows × 10 columns) XLSX files, averaged over 5 iterations on Ruby 3.4+.
-
-### Write Performance (100,000 cells)
-
-| Library                | Time   | Peak Memory | GC Count |
-| ---------------------- | ------ | ----------- | -------- |
-| xlsxtream (Streaming)  | 0.15 s | 65.0 MB     | 4.4      |
-| fast_excel (Streaming) | 0.28 s | 64.4 MB     | 2.0      |
-| xlsxrb (Streaming)     | 0.34 s | 64.4 MB     | 19.0     |
-| caxlsx (In-Memory)     | 1.19 s | 73.8 MB     | 5.0      |
-| xlsxrb (In-Memory)     | 3.06 s | 132.4 MB    | 34.0     |
-| rubyXL (In-Memory)     | 5.45 s | 274.8 MB    | 33.0     |
-
-### Read Performance (100,000 cells)
-
-| Library            | Time   | Peak Memory | GC Count |
-| ------------------ | ------ | ----------- | -------- |
-| xlsxrb (Streaming) | 1.02 s | 67.4 MB     | 192.0    |
-| creek (Streaming)  | 1.32 s | 160.4 MB    | 396.8    |
-| roo (Streaming)    | 1.33 s | 87.4 MB     | 31.0     |
-| xlsxrb (In-Memory) | 1.82 s | 153.9 MB    | 20.0     |
-| xsv (Streaming)    | 3.51 s | 92.1 MB     | 98.0     |
-| rubyXL (In-Memory) | 4.95 s | 265.9 MB    | 38.0     |
+The following benchmarks measure the time and memory required to process a 1,000,000 cells (100,000 rows × 10 columns) spreadsheet, demonstrating `xlsxrb`'s memory consumption and processing times.
 
 ### Write Performance (1,000,000 cells)
 
 | Library                | Time    | Peak Memory | GC Count |
 | ---------------------- | ------- | ----------- | -------- |
-| xlsxtream (Streaming)  | 0.11 s  | 65.1 MB     | 4.2      |
-| fast_excel (Streaming) | 2.26 s  | 64.4 MB     | 28.0     |
-| xlsxrb (Streaming)     | 3.82 s  | 79.0 MB     | 199.0    |
-| caxlsx (In-Memory)     | 4.52 s  | 142.9 MB    | 15.6     |
-| xlsxrb (In-Memory)     | 11.61 s | 454.5 MB    | 61.4     |
-| rubyXL (In-Memory)     | 86.63 s | 2072.0 MB   | 91.4     |
+| xlsxtream (Streaming)  | 0.12 s  | 64.9 MB     | 9.0      |
+| fast_excel (Streaming) | 1.34 s  | 64.5 MB     | 28.0     |
+| caxlsx (In-Memory)     | 2.64 s  | 142.7 MB    | 16.0     |
+| xlsxrb (Streaming)     | 3.32 s  | 216.9 MB    | 65.0     |
+| xlsxrb (In-Memory)     | 6.23 s  | 431.2 MB    | 68.0     |
+| rubyXL (In-Memory)     | 37.16 s | 2105.9 MB   | 90.0     |
 
 ### Read Performance (1,000,000 cells)
 
 | Library            | Time    | Peak Memory | GC Count |
 | ------------------ | ------- | ----------- | -------- |
-| xlsxrb (Streaming) | 11.05 s | 102.9 MB    | 582.0    |
-| roo (Streaming)    | 13.20 s | 127.9 MB    | 233.4    |
-| xsv (Streaming)    | 15.35 s | 94.3 MB     | 984.4    |
-| creek (Streaming)  | 15.69 s | 706.5 MB    | 3974.6   |
-| xlsxrb (In-Memory) | 25.23 s | 991.7 MB    | 41.4     |
-| rubyXL (In-Memory) | 56.26 s | 1858.3 MB   | 127.0    |
-
-For reference, the following specification files from the Ecma International website are located in the `vendor/docs/` directory:
-
-- `vendor/docs/ECMA-376-Part1/Ecma Office Open XML Part 1 - Fundamentals And Markup Language Reference.pdf`: Part 1 - Fundamentals And Markup Language Reference
-- `vendor/docs/ECMA-376-Part2/ECMA-376-2_5th_edition_december_2021.pdf`: Part 2 - Open Packaging Conventions
-- `vendor/docs/ECMA-376-Part3/ECMA-376-3_5th_edition_december_2015.pdf`: Part 3 - Markup Compatibility and Extensibility
-- `vendor/docs/ECMA-376-Part4/Ecma Office Open XML Part 4 - Transitional Migration Features.pdf`: Part 4 - Transitional Migration Features
-
-## Testing Strategy
-
-To ensure high quality and strict compliance with the ECMA-376 specification while maintaining a fast development loop, we employ a 4-tier testing strategy:
-
-1. **Unit Tests (Fast & No Dependencies):**
-   - Verify individual components (Writer, Reader, Packaging) using only the Ruby standard library and bundled gems.
-   - **Round-Trip Testing:** Ensure that files generated by the `xlsxrb` Writer can be seamlessly and accurately parsed back by the `xlsxrb` Reader.
-   - Run via: `bundle exec rake test:unit`
-
-2. **Contract Tests (API Consistency):**
-   - Execute the same data scenario through both the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build` + `Xlsxrb.write`) APIs.
-   - Verify that both APIs produce semantically identical OOXML output.
-   - Run via: `bundle exec rake test:contract`
-
-3. **Interoperability Testing (E2E):**
-   - Utilize the official **[Open XML SDK](https://github.com/dotnet/Open-XML-SDK)** for robust, two-way verification:
-     - **Writer Validation:** Files generated by `xlsxrb` are read and validated using the Open XML SDK validator.
-     - **Reader Validation:** Complex, real-world XLSX files generated by the SDK are parsed and verified by the `xlsxrb` reader.
-   - Requires `.NET SDK`.
-   - Run via: `bundle exec rake test:e2e`
-
-4. **Visual Examples & VRT (Visual Regression Testing):**
-   - **Visual Gallery:** Automatically compiles example DSL scripts under `examples/visual/` into the [Visual Examples Gallery](docs/visual/VisualGallery.md).
-   - **Visual Regression Testing:** Renders generated spreadsheets to PNGs using a headless LibreOffice Calc engine, and compares them against baselines to catch rendering errors or layout regressions.
-   - Requires `libreoffice-calc`, `poppler-utils` (`pdftoppm`), and `imagemagick`.
-   - Run via: `bundle exec rake test:visual`
-
-**Note on Test Environments:**
-All necessary dependencies (.NET SDK, LibreOffice, etc.) are pre-configured in the repository's **Dev Container** setup for a consistent local and CI experience.
-
-## Development
-
-This project is designed to be developed using [Dev Containers](https://containers.dev/). The provided `.devcontainer` configuration includes all necessary tools (Ruby 4.0, and the .NET SDK for E2E testing) to ensure a consistent development environment.
+| xlsxrb (Streaming) | 5.38 s  | 101.8 MB    | 1429.0   |
+| creek (Streaming)  | 7.05 s  | 706.2 MB    | 3985.0   |
+| roo (Streaming)    | 7.24 s  | 128.1 MB    | 279.0    |
+| xlsxrb (In-Memory) | 8.62 s  | 996.1 MB    | 28.0     |
+| xsv (Streaming)    | 14.41 s | 93.5 MB     | 998.0    |
+| rubyXL (In-Memory) | 24.58 s | 1856.8 MB   | 127.0    |
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Running the Benchmarks Locally
 
-### Development Workflow
+The benchmark data is gathered using the bundled [benchmark.rb](file:///workspaces/xlsxrb/benchmark.rb) script, which runs each library's code in isolated subprocesses to ensure accurate memory and GC measurements.
 
-High-level API expansion follows the Facade rules documented in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). In short: if a low-level writer feature is stable, the default expectation is that it should eventually be exposed through the high-level DSL as well, with consistent naming, both streaming and in-memory coverage, backward-compatible options/block forms where practical, and matching Facade-level tests.
+To run the benchmark locally for 1,000,000 cells (100,000 rows):
+```bash
+ruby benchmark.rb 100000
+```
 
-To ensure systematic progress, perfect round-trip compatibility, and strict adherence to the ECMA-376 specification, we follow this iterative development cycle for each new feature:
+## Testing & Quality Assurance
 
-1.  **Select a Feature:** Choose a specific element or behavior from the specification to implement.
-2.  **Writer Unit Tests:** Write unit tests for the Writer component targeting this feature.
-3.  **Writer Implementation:** Implement the Writer functionality.
-4.  **Run Writer Tests:** Execute the Writer unit tests. If they fail, return to step 3.
-5.  **Writer E2E & Validation:** Test the Writer's generated XLSX file using the Open XML SDK. This includes structural validation using `OpenXmlValidator`. If the test or validation fails, return to step 2.
-6.  **Reader Unit Tests:** Write unit tests for the Reader component. **Crucially, include round-trip tests** to ensure the Reader can perfectly parse the output of your Writer.
-7.  **Reader Implementation:** Implement the Reader functionality.
-8.  **Run Reader Tests:** Execute the Reader unit tests. If they fail, return to step 6 or 7. If the round-trip test reveals a structural flaw in the Writer's output, return all the way back to step 2.
-9.  **Reader E2E:** Verify that the Reader can successfully parse a valid XLSX file generated by the Open XML SDK that includes the new feature. If it fails, return to step 6 or 7.
-10. **Full Test Suite:** Run the entire test suite (`rake test`). If any tests fail, trace back to the appropriate step.
-11. **Commit:** Commit the changes. The commit message must clearly describe the specific feature implemented in this cycle.
-12. **Next Feature:** Proceed to the next feature and return to step 1.
+To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a 4-tier testing strategy:
 
-#### E2E Policy
+1. Round-Trip Testing: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
+2. Contract Consistency: The library ensures semantic output consistency between the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build`) APIs.
+3. Official Open XML SDK Validation (E2E): Every feature is validated against the official Microsoft Open XML SDK. Generated spreadsheets are structurally checked to prevent file corruption warnings.
+4. Visual Regression Testing (VRT): To guarantee rendering correctness, generated XLSX files are rendered via a headless LibreOffice Calc engine, and compared pixel-by-pixel against visual baselines.
 
-E2E tests are required for every new feature. Omitting them is the exception, not the rule, and requires explicit justification.
+For details on running the tests locally or within our pre-configured Dev Container, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
-A strong signal that E2E should not be omitted: if you are adding a new XML element, a new attribute on a top-level structure, or a new public API parameter, E2E is expected.
+## Development
 
-Omission is only acceptable when **all** of the following hold:
+We welcome contributions! The project is configured with a ready-to-use Dev Container to streamline local environment setup.
 
-1. The change adds a minor attribute to an XML structure that is **already exercised end-to-end** by an existing E2E scenario for the same element.
-2. No new XML element or branch is introduced.
-3. Unit tests and round-trip tests fully cover the new behaviour.
-4. `rake test` passes with Open XML SDK validation included.
-5. The commit message explicitly names the existing E2E scenario that provides coverage and states why a new scenario adds no value.
+For contribution guidelines, E2E testing policies, and the step-by-step development workflow, 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).
 

data/Rakefile

@@ -291,15 +291,119 @@ task :wasm do
   end
 end
 
+desc "Fetch required external assets for offline usage"
+task :fetch_assets do
+  require 'open-uri'
+  require 'fileutils'
+
+  def download_file(url, dest)
+    # Check if the file exists and is not a tiny placeholder/error document
+    return if File.exist?(dest) && File.size(dest) > 1024
+
+    puts "Downloading #{url} to #{dest}..."
+    FileUtils.mkdir_p(File.dirname(dest))
+
+    require 'net/http'
+    uri = URI.parse(url)
+    temp_dest = dest + ".tmp"
+
+    begin
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 15, read_timeout: 90) do |http|
+        request = Net::HTTP::Get.new(uri)
+        # Specify User-Agent to bypass scraping prevention on CDNs and act as a normal browser
+        request['User-Agent'] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+        # Force raw (identity) encoding to prevent receiving Brotli-compressed (.br) data,
+        # which Ruby's Net::HTTP cannot decode automatically, leading to corrupted Wasm files.
+        request['Accept-Encoding'] = 'identity'
+
+        http.request(request) do |response|
+          if response.code.to_i != 200
+            raise "HTTP error #{response.code}: #{response.message}"
+          end
+
+          File.open(temp_dest, "wb") do |output|
+            response.read_body do |chunk|
+              output.write(chunk)
+            end
+          end
+        end
+      end
+      # Atomic rename to prevent leaving incomplete files on failure
+      File.rename(temp_dest, dest)
+      puts "Downloaded successfully."
+    rescue => e
+      puts "Failed to download #{url}: #{e.message}"
+      File.delete(temp_dest) if File.exist?(temp_dest)
+      File.delete(dest) if File.exist?(dest)
+      raise "Required asset download failed. Build aborted."
+    end
+  end
+
+  def fetch_google_fonts
+    css_dest = "docs/fonts/fonts.css"
+    return if File.exist?(css_dest)
+
+    puts "Fetching and localizing Google Fonts..."
+    font_url = "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
+
+    css_content = nil
+    begin
+      # Specify Chrome User-Agent to ensure Google Fonts returns modern and lightweight .woff2 formats
+      # instead of legacy formats (like .ttf or .eot) designed for older browsers
+      URI.open(font_url, "User-Agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36") do |f|
+        css_content = f.read
+      end
+    rescue => e
+      puts "Failed to fetch Google Fonts CSS: #{e.message}"
+      return
+    end
+
+    urls = css_content.scan(/url\((https:\/\/fonts\.gstatic\.com\/[^\)]+)\)/).flatten
+
+    urls.uniq.each do |url|
+      filename = url.split("/").last
+      local_path = "docs/fonts/#{filename}"
+      download_file(url, local_path)
+      css_content.gsub!(url, filename)
+    end
+
+    FileUtils.mkdir_p("docs/fonts")
+    File.write(css_dest, css_content)
+    puts "Google Fonts localized successfully."
+  end
+
+  # Fetch Ruby WASI JS
+  download_file(
+    "https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@2.9.3-2.9.4/dist/browser.umd.js",
+    "docs/wasm/browser.umd.js"
+  )
+
+  # Fetch ZetaOffice Wasm
+  base_zeta_url = "https://cdn.zetaoffice.net/zetaoffice_latest/"
+  %w[soffice.js soffice.wasm soffice.data soffice.data.js.metadata qtloader.js].each do |file|
+    download_file(base_zeta_url + file, "docs/zetaoffice/#{file}")
+  end
+
+  # Fetch and localize Google Fonts
+  fetch_google_fonts
+end
+
 desc "Generate RDoc documentation including Visual Gallery"
-task doc: :wasm do
+task doc: [:wasm, :fetch_assets] do
   FileUtils.rm_rf("doc")
-  sh "bundle exec rdoc --title 'xlsxrb Documentation' --main README.md README.md \"docs/visual/VisualGallery.md\" lib/"
+
+  # RDoc コマンドを実行 (--exclude を指定して docs 配下のプレビュー用アセットの誤パースを回避)
+  sh "bundle exec rdoc --op doc" \
+     " --exclude 'docs/coi-serviceworker\\.js'" \
+     " --exclude 'docs/zeta\\.js'" \
+     " --exclude 'docs/office_thread\\.js'" \
+     " --exclude 'docs/preview\\.html'" \
+     " --title 'xlsxrb Documentation' --main README.md README.md \"docs/visual/VisualGallery.md\" lib/"
 
   # Copy visual gallery images and files so they are available in RDoc output
   FileUtils.mkdir_p("doc/test/visual/baselines")
-  FileUtils.cp_r("test/visual/baselines", "doc/test/visual")
   FileUtils.mkdir_p("doc/test/visual/support/illustrations")
+  FileUtils.cp_r(Dir.glob("test/visual/baselines/*"), "doc/test/visual/baselines")
   FileUtils.cp_r(Dir.glob("test/visual/support/illustrations/*.png"), "doc/test/visual/support/illustrations")
 
   FileUtils.mkdir_p("doc/docs/visual/files")
@@ -312,21 +416,35 @@ task doc: :wasm do
   FileUtils.mkdir_p("doc/css")
   FileUtils.mkdir_p("doc/js")
   FileUtils.mkdir_p("doc/wasm")
+  FileUtils.mkdir_p("doc/zetaoffice")
+  FileUtils.mkdir_p("doc/fonts")
+
   FileUtils.cp("docs/wasm/wasm_doc_helper.js", "doc/js/wasm_doc_helper.js")
   FileUtils.cp("docs/wasm/wasm_doc_helper.css", "doc/css/wasm_doc_helper.css")
   FileUtils.cp("docs/wasm/ruby.wasm", "doc/wasm/ruby.wasm")
+  FileUtils.cp("docs/wasm/browser.umd.js", "doc/wasm/browser.umd.js")
+  FileUtils.cp_r(Dir.glob("docs/zetaoffice/*"), "doc/zetaoffice")
+  FileUtils.cp_r(Dir.glob("docs/fonts/*"), "doc/fonts")
+
+  # Copy LibreOffice Wasm Preview assets to doc directory
+  FileUtils.cp("docs/preview.html", "doc/preview.html")
+  FileUtils.cp("docs/coi-serviceworker.js", "doc/coi-serviceworker.js")
+  FileUtils.cp("docs/zeta.js", "doc/zeta.js")
+  FileUtils.cp("docs/office_thread.js", "doc/office_thread.js")
 
   # Inject stylesheet and javascript loading tags to all generated HTML docs
   Dir.glob("doc/**/*.html").each do |html_path|
+    next if File.basename(html_path) == "preview.html"
     html_content = File.read(html_path)
     depth = html_path.sub(%r{\Adoc/}, "").count("/")
     rel_prefix = "../" * depth
 
+    coi_tag = %Q{<script src="#{rel_prefix}coi-serviceworker.js"></script>}
     js_tag = %Q{<script src="#{rel_prefix}js/wasm_doc_helper.js" defer></script>}
     css_tag = %Q{<link href="#{rel_prefix}css/wasm_doc_helper.css" rel="stylesheet">}
 
     if html_content.include?("<body")
-      modified = html_content.sub("<body", "#{js_tag}\n#{css_tag}\n<body")
+      modified = html_content.sub("<body", "#{coi_tag}\n#{js_tag}\n#{css_tag}\n<body")
       File.write(html_path, modified)
     end
   end
@@ -346,7 +464,21 @@ namespace :doc do
       Port: port,
       DocumentRoot: File.expand_path("doc", __dir__),
       Logger: WEBrick::Log.new(nil, WEBrick::BasicLog::WARN),
-      AccessLog: []
+      AccessLog: [],
+      # If the file is a Brotli-compressed Wasm/Data asset (checked via magic bytes),
+      # dynamically inject 'Content-Encoding: br' header so the browser decompresses it natively.
+      RequestCallback: ->(req, res) {
+        if req.path.end_with?(".wasm") || req.path.end_with?(".data")
+          # Resolve physical file path from req.path manually since res.filename is nil at this stage
+          local_path = File.join(File.expand_path("doc", __dir__), req.path)
+          if File.exist?(local_path)
+            first_4 = File.binread(local_path, 4) rescue nil
+            if first_4 != "\x00asm"
+              res['Content-Encoding'] = 'br'
+            end
+          end
+        end
+      }
     )
 
     puts "=================================================="