xlsxrb 0.1.5 → 0.1.6

data/README.md

@@ -6,17 +6,22 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 The Ruby ecosystem already has great XLSX libraries. Each is well-designed for its purpose:
 
-| Library                                            | Read | Write | Streaming (low memory) |
-| -------------------------------------------------- | ---- | ----- | ---------------------- |
-| [roo](https://rubygems.org/gems/roo)               | ✅   | ❌    | ✅                     |
-| [creek](https://rubygems.org/gems/creek)           | ✅   | ❌    | ✅                     |
-| [xsv](https://rubygems.org/gems/xsv)               | ✅   | ❌    | ✅                     |
-| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx) | ❌   | ✅    | ❌                     |
-| [xlsxtream](https://rubygems.org/gems/xlsxtream)   | ❌   | ✅    | ✅                     |
-| [rubyXL](https://rubygems.org/gems/rubyXL)         | ✅   | ✅    | ❌                     |
-| [fast_excel](https://rubygems.org/gems/fast_excel) | ❌   | ✅    | ✅                     |
-
-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.
+| Library                                            | Read | Write | Model                 | Write String Storage | Rich Formatting |
+| -------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- |
+| [roo](https://rubygems.org/gems/roo)               | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) |
+| [creek](https://rubygems.org/gems/creek)           | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) |
+| [xsv](https://rubygems.org/gems/xsv)               | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) |
+| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx) | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) |
+| [xlsxtream](https://rubygems.org/gems/xlsxtream)   | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) |
+| [fast_excel](https://rubygems.org/gems/fast_excel) | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) |
+| [rubyXL](https://rubygems.org/gems/rubyXL)         | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) |
+| **[xlsxrb](https://github.com/niku/xlsxrb)**       | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** |
+
+Each of these libraries makes deliberate tradeoffs, and they do so thoughtfully:
+* **Memory & Execution Model (Streaming vs In-Memory)**: Streaming libraries write or read rows sequentially on-the-fly to maintain a constant, low-memory footprint regardless of row count. In-memory libraries build complete document object trees, offering flexible random access and cell updates at the cost of high RAM usage on large sheets.
+* **String Storage Architecture (SST vs Inline Strings)**:
+  * **SST (Shared String Table)**: De-duplicates strings into a central dictionary (`xl/sharedStrings.xml`), referencing them by numeric IDs in cell entries (`<c t="s"><v>0</v></c>`). This is standard Microsoft Excel behavior, producing significantly smaller raw XML documents (50–100% smaller) and reducing Excel's memory footprint when opening spreadsheets.
+  * **Inline Strings**: Writes text directly into cell payloads (`<c t="inlineStr"><is><t>...</t></is></c>`). Bypassing the dictionary enables blazing-fast raw throughput for simple data exports, but inflates uncompressed XML size and limits advanced formatting (e.g. styling, cell merges, charts).
 
 Traditionally, attempting to build a "complete package" that offers both reading and writing, rich features, high performance, strict compatibility, and comprehensive documentation presents an inherent open-source challenge: the cumulative maintenance overhead often exceeds the capacity of individual human maintainers.
 
@@ -156,37 +161,39 @@ For detailed specification references and policies, see [SPEC_SOURCES.md](docs/S
 
 ## Benchmarks
 
-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.
+The following benchmarks measure the time, peak memory, and GC count required to process a 1,000,000 cells (100,000 rows × 10 columns) spreadsheet across popular Ruby Excel libraries. Each test is executed across 3 independent runs in isolated subprocesses; median values are reported along with the mean execution time.
 
 ### Write Performance (1,000,000 cells)
 
-| Library                | Time    | Peak Memory | GC Count |
-| ---------------------- | ------- | ----------- | -------- |
-| 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     |
+| Library                | Model       | Write String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| ---------------------- | ----------- | -------------------- | ------------- | ----------- | ----------- | -------- |
+| xlsxtream 3.1.0        | Streaming   | Inline String        | 1.23 s        | 1.25 s      | 18.1 MB     | 1061.0   |
+| xlsxrb (Streaming)     | Streaming   | SST (Shared)         | 1.62 s        | 1.62 s      | 94.5 MB     | 39.0     |
+| fast_excel 0.5.0 (C)   | Streaming   | SST (Shared)         | 2.03 s        | 2.03 s      | 147.9 MB    | 263.0    |
+| xlsxrb (In-Memory)     | In-Memory   | SST (Shared)         | 4.06 s        | 4.06 s      | 280.3 MB    | 32.0     |
+| caxlsx 4.5.0           | In-Memory   | Inline String        | 5.36 s        | 5.35 s      | 188.7 MB    | 23.0     |
+| rubyXL 3.4.38          | In-Memory   | Inline String        | 38.02 s       | 38.03 s     | 2166.0 MB   | 104.0    |
+
+> **Note**: All libraries are evaluated in their **default, out-of-the-box configuration**. Under the same Microsoft Excel-standard Shared String Table (SST) architecture, Pure Ruby `xlsxrb` (Streaming: 1.62s, In-Memory: 4.06s) writes 1,000,000 cells faster than the C-extension `fast_excel` (2.03s) and in-memory gems like `caxlsx` (5.36s).
 
 ### Read Performance (1,000,000 cells)
 
-| Library            | Time    | Peak Memory | GC Count |
-| ------------------ | ------- | ----------- | -------- |
-| 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    |
+| Library                | Model       | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| ---------------------- | ----------- | ------------- | ----------- | ----------- | -------- |
+| xlsxrb (Streaming)     | Streaming   | 3.38 s        | 3.37 s      | 90.6 MB     | 40.0     |
+| xlsxrb (In-Memory)     | In-Memory   | 5.75 s        | 5.94 s      | 250.9 MB    | 55.0     |
+| creek 2.6.3            | Streaming   | 7.90 s        | 7.93 s      | 835.7 MB    | 481.0    |
+| roo 3.0.0              | Streaming   | 10.34 s       | 10.28 s     | 139.0 MB    | 107.0    |
+| xsv 1.4.1              | Streaming   | 16.39 s       | 17.28 s     | 75.4 MB     | 2215.0   |
+| rubyXL 3.4.38          | In-Memory   | 35.45 s       | 35.38 s     | 2281.3 MB   | 146.0    |
 
-### Running the Benchmarks Locally
+### Running the Benchmarks Locally (Reproducibility)
 
-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.
+The benchmark suite leverages [`bundler/inline`](https://bundler.io/v2.5/guides/bundler_in_a_single_file_ruby_script.html) to automatically manage and download all peer ecosystem gems without modifying the project's core `Gemfile` or requiring manual global `gem install` steps. Each library is executed in an isolated subprocess (`Bundler.with_unbundled_env`) across multiple runs with standard business dataset rows (integers, strings, floats, booleans, dates) to ensure clean memory and GC measurements without cross-contamination.
 
-To run the benchmark locally for 1,000,000 cells (100,000 rows):
+To run the complete benchmark suite:
 ```bash
-ruby benchmark.rb 100000
+ruby benchmark.rb 100000 10
 ```
 
 ## Security (Protection against CSV/Excel Injection)

data/Rakefile

@@ -527,7 +527,8 @@ namespace :doc do
 end
 desc "Generate RBS signature files from inline annotations"
 task :sig do
-  sh "bundle exec rbs-inline --output lib/**/*.rb"
+  files = FileList["lib/**/*.rb"].to_a
+  sh "bundle", "exec", "rbs-inline", "--output=sig/generated", "--base=lib", *files
 end
 
 desc "Run static type checking with Steep"

data/Steepfile

@@ -3,8 +3,6 @@
 target :lib do
   signature "sig"
 
-  check "lib/xlsxrb.rb"
-
   library "date"
   library "time"
   library "securerandom"

data/benchmark.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+# rubocop:disable all
+
+require "json"
+require "open3"
+require "fileutils"
+require "bundler/inline"
+
+puts "Ensuring benchmark peer ecosystem gems are available (bundler/inline)..."
+gemfile(true) do
+  source "https://rubygems.org"
+  gem "caxlsx", "4.5.0"
+  gem "xlsxtream", "3.1.0"
+  gem "fast_excel", "0.5.0", platform: :mri
+  gem "rubyXL", "3.4.38"
+  gem "roo", "3.0.0"
+  gem "creek", "2.6.3"
+  gem "xsv", "1.4.1"
+end
+
+RUNS = (ENV["RUNS"] || "3").to_i
+ROWS = (ARGV[0] || "100000").to_i
+COLS = (ARGV[1] || "10").to_i
+
+AVAILABLE_GEMS = {
+  "xlsxrb_stream" => true,
+  "xlsxrb_inmemory" => true,
+  "xlsxtream" => true,
+  "fast_excel" => true,
+  "caxlsx" => true,
+  "rubyXL" => true,
+  "creek" => true,
+  "roo" => true,
+  "xsv" => true
+}
+
+puts "=" * 80
+puts "Benchmarking Excel Libraries (#{ROWS} rows x #{COLS} cols = #{ROWS * COLS} cells)"
+puts "Runs per benchmark: #{RUNS} (Median reported, Mean calculated)"
+puts "Ruby: #{RUBY_DESCRIPTION}"
+puts "=" * 80
+
+RUNNER_SCRIPT = <<~'RUBY'
+  require "json"
+  require "stringio"
+
+  def measure
+    gc_before = GC.stat[:count]
+    t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    
+    yield
+    
+    t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    gc_after = GC.stat[:count]
+    
+    # Peak memory in MB via /proc/self/status or getrusage
+    peak_mb = 0.0
+    if File.exist?("/proc/self/status")
+      status = File.read("/proc/self/status")
+      if status =~ /VmHWM:\s+(\d+)\s+kB/i
+        peak_mb = $1.to_f / 1024.0
+      elsif status =~ /VmRSS:\s+(\d+)\s+kB/i
+        peak_mb = $1.to_f / 1024.0
+      end
+    end
+    
+    {
+      time: (t1 - t0),
+      peak_memory_mb: peak_mb,
+      gc_count: (gc_after - gc_before)
+    }
+  end
+
+  def generate_row(r, cols)
+    base = [r + 1, "User #{r + 1}", 123.45, true, "Active", (r + 1) * 10, "Tokyo", 99.9, false, "Item #{r % 50}"]
+    if cols <= base.size
+      base.first(cols)
+    else
+      base + Array.new(cols - base.size) { |c| "col_#{c}_#{r}" }
+    end
+  end
+
+  lib = ARGV[0]
+  mode = ARGV[1] # "write" or "read"
+  rows = ARGV[2].to_i
+  cols = ARGV[3].to_i
+  filename = ARGV[4]
+
+  result = case [lib, mode]
+  when ["xlsxtream", "write"]
+    require "xlsxtream"
+    measure do
+      Xlsxtream::Workbook.open(filename) do |wb|
+        wb.write_worksheet("Data") do |sheet|
+          rows.times do |r|
+            sheet << generate_row(r, cols)
+          end
+        end
+      end
+    end
+  when ["fast_excel", "write"]
+    require "fast_excel"
+    measure do
+      wb = FastExcel.open(filename)
+      sheet = wb.add_worksheet("Data")
+      rows.times do |r|
+        sheet.append_row(generate_row(r, cols))
+      end
+      wb.close
+    end
+  when ["caxlsx", "write"]
+    require "caxlsx"
+    measure do
+      p = Axlsx::Package.new
+      wb = p.workbook
+      wb.add_worksheet(name: "Data") do |sheet|
+        rows.times do |r|
+          sheet.add_row(generate_row(r, cols))
+        end
+      end
+      p.serialize(filename)
+    end
+  when ["rubyXL", "write"]
+    require "rubyXL"
+    measure do
+      wb = RubyXL::Workbook.new
+      sheet = wb[0]
+      sheet.sheet_name = "Data"
+      rows.times do |r|
+        row_data = generate_row(r, cols)
+        row_data.each_with_index do |val, c|
+          sheet.add_cell(r, c, val)
+        end
+      end
+      wb.write(filename)
+    end
+  when ["xlsxrb_stream", "write"]
+    require_relative "lib/xlsxrb"
+    measure do
+      Xlsxrb.generate(filename) do |wb|
+        wb.sheet("Data") do |sheet|
+          rows.times do |r|
+            sheet.row(generate_row(r, cols))
+          end
+        end
+      end
+    end
+  when ["xlsxrb_inmemory", "write"]
+    require_relative "lib/xlsxrb"
+    measure do
+      wb = Xlsxrb.build do |b|
+        b.sheet("Data") do |s|
+          rows.times do |r|
+            s.row(generate_row(r, cols))
+          end
+        end
+      end
+      Xlsxrb.write(filename, wb)
+    end
+  when ["xlsxrb_stream", "read"]
+    require_relative "lib/xlsxrb"
+    measure do
+      count = 0
+      Xlsxrb.foreach(filename) do |sheet|
+        sheet.each do |row|
+          row.cells.each do |cell|
+            _val = cell.value
+            count += 1
+          end
+        end
+      end
+    end
+  when ["xlsxrb_inmemory", "read"]
+    require_relative "lib/xlsxrb"
+    measure do
+      wb = Xlsxrb.read(filename)
+      count = 0
+      wb.sheets.each do |sheet|
+        sheet.rows.each do |row|
+          row.cells.each do |cell|
+            _val = cell.value
+            count += 1
+          end
+        end
+      end
+    end
+  when ["creek", "read"]
+    require "creek"
+    measure do
+      creek = Creek::Book.new(filename)
+      count = 0
+      creek.sheets.each do |sheet|
+        sheet.rows.each do |row|
+          row.each_value do |_val|
+            count += 1
+          end
+        end
+      end
+    end
+  when ["roo", "read"]
+    require "roo"
+    measure do
+      xlsx = Roo::Excelx.new(filename)
+      count = 0
+      xlsx.each_row_streaming do |row|
+        row.each do |cell|
+          _val = cell&.value
+          count += 1
+        end
+      end
+    end
+  when ["xsv", "read"]
+    require "xsv"
+    measure do
+      x = Xsv.open(filename)
+      count = 0
+      x.sheets.each do |sheet|
+        sheet.each do |row|
+          row.each do |_val|
+            count += 1
+          end
+        end
+      end
+    end
+  when ["rubyXL", "read"]
+    require "rubyXL"
+    measure do
+      wb = RubyXL::Parser.parse(filename)
+      count = 0
+      wb.worksheets.each do |sheet|
+        sheet.each do |row|
+          next unless row
+          row.cells.each do |cell|
+            _val = cell&.value
+            count += 1
+          end
+        end
+      end
+    end
+  else
+    raise "Unknown benchmark target: #{lib} #{mode}"
+  end
+
+  puts result.to_json
+RUBY
+
+runner_file = "benchmark_runner.rb"
+File.write(runner_file, RUNNER_SCRIPT)
+
+def run_isolated(lib, mode, rows, cols, filename)
+  cmd = ["ruby", "-Ilib", "benchmark_runner.rb", lib, mode, rows.to_s, cols.to_s, filename]
+  stdout, stderr, status = Bundler.with_unbundled_env do
+    Open3.capture3(*cmd)
+  end
+  unless status.success?
+    warn "Failed to run #{lib} #{mode}: #{stderr}"
+    return nil
+  end
+  JSON.parse(stdout.strip, symbolize_names: true)
+end
+
+def run_benchmark_series(name, lib, mode, rows, cols, filename, runs)
+  unless AVAILABLE_GEMS[lib]
+    puts "Skipping #{name} (gem not installed)"
+    return nil
+  end
+
+  print "Running #{name} (#{runs} runs)... "
+  $stdout.flush
+  results = []
+  runs.times do |_i|
+    File.delete(filename) if File.exist?(filename) && mode == "write"
+    res = run_isolated(lib, mode, rows, cols, filename)
+    if res
+      results << res
+      print "#{res[:time].round(2)}s "
+      $stdout.flush
+    else
+      print "ERR "
+      $stdout.flush
+    end
+  end
+  puts
+
+  return nil if results.empty?
+
+  times = results.map { |r| r[:time] }.sort
+  mems = results.map { |r| r[:peak_memory_mb] }.sort
+  gcs = results.map { |r| r[:gc_count] }.sort
+
+  median_time = times[times.size / 2]
+  mean_time = times.sum / times.size
+  median_mem = mems[mems.size / 2]
+  median_gc = gcs[gcs.size / 2]
+
+  {
+    name: name,
+    median_time: median_time,
+    mean_time: mean_time,
+    median_mem: median_mem,
+    median_gc: median_gc
+  }
+end
+
+# 1. Generate a standard reference file for reading benchmarks
+ref_file = "bench_reference_data.xlsx"
+puts "\n[Setup] Generating reference file (#{ROWS} x #{COLS}) for read benchmarks..."
+run_isolated("xlsxrb_stream", "write", ROWS, COLS, ref_file)
+
+# 2. Benchmark Write
+puts "\n=== Benchmarking Write Performance ==="
+write_targets = [
+  ["xlsxtream 3.1.0", "xlsxtream", "Streaming", "Inline String"],
+  ["xlsxrb (Streaming)", "xlsxrb_stream", "Streaming", "SST (Shared)"],
+  ["fast_excel 0.5.0 (C)", "fast_excel", "Streaming", "SST (Shared)"],
+  ["caxlsx 4.5.0", "caxlsx", "In-Memory", "Inline String"],
+  ["xlsxrb (In-Memory)", "xlsxrb_inmemory", "In-Memory", "SST (Shared)"],
+  ["rubyXL 3.4.38", "rubyXL", "In-Memory", "Inline String"]
+]
+
+write_results = []
+write_targets.each do |name, lib, model, storage|
+  target_file = "bench_write_#{lib}.xlsx"
+  res = run_benchmark_series(name, lib, "write", ROWS, COLS, target_file, RUNS)
+  if res
+    res[:model] = model
+    res[:storage] = storage
+    write_results << res
+  end
+  FileUtils.rm_f(target_file)
+end
+
+# 3. Benchmark Read
+puts "\n=== Benchmarking Read Performance ==="
+read_targets = [
+  ["xlsxrb (Streaming)", "xlsxrb_stream", "Streaming"],
+  ["xlsxrb (In-Memory)", "xlsxrb_inmemory", "In-Memory"],
+  ["creek 2.6.3", "creek", "Streaming"],
+  ["roo 3.0.0", "roo", "Streaming"],
+  ["xsv 1.4.1", "xsv", "Streaming"],
+  ["rubyXL 3.4.38", "rubyXL", "In-Memory"]
+]
+
+read_results = []
+read_targets.each do |name, lib, model|
+  res = run_benchmark_series(name, lib, "read", ROWS, COLS, ref_file, RUNS)
+  if res
+    res[:model] = model
+    read_results << res
+  end
+end
+
+# Cleanup
+FileUtils.rm_f(ref_file)
+FileUtils.rm_f(runner_file)
+
+# Print Tables
+puts "\n" + ("=" * 80)
+puts "### Write Performance (#{ROWS * COLS} cells: #{ROWS} rows x #{COLS} cols)"
+puts ""
+puts "| Library                | Model       | Write String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |"
+puts "| ---------------------- | ----------- | -------------------- | ------------- | ----------- | ----------- | -------- |"
+write_results.sort_by { |r| r[:median_time] }.each do |r|
+  printf "| %-22s | %-11s | %-20s | %6.2f s      | %6.2f s    | %7.1f MB  | %6.1f   |\n",
+         r[:name], r[:model], r[:storage], r[:median_time], r[:mean_time], r[:median_mem], r[:median_gc]
+end
+
+puts "\n### Read Performance (#{ROWS * COLS} cells: #{ROWS} rows x #{COLS} cols)"
+puts ""
+puts "| Library                | Model       | Time (Median) | Time (Mean) | Peak Memory | GC Count |"
+puts "| ---------------------- | ----------- | ------------- | ----------- | ----------- | -------- |"
+read_results.sort_by { |r| r[:median_time] }.each do |r|
+  printf "| %-22s | %-11s | %6.2f s      | %6.2f s    | %7.1f MB  | %6.1f   |\n",
+         r[:name], r[:model], r[:median_time], r[:mean_time], r[:median_mem], r[:median_gc]
+end
+puts "=" * 80

data/docs/ARCHITECTURE.md

@@ -26,12 +26,19 @@ As a strict rule, **we do not accept dynamic method definitions using `method_mi
 2. **Developer Experience**: IDE autocompletion, jump-to-definition, and YARD documentation work perfectly.
 3. **Traceability**: If a method exists, you can `grep` for it.
 
-Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mappings (e.g. `ChartBuilder`, `SeriesBuilder`) would traditionally benefit from dynamic method delegation to avoid boilerplate, we explicitly generate and write out those delegations in the source code.
+Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mappings (e.g. `ChartBuilder`, `SeriesBuilder`) would traditionally benefit from dynamic delegation to avoid boilerplate, we explicitly generate and write out those delegations in the source code.
 
-### API Contract (SemVer)
-- Methods tagged with `@api public` in their YARD documentation are guaranteed to follow SemVer.
-- Methods without this tag (or tagged `@api private`) are internal and may change at any time.
-- Note that during the 0.x series, this is a "best effort" promise, but after 1.0.0, strict SemVer guarantees will apply to all `@api public` methods.
+### 1. **`Xlsxrb` Module is the ONLY Entrypoint:**
+   The `Xlsxrb` module provides the top-level methods: `generate`, `build`, `read`, `foreach`, and `modify`. Users should **never** instantiate internal classes (like `Xlsxrb::Ooxml::WorkbookWriter`) directly.
+
+2. **The `@api public` Contract (SemVer Guarantee):**
+   Any module, class, or method tagged with `# @api public` in its YARD documentation is guaranteed to follow Semantic Versioning.
+   - Patch versions (0.1.x -> 0.1.y) will not break these APIs.
+   - Minor versions (0.x.0 -> 0.y.0) will not break these APIs once 1.0.0 is released (during 0.x.x, it is a best-effort promise).
+   - Major versions (1.x -> 2.x) are the only time breaking changes to `@api public` components are permitted.
+
+3. **Block-Yielded Objects are Public APIs:**
+   All builder objects yielded into blocks (e.g., `writer` in `Xlsxrb.generate { |writer| }`, `sheet` in `writer.sheet { |sheet| }`, `chart` in `sheet.chart { |chart| }`) are explicitly marked as `@api public`. Their exposed methods constitute the DSL and are strictly protected by the SemVer contract.
 
 ---
 

data/lib/xlsxrb/elements/cell.rb

@@ -7,7 +7,7 @@ module Xlsxrb
     # Represents a single cell in a worksheet.
     # All indices are 0-based.
     Cell = Data.define(:row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors) do
-      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: {}, errors: nil)
+      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(row_index, column_index, value)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         super(row_index: row_index, column_index: column_index, value: value, formula: formula,
@@ -23,6 +23,22 @@ module Xlsxrb
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       end
 
+      def [](key)
+        case key
+        when :value then value
+        when :formula then formula
+        when :style_index then style_index
+        when :ref then ref
+        when :column_index then column_index
+        when :row_index then row_index
+        when :type
+          case value
+          when String then "s"
+          when true, false then "b"
+          end
+        end
+      end
+
       def content
         value
       end
@@ -122,19 +138,35 @@ module Xlsxrb
 
       # Parses an Excel-style reference to [row_index, col_index] (both 0-based).
       def self.parse_ref(ref)
-        match = ref.match(/\A([A-Z]+)(\d+)\z/)
-        return nil unless match
+        return nil unless ref
+
+        bytes = ref.b
+        len = bytes.bytesize
+        col = 0
+        i = 0
+        while i < len
+          b = bytes.getbyte(i)
+          if b.between?(65, 90)
+            col = (col * 26) + (b - 64)
+            i += 1
+          elsif b.between?(97, 122)
+            col = (col * 26) + (b - 96)
+            i += 1
+          else
+            break
+          end
+        end
+        return nil if i.zero? || i == len
 
-        col = match[1].chars.reduce(0) { |acc, c| (acc * 26) + (c.ord - "A".ord + 1) } - 1
-        row = match[2].to_i - 1
-        [row, col]
+        row = bytes.byteslice(i, len - i).to_i - 1
+        [row, col - 1]
       end
 
       def self.validate(row_index, column_index, value)
         if row_index.is_a?(Integer) && row_index >= 0 && row_index < 1_048_576 &&
            column_index.is_a?(Integer) && column_index >= 0 && column_index < 16_384 &&
            (value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false || value.is_a?(Date) || value.is_a?(Time) || value.is_a?(Formula) || (value.is_a?(Hash) && value.key?(:formula)) || value.is_a?(RichText) || value.is_a?(CellError))
-          return [].freeze
+          return EMPTY_ERRORS
         end
 
         errs = []

data/lib/xlsxrb/elements/row.rb

@@ -9,8 +9,8 @@ module Xlsxrb
     Row = Data.define(:index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors) do
       include Enumerable
 
-      def initialize(index:, cells: [], height: nil, hidden: false, custom_height: false, outline_level: nil,
-                     unmapped_data: {}, errors: nil)
+      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil,
+                     unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(index, cells)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         cells = cells.freeze unless cells.frozen?
@@ -20,7 +20,20 @@ module Xlsxrb
       end
 
       def [](col_index)
-        cells[col_index]
+        case col_index
+        when Symbol
+          case col_index
+          when :cells then cells
+          when :index then index
+          when :height then height
+          when :hidden then hidden
+          when :custom_height then custom_height
+          when :outline_level then outline_level
+          when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
+          end
+        else
+          cells[col_index]
+        end
       end
 
       def each(&)
@@ -66,7 +79,7 @@ module Xlsxrb
       end
 
       def self.validate(index, cells)
-        return [].freeze if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)
+        return EMPTY_ERRORS if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)
 
         errs = []
         if !index.is_a?(Integer) || index.negative?

data/lib/xlsxrb/elements/types.rb

@@ -4,6 +4,10 @@
 
 module Xlsxrb
   module Elements
+    EMPTY_ERRORS = [].freeze
+    EMPTY_HASH = {}.freeze
+    EMPTY_CELLS = [].freeze
+
     # Represents a formula with an optional cached value.
     # Optional: type (:shared, :array), ref (range), shared_index (si for shared formulas)
     Formula = Data.define(:expression, :cached_value, :type, :ref, :shared_index, :calculate_always, :aca, :bx, :dt2d, :dtr, :r1, :r2) do