xlsxrb 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf81256a8c23f02b4ef5a1f2efb91122850960da349cc1c00bce37d4055486ac
-  data.tar.gz: c0fdb2a48e67beb7a59730fe947ca819c5ed72196c858b02a430cb5f85e953c5
+  metadata.gz: 15a818d0e9e58b9ada1a11c90db9f9baa55fc76b3a7e62303d33a61f2e6f9896
+  data.tar.gz: c7b5f4af516d9911a1ee37ef5413939e8425bc270304900132e0962fad18905d
 SHA512:
-  metadata.gz: a4e3b7098c50d3d9e5958333f49ad2b8c22399f383067c01b0481fb82e9d1eaa50481de15afe8b2b883d6f0ee1697144ae55d028771eeca159cc38f46626043f
-  data.tar.gz: 25c3979864c017334256986e5697c793f40b22b3cdc7419d18e3ef090925f0297909ca8fafc9188cf37769344e656fa7e900cf8da8f3a310599e1cd9ab61ed8b
+  metadata.gz: 9deec47109a21a62aafb4a93efcee64f61f5ffb4566fd009cd1d5fdb9557e1193a53155d60ff7e4cc565317d49fb4ce8b3b89542234dff6a900981cd9220d14a
+  data.tar.gz: b536ef03e3ae01c49ff8e00c693d86fb72a9248cae1ccf93802962127d9b86ef676b5b17ca4b896613961bab8869139644e439542b1bca5adb6a7452d971f124

data/.mutant.yml

@@ -0,0 +1,8 @@
+usage: opensource
+requires:
+  - test_helper
+  - xlsxrb
+includes:
+  - lib
+  - test
+integration: test-unit

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [0.1.12] - 2026-09-20
+
+### Added
+- **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.
+  - 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`.
+
+### Changed
+- **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).
+    - 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`).
+  - Extracted shared DSL parameter normalization and range expansion into `Xlsxrb::DslHelpers`.
+  - Modularized reader SAX listeners into domain-specific parser components.
+
+### Fixed
+- **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**:
+  - 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.).
+  - Handled `RBS::Test::Tester::TypeError` in unit tests verifying block return type validation.
+
 ## [0.1.11] - 2026-08-19
 
 ### Performance

data/README.md

@@ -166,6 +166,7 @@ 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.
 
 For full architectural details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md).

data/Rakefile

@@ -462,6 +462,12 @@ task doc: %i[wasm fetch_assets] do
   FileUtils.mkdir_p("doc/docs/visual/files")
   FileUtils.cp_r(Dir.glob("docs/visual/files/*"), "doc/docs/visual/files")
 
+  FileUtils.mkdir_p("doc/docs/assets")
+  FileUtils.cp_r(Dir.glob("docs/assets/*"), "doc/docs/assets")
+
+  # Alias index.html as README_md.html for links referencing README.md
+  FileUtils.cp("doc/index.html", "doc/README_md.html") if File.exist?("doc/index.html")
+
   # --- WebAssembly Playground Integration ---
   puts "Integrating WebAssembly Playground..."
 
@@ -565,3 +571,63 @@ desc "Run static type checking with Steep"
 task typecheck: :sig do
   sh "bundle exec steep check"
 end
+
+namespace :mutant do
+  desc "Run mutation testing on pure logic and algorithms (coordinates, serial, conversion)"
+  task :pure do
+    default_subjects = [
+      "Xlsxrb::Elements::CoordinateAccess#cells",
+      "Xlsxrb::Elements::CoordinateAccess#[]",
+      "Xlsxrb::Elements::Cell#ref",
+      "Xlsxrb::Elements::Cell#to_i",
+      "Xlsxrb::Elements::Cell#to_f",
+      "Xlsxrb::Elements::Cell#content",
+      "Xlsxrb::Elements::Cell#to_s",
+      "Xlsxrb::Elements::Cell#valid?",
+      "Xlsxrb::Elements::Cell.calculate_column_letter",
+      "Xlsxrb::Elements::Cell.calculate_column_index",
+      "Xlsxrb::Elements::Cell.valid_coordinates?",
+      "Xlsxrb::Elements::Cell.valid_value?",
+      "Xlsxrb::Ooxml::Utils.serial_to_date",
+      "Xlsxrb::Ooxml::Utils.date_to_serial",
+      "Xlsxrb::Ooxml::Utils.datetime_to_serial",
+      "Xlsxrb::Ooxml::Utils.serial_to_datetime",
+      "Xlsxrb::Ooxml::ZipGenerator.le16",
+      "Xlsxrb::Ooxml::ZipGenerator.le32",
+      "Xlsxrb::StreamRow#valid?",
+      "Xlsxrb::StreamRow#unmapped_data",
+      "Xlsxrb::StreamRow#errors",
+      "Xlsxrb::StreamRow#values",
+      "Xlsxrb::Elements::Worksheet.valid_name?",
+      "Xlsxrb::Elements::Worksheet#valid?",
+      "Xlsxrb::Elements::Worksheet#load",
+      "Xlsxrb::Ooxml::Cfb::Reader.cfb?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#stream?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#root?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#storage?",
+      "Xlsxrb::Elements::Column.valid_index?",
+      "Xlsxrb::Elements::Column.validate",
+      "Xlsxrb::Elements::Column#valid?",
+      "Xlsxrb::Elements::Row.valid_index?",
+      "Xlsxrb::Elements::Row#valid?",
+      "Xlsxrb::Elements::Workbook#valid?",
+      "Xlsxrb::Ooxml::XmlBuilder.escape",
+      "Xlsxrb::Ooxml::ZipGenerator.dos_datetime",
+      "Xlsxrb::DslHelpers.normalize_column_indices"
+    ].join(" ")
+    subjects = ENV["MUTANT_SUBJECTS"] || default_subjects
+    test_files = [
+      "./test/xlsxrb/elements_test.rb",
+      "./test/xlsxrb/ooxml_test.rb",
+      "./test/xlsxrb/ooxml/utils_test.rb",
+      "./test/xlsxrb/ooxml/crypto_test.rb",
+      "./test/xlsxrb/ooxml/cfb_test.rb",
+      "./test/zip_generator_test.rb",
+      "./test/xlsxrb/stream_row_test.rb",
+      "./test/xlsxrb/style_builder_test.rb",
+      "./test/xlsxrb/dsl_helpers_test.rb"
+    ].select { |f| File.exist?(f) }
+    requires = test_files.map { |f| "-r #{f}" }.join(" ")
+    sh "bundle exec mutant run --usage opensource #{requires} -- #{subjects}"
+  end
+end

data/docs/ARCHITECTURE.md

@@ -509,6 +509,6 @@ To ensure library robustness and consistency across execution paths, we organize
    - Run via: `bundle exec rake test:e2e`
 
 4. **Visual Examples & VRT (`test/visual/`):**
-   - **Living Documentation:** Compiles visual DSL scripts under `examples/visual/` into the [Visual Examples Gallery](visual/README.md).
+   - **Living Documentation:** Compiles visual DSL scripts under `examples/visual/` into the [Visual Examples Gallery](visual/VisualGallery.md).
    - **Visual Regression Testing:** Renders the generated spreadsheets into PNG files using headless LibreOffice Calc, and calculates pixel differences against reference baselines using ImageMagick.
    - Run via: `bundle exec rake test:visual`

data/docs/DEVELOPMENT.md

@@ -32,7 +32,11 @@ To run the different tiers of our testing strategy:
    ```bash
    bundle exec rake test:visual
    ```
-7. **Run All Tests:**
+7. **Mutation Testing (Pure Logic & Algorithms):**
+   ```bash
+   bundle exec rake mutant:pure
+   ```
+8. **Run All Tests:**
    ```bash
    bundle exec rake test
    ```
@@ -41,7 +45,7 @@ To run the different tiers of our testing strategy:
 
 ## Development Workflow
 
-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.
+High-level API expansion follows the Facade rules documented in [ARCHITECTURE.md](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 ensure systematic progress, reliable round-trip compatibility, and strict adherence to the ECMA-376 specification, we follow this iterative development cycle for each new feature:
 

data/docs/MUTATION_TESTING.md

@@ -0,0 +1,52 @@
+# Mutation Testing in xlsxrb
+
+To ensure enterprise-grade reliability and avoid "shallow test coverage" (where line coverage is high but assertions are missing or weak), `xlsxrb` adopts **Mutation Testing** via [`mbj/mutant`](https://github.com/mbj/mutant) with `test-unit` integration.
+
+As of the current release, the test suite achieves **100.00% kill rate (1,091 / 1,091 mutations killed, 0 alive)** across all 38 pure functional subjects.
+
+## Motivation & Strategy
+
+Standard code coverage measures whether lines of code were executed during tests. However, it cannot guarantee that the tests will fail if the code's behavior is altered or corrupted. Mutation testing systematically modifies source code (introducing "mutants" such as flipping conditionals, substituting constants, or removing statements) and checks whether existing tests catch the mutation ("kill" the mutant).
+
+### Targeted Scope: Functional Core, Pure Predicates & Byte Encoding
+
+Running mutation testing across the entire codebase (which includes heavy file I/O, ZIP streaming, and large XML parsing) is computationally expensive and prone to creating brittle tests for streaming writers. Therefore, `xlsxrb` follows the **Functional Core / Imperative Shell** architecture, focusing mutation testing strictly on pure functions, boundary predicates, coordinate conversions, and binary encoders:
+
+1. **Coordinates & Cell Conversions (`Xlsxrb::Elements::Cell`, `CoordinateAccess`)**:
+   - Column letters to 0-based indices (`"A"` ↔ `0`, `"Z"` ↔ `25`, `"AA"` ↔ `26`, up to `"XFD"` ↔ `16383`).
+   - Pure predicate checks (`Cell.valid_coordinates?`, `Cell.valid_value?`, `Cell#valid?`).
+   - String, integer, and float conversions (`Cell#to_s`, `Cell#to_i`, `Cell#to_f`, `Cell#content`, `Cell#ref`).
+   - Coordinate access references and cell sorting (`CoordinateAccess#cells`, `CoordinateAccess#[]`).
+2. **Worksheet, Column, Row & Workbook Invariants (`Xlsxrb::Elements::*`, `Xlsxrb::StreamRow`)**:
+   - Worksheet name validation (`Worksheet.valid_name?` with 1..31 characters and forbidden character rules `\ / ? * [ ]`).
+   - Column and row bounds (`Column.valid_index?`, `Column.validate`, `Column#valid?`, `Row.valid_index?`, `Row#valid?`).
+   - Workbook structure validation (`Workbook#valid?`).
+   - Streaming row data integrity (`StreamRow#valid?`, `StreamRow#unmapped_data`, `StreamRow#errors`, `StreamRow#values`).
+3. **Serial Value & DateTime Conversions (`Xlsxrb::Ooxml::Utils`)**:
+   - Julian Day ↔ 1900-based serial number conversions (`date_to_serial`, `serial_to_date`).
+   - Time fractions and fractional days arithmetic (`datetime_to_serial`, `serial_to_datetime`).
+   - Excel 1900 leap year bug handling.
+4. **Binary Parsing & Bitfield Packings (`Xlsxrb::Ooxml::ZipGenerator`, `Xlsxrb::Ooxml::Cfb`)**:
+   - Little-endian 16/32-bit byte serialization (`ZipGenerator.le16`, `ZipGenerator.le32`).
+   - MS-DOS packed datetime calculation with arithmetic bitfield combinations (`ZipGenerator.dos_datetime`).
+   - Compound File Binary (CFB) magic header recognition (`Cfb::Reader.cfb?`) and directory entry predicates (`DirEntry#stream?`, `#root?`, `#storage?`).
+5. **XML Character Escaping (`Xlsxrb::Ooxml::XmlBuilder`)**:
+   - Pure escaping of XML special characters (`XmlBuilder.escape`) with object identity preservation for clean strings.
+6. **DSL Normalization (`Xlsxrb::DslHelpers`)**:
+   - Column indices, range, and alphabet normalization (`DslHelpers.normalize_column_indices`).
+
+### Excluded Scope (Non-Targets)
+
+- **Streaming XML Writers & Parsers**: Validated via Microsoft Open XML SDK schema checks and round-trip parsing tests rather than mutant to avoid brittle assertions.
+- **Visual Regression Testing (VRT)**: Headless rendering with LibreOffice Calc is validated via image diffs in CI.
+- **Cryptographic Key Stretching**: Password hashing with 100,000 spin iterations is validated by specific contract tests to avoid slow feedback cycles.
+
+## Running Mutation Testing
+
+```bash
+# Run full mutation testing suite (38 subjects, ~35 seconds)
+bundle exec rake mutant:pure
+
+# Or run mutant against a specific class or method using .mutant.yml configuration
+bundle exec mutant run -- 'Xlsxrb::Elements::Cell.valid_value?'
+```

data/docs/QUALITY_ASSURANCE.md

@@ -15,6 +15,7 @@ Below is an overview of the inspection mechanisms, when they run, the quality at
 | **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)** | `rake test:pbt` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
+| **Mutation Testing (Mutant)** | `rake mutant:pure` | ⭕ | ⭕ | - | Test Suite Rigor / Detection Power | Fault Injection / Mutation Analysis (100% kill on 1,091 mutants) | Shallow tests, unasserted edge cases, and surviving mutant bugs in pure algorithms, predicates, and coordinates logic. |
 | **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. |

data/docs/visual/VisualGallery.md

@@ -1136,8 +1136,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Positive Yen" (Format ID: , Code: nil), B2: 12500 (Format ID: 164, Code: "¥#,##0;[Red]¥-#,##0")
-Row 2: A3: "Negative Yen" (Format ID: , Code: nil), B3: -8000 (Format ID: 164, Code: "¥#,##0;[Red]¥-#,##0")
+Row 1: A2: "Positive Yen" (Format ID: , Code: nil), B2: 12500 (Format ID: 166, Code: "¥#,##0;[Red]¥-#,##0")
+Row 2: A3: "Negative Yen" (Format ID: , Code: nil), B3: -8000 (Format ID: 166, Code: "¥#,##0;[Red]¥-#,##0")
 ```
 
 <hr/>
@@ -1187,8 +1187,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Positive (Green)" (Format ID: , Code: nil), B2: 5000 (Format ID: 164, Code: "[Green]#,##0;[Red]-#,##0")
-Row 2: A3: "Negative (Red)" (Format ID: , Code: nil), B3: -2500 (Format ID: 164, Code: "[Green]#,##0;[Red]-#,##0")
+Row 1: A2: "Positive (Green)" (Format ID: , Code: nil), B2: 5000 (Format ID: 166, Code: "[Green]#,##0;[Red]-#,##0")
+Row 2: A3: "Negative (Red)" (Format ID: , Code: nil), B3: -2500 (Format ID: 166, Code: "[Green]#,##0;[Red]-#,##0")
 ```
 
 <hr/>
@@ -1239,9 +1239,9 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Half" (Format ID: , Code: nil), B2: 0.5 (Format ID: 164, Code: "# ?/?")
-Row 2: A3: "Third" (Format ID: , Code: nil), B3: 0.3333 (Format ID: 164, Code: "# ?/?")
-Row 3: A4: "Quarter" (Format ID: , Code: nil), B4: 0.75 (Format ID: 164, Code: "# ?/?")
+Row 1: A2: "Half" (Format ID: , Code: nil), B2: 0.5 (Format ID: 166, Code: "# ?/?")
+Row 2: A3: "Third" (Format ID: , Code: nil), B3: 0.3333 (Format ID: 166, Code: "# ?/?")
+Row 3: A4: "Quarter" (Format ID: , Code: nil), B4: 0.75 (Format ID: 166, Code: "# ?/?")
 ```
 
 <hr/>
@@ -1290,7 +1290,7 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Percent with 2 Decimals" (Format ID: , Code: nil), B2: 0.12345 (Format ID: 164, Code: "0.00%")
+Row 1: A2: "Percent with 2 Decimals" (Format ID: , Code: nil), B2: 0.12345 (Format ID: 166, Code: "0.00%")
 ```
 
 <hr/>
@@ -1340,8 +1340,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Scientific" (Format ID: , Code: nil), B2: 123456789.0 (Format ID: 164, Code: "0.00E+00")
-Row 2: A3: "Small Scientific" (Format ID: , Code: nil), B3: 1.234e-05 (Format ID: 164, Code: "0.00E+00")
+Row 1: A2: "Scientific" (Format ID: , Code: nil), B2: 123456789.0 (Format ID: 166, Code: "0.00E+00")
+Row 2: A3: "Small Scientific" (Format ID: , Code: nil), B3: 1.234e-05 (Format ID: 166, Code: "0.00E+00")
 ```
 
 <hr/>
@@ -2867,8 +2867,6 @@ Visual demonstration for Drawing Shapes.
 
 <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
@@ -2880,12 +2878,12 @@ 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.column(0..4, width: 12)
     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)
+    sheet.shape(preset: "rect", text: "Start", from_col: 0, from_row: 2, to_col: 1, to_row: 4)
+    sheet.shape(preset: "rightArrow", text: "Next", from_col: 1, from_row: 3, to_col: 2, to_row: 4)
+    sheet.shape(preset: "roundRect", text: "Processing", from_col: 2, from_row: 2, to_col: 4, to_row: 4)
   end
 end
 
@@ -4082,8 +4080,6 @@ Visual demonstration for Pivot Table.
 
 <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
@@ -4095,7 +4091,7 @@ 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.column(0..3, width: 14)
     sheet.row(%w[Region Quarter Sales Rep])
     sheet.row(["East", "Q1", 1000, "Alice"])
     sheet.row(["West", "Q1", 1500, "Bob"])
@@ -4104,12 +4100,22 @@ Xlsxrb.write(output_path) do |wb|
     sheet.row(["North", "Q1", 800, "Charlie"])
     sheet.row(["North", "Q2", 950, "Charlie"])
 
+    sheet.row([])
+    sheet.row([])
+    # Pre-populate summary cells in the pivot table target region (A10:D15) for headless renderers
+    sheet.row(["Sum of Sales", "Quarter", nil, nil])
+    sheet.row(["Region", "Q1", "Q2", "Grand Total"])
+    sheet.row(["East", 1000, 1200, 2200])
+    sheet.row(["North", 800, 950, 1750])
+    sheet.row(["West", 1500, 1800, 3300])
+    sheet.row(["Grand Total", 3300, 3950, 7250])
+
     sheet.pivot_table(
       "SalesData!A1:D7",
       row_fields: ["Region"],
       data_fields: [{ name: "Sales", subtotal: "sum" }],
       col_fields: ["Quarter"],
-      dest_ref: "F1",
+      dest_ref: "A10",
       name: "RegionalSalesSummary"
     )
   end
@@ -4135,6 +4141,14 @@ 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"
+Row 7: 
+Row 8: 
+Row 9: A10: "Sum of Sales", B10: "Quarter"
+Row 10: A11: "Region", B11: "Q1", C11: "Q2", D11: "Grand Total"
+Row 11: A12: "East", B12: 1000, C12: 1200, D12: 2200
+Row 12: A13: "North", B13: 800, C13: 950, D13: 1750
+Row 13: A14: "West", B14: 1500, C14: 1800, D14: 3300
+Row 14: A15: "Grand Total", B15: 3300, C15: 3950, D15: 7250
 ```
 
 <hr/>
@@ -4494,8 +4508,6 @@ Visual demonstration for Table Styles.
 
 <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
@@ -4507,7 +4519,10 @@ 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.column(0, width: 8)
+    sheet.column(1, width: 16)
+    sheet.column(2, width: 16)
+    sheet.column(3, width: 14)
     sheet.row(%w[ID Name Department Salary])
     sheet.row([101, "Alice Smith", "Engineering", 120_000])
     sheet.row([102, "Bob Jones", "Marketing", 95_000])
@@ -4548,8 +4563,6 @@ Demonstrates disabling visible grid lines in spreadsheet view.
 
 <div><img src="../../test/visual/baselines/view_show_grid_lines/page-1.png" width="100%" alt="Preview"/></div>
 
-<div><img src="../../test/visual/support/illustrations/view_show_grid_lines_page-2.png" width="100%" alt="Preview"/></div>
-
 ### DSL Code
 
 ```ruby
@@ -4593,8 +4606,6 @@ Demonstrates setting custom zoom scale in sheet view (e.g. 150%).
 
 <div><img src="../../test/visual/baselines/view_zoom_scale/page-1.png" width="100%" alt="Preview"/></div>
 
-<div><img src="../../test/visual/support/illustrations/view_zoom_scale_page-2.png" width="100%" alt="Preview"/></div>
-
 ### DSL Code
 
 ```ruby

data/lib/xlsxrb/chart_builder.rb

@@ -80,7 +80,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for legend styling/layout.
     # @return [Object] The configured legend property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def legend(*args, **kwargs)
       @options[:legend] = kwargs.empty? ? args.first : kwargs
     end
@@ -91,7 +91,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for plot area configuration.
     # @return [Object] The configured plot_area property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def plot_area(*args, **kwargs)
       @options[:plot_area] = kwargs.empty? ? args.first : kwargs
     end
@@ -102,7 +102,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured chart_space property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def chart_space(*args, **kwargs)
       @options[:chart_space] = kwargs.empty? ? args.first : kwargs
     end
@@ -113,7 +113,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured style property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String | Integer) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String | Integer)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String | Integer) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String | Integer)
     def style(*args, **kwargs)
       @options[:style] = kwargs.empty? ? args.first : kwargs
     end
@@ -124,7 +124,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured data_labels property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def data_labels(*args, **kwargs)
       @options[:data_labels] = kwargs.empty? ? args.first : kwargs
     end
@@ -135,7 +135,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def plot_visible_only(*args, **kwargs)
       @options[:plot_visible_only] = kwargs.empty? ? args.first : kwargs
     end
@@ -146,7 +146,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [String]
     # @api public
-    #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+    #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
     def display_blanks_as(*args, **kwargs)
       @options[:display_blanks_as] = kwargs.empty? ? args.first : kwargs
     end
@@ -157,7 +157,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def view3d(*args, **kwargs)
       @options[:view3d] = kwargs.empty? ? args.first : kwargs
     end
@@ -168,7 +168,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def category_axis(*args, **kwargs)
       @options[:category_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -179,7 +179,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def value_axis(*args, **kwargs)
       @options[:value_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -190,7 +190,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def show_legend_key(*args, **kwargs)
       @options[:show_legend_key] = kwargs.empty? ? args.first : kwargs
     end
@@ -258,7 +258,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def fill(*args, **kwargs)
         @options[:fill] = kwargs.empty? ? args.first : kwargs
       end
@@ -269,7 +269,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def line(*args, **kwargs)
         @options[:line] = kwargs.empty? ? args.first : kwargs
       end
@@ -280,7 +280,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def trendline(*args, **kwargs)
         @options[:trendline] = kwargs.empty? ? args.first : kwargs
       end
@@ -291,7 +291,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def data_labels(*args, **kwargs)
         @options[:data_labels] = kwargs.empty? ? args.first : kwargs
       end
@@ -302,7 +302,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Boolean, String]
       # @api public
-      #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+      #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
       def smooth(*args, **kwargs)
         @options[:smooth] = kwargs.empty? ? args.first : kwargs
       end
@@ -313,7 +313,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def shape(*args, **kwargs)
         @options[:shape] = kwargs.empty? ? args.first : kwargs
       end
@@ -324,7 +324,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def type(*args, **kwargs)
         @options[:type] = kwargs.empty? ? args.first : kwargs
       end