xlsxrb 0.1.5 → 0.1.7

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.
 
@@ -77,8 +82,8 @@ Generate large files efficiently by writing data directly to the file stream:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.generate("large_output.xlsx") do |wb|
-  wb.sheet("Sales Data") do |sheet|
+Xlsxrb.generate("large_output.xlsx") do |stream_writer|
+  stream_writer.sheet("Sales Data") do |sheet|
     sheet.row(["Date", "Amount", "Status"])
     sheet.row([Date.today, 100, true])
     sheet.column(0, width: 15.5)
@@ -92,7 +97,7 @@ Read rows one at a time without loading the entire file into memory:
 require "xlsxrb"
 
 Xlsxrb.foreach("large_file.xlsx") do |sheet|
-  sheet.each do |row|
+  sheet.each_row do |row|
     puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
   end
 end
@@ -103,17 +108,17 @@ end
 `xlsxrb` provides a powerful, immutable-by-default API for modifying existing Excel files or building templates in-memory. 
 
 #### Modifying an Existing File
-You can update specific cells or sheets using the functional `Xlsxrb.modify` API, which yields the parsed `Workbook`.
+You can update specific cells or sheets using the functional `Xlsxrb.modify` API, which yields the parsed `Elements::Workbook`.
 
 ```ruby
 require "xlsxrb"
 
-# Create a dummy template.xlsx for this example
-Xlsxrb.build { |w| w.sheet("Invoice") }.write("template.xlsx")
+# Create a template.xlsx for this example
+Xlsxrb.build { |builder| builder.sheet("Invoice") }.write("template.xlsx")
 
-Xlsxrb.modify("template.xlsx", "output.xlsx") do |wb|
-  wb.update_sheet("Invoice") do |sheet|
-    # Update a specific cell
+Xlsxrb.modify("template.xlsx", "output.xlsx") do |workbook|
+  workbook.update_sheet("Invoice") do |sheet|
+    # Update specific cells (returns updated sheet)
     sheet = sheet.update_cell("C4", value: "INV-10042")
     sheet = sheet.update_cell("C5", value: Date.today)
     
@@ -129,16 +134,31 @@ end
 You can directly apply inline styles or use Ranges for multiple columns without boilerplate:
 
 ```ruby
-Xlsxrb.build do |wb|
+Xlsxrb.build do |builder|
   # Use [] accessor for sheets
-  wb["Report"].row(
+  builder["Report"].row(
     ["ID", "Name", "Score", "Rank"],
     # Apply 'header' style to first two columns, and bold inline style to the third
     styles: { 0..1 => "header", 2 => { font: { bold: true, color: "red" } } }
   )
   
   # Set multiple column widths at once using Ranges
-  wb["Report"].column("A".."D", width: 15.0)
+  builder["Report"].column("A".."D", width: 15.0)
+end
+```
+
+### IDE Autocompletion & Ruby LSP Support
+
+`xlsxrb` bundles a native **Ruby LSP Add-on** (`RubyLsp::Xlsxrb::Addon`) and full **RBS signatures**, enabling zero-configuration method autocompletion and rich Markdown documentation in VS Code and other LSP-enabled editors.
+
+Whether you use standard descriptive block variable names (`|stream_writer|`, `|sheet|`, `|workbook|`) or short names (`|wb|`, `|s|`), your editor will automatically provide complete method suggestions and parameter hints:
+
+```ruby
+Xlsxrb.generate("output.xlsx") do |stream_writer| # or |wb|
+  stream_writer.sheet("Data") do |sheet|           # or |s|
+    sheet.row(["Product", "Price"], styles: :bold)
+    sheet.auto_filter("A1:B100")
+  end
 end
 ```
 
@@ -156,37 +176,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

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

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/docs/visual/VisualGallery.md

@@ -1426,6 +1426,14 @@ sheet.rows.each do |row|
 end
 ```
 
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "Format" (String), B1: "Value" (String)
+Row 1: A2: "Rich Text Cell" (String), B2: "Normal BOLD RED ITALIC BLUE" (String)
+```
+
 <hr/>
 
 ## Cell Times

data/lib/ruby_lsp/xlsxrb/addon.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ruby_lsp/addon"
+require_relative "completion_listener"
+require_relative "../../xlsxrb/version"
+
+module RubyLsp
+  module Xlsxrb
+    # Ruby LSP Add-on for xlsxrb.
+    #
+    # [Context & Lifecycle Note]
+    # This add-on serves as a bridge/polyfill for current Ruby LSP environments.
+    # While xlsxrb ships with complete RBS signatures (`sig/generated/`), Ruby LSP's
+    # type inferrer does not yet perform automatic static type inference from method
+    # block signatures to block parameters (e.g., `Xlsxrb.generate do |wb|`).
+    #
+    # This add-on enables immediate out-of-the-box autocompletion and rich Markdown
+    # documentation across all public block arguments.
+    #
+    # As the Ruby tooling ecosystem evolves and Ruby LSP gains native block argument
+    # type resolution from gem RBS signatures in the future, this add-on will become
+    # redundant and can eventually be deprecated or removed.
+    class Addon < ::RubyLsp::Addon
+      def activate(global_state, _message_queue)
+        @global_state = global_state
+      end
+
+      def deactivate; end
+
+      def name
+        "xlsxrb"
+      end
+
+      def version
+        ::Xlsxrb::VERSION
+      end
+
+      def create_completion_listener(response_builder, node_context, dispatcher, _uri = nil)
+        CompletionListener.new(response_builder, node_context, dispatcher, @global_state)
+      end
+    end
+  end
+end