xlsxrb 0.1.3 → 0.1.5

data/CHANGELOG.md

@@ -1,12 +1,33 @@
 ## [Unreleased]
+- No unreleased changes.
 
+## [0.1.5] - 2026-08-11
+
+### Added
+- Functional API for updating existing files (`Xlsxrb.modify`).
+- New `Workbook#update_sheet` and `Worksheet#update_cell` helpers for immutable data structures.
+- Syntactic sugar for `styles:` in `sheet.row` using `Hash` and `Range` keys (e.g. `styles: { 0..4 => "header" }`).
+- Support for inline anonymous styles as Hash objects (e.g. `styles: { 0 => { font: { bold: true } } }`).
+- Support for `Range` and `Array` arguments in `sheet.column` to modify multiple columns at once.
+- `WorkbookBuilder#[]` and `StreamWriter#[]` aliased to `#sheet` for elegant context switching.
+- Block-based configuration for `font` and `border` properties inside `StyleBuilder`.
+- Extensive inline RBS typing with strict generic types (eliminated `untyped` from the public API).
+- Full `RBS::Test` runtime type validation enabled for the entire test suite.
+- Extensive Excel limit warnings documented via YARD tags.
+- Formal SemVer API contract with `@api public` tags for user-facing methods.
+- Comprehensive mutation testing (Mutant) and test coverage (SimpleCov) integrations.
+
+### Changed
+- Replaced `method_missing` with statically defined, fully typed methods in `WorksheetProxy`, `ChartBuilder`, and `SeriesBuilder`.
+- Removed deprecated `instance_eval` block context for builders; explicit block arguments are now required.
+- Hardened security and bounds checking across the DSL for `strict_excel_mode`.
+- Fixed numerous Rubocop linting violations and standardized style rules.
 - Add specification reference policy and implemented specification mapping (`docs/SPEC_SOURCES.md`).
 - Introduce unified event-based streaming and parsing architecture (`Ooxml::Event` and event streams for WorksheetParser/SharedStringsParser).
-- Restructure test suite into four distinct tiers (Unit, Contract, E2E, Visual).
-- Add visual examples gallery (`examples/visual/` and `docs/visual/README.md`).
+- Restructure test suite into four distinct tiers (Unit, Contract, E2E, Visual) and renamed `facade_test.rb` to `public_api_test.rb`.
+- Add visual examples gallery (`examples/visual/` and `docs/visual/README.md`) and promoted it via animated GIF in the main README.
 - Implement visual regression testing (VRT) pipeline comparing generated sheets against reference baselines.
 
-
 ## [0.1.0] - 2026-03-25
 
 - Initial release

data/README.md

@@ -77,11 +77,11 @@ Generate large files efficiently by writing data directly to the file stream:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.generate("large_output.xlsx") do |writer|
-  writer.add_sheet("Sales Data") do
-    writer.add_row(["Date", "Amount", "Status"])
-    writer.add_row([Date.today, 100, true])
-    writer.set_column(0, width: 15.5)
+Xlsxrb.generate("large_output.xlsx") do |wb|
+  wb.sheet("Sales Data") do |sheet|
+    sheet.row(["Date", "Amount", "Status"])
+    sheet.row([Date.today, 100, true])
+    sheet.column(0, width: 15.5)
   end
 end
 ```
@@ -91,12 +91,56 @@ Read rows one at a time without loading the entire file into memory:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.foreach("large_file.xlsx", sheet: 0) do |row|
-  puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
+Xlsxrb.foreach("large_file.xlsx") do |sheet|
+  sheet.each do |row|
+    puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
+  end
+end
+```
+
+### In-Memory Building & Modifying
+
+`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`.
+
+```ruby
+require "xlsxrb"
+
+# Create a dummy template.xlsx for this example
+Xlsxrb.build { |w| w.sheet("Invoice") }.write("template.xlsx")
+
+Xlsxrb.modify("template.xlsx", "output.xlsx") do |wb|
+  wb.update_sheet("Invoice") do |sheet|
+    # Update a specific cell
+    sheet = sheet.update_cell("C4", value: "INV-10042")
+    sheet = sheet.update_cell("C5", value: Date.today)
+    
+    # Or append new rows
+    sheet.with(rows: sheet.rows + [
+      Xlsxrb::Elements::Row.new(index: sheet.rows.size, cells: [])
+    ])
+  end
 end
 ```
 
-*(For In-Memory document building, cell modifications, or template updating, please refer to the detailed RDoc API documentation).*
+#### Hash & Range Styling (Syntactic Sugar)
+You can directly apply inline styles or use Ranges for multiple columns without boilerplate:
+
+```ruby
+Xlsxrb.build do |wb|
+  # Use [] accessor for sheets
+  wb["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)
+end
+```
 
 ## Feature Support & ECMA-376 Compliance
 
@@ -145,28 +189,58 @@ To run the benchmark locally for 1,000,000 cells (100,000 rows):
 ruby benchmark.rb 100000
 ```
 
+## Security (Protection against CSV/Excel Injection)
+
+Unlike CSV files which lack type definitions and force Excel to guess types (often inadvertently executing strings starting with `=`), `.xlsx` files generated by `xlsxrb` are strictly typed.
+
+When you pass a Ruby `String` to `xlsxrb`, it explicitly writes it as a `String` (`t="s"`) into the OOXML file. Therefore, **even if a string starts with `=`, Excel will never evaluate it as a formula**. To write a formula, you must explicitly use `Xlsxrb::Elements::Formula.new`. This design completely mitigates CSV/Formula Injection vulnerabilities by default without requiring additional sanitization.
+
+### External Link Updates (`update_links`)
+
+As an extra layer of "defense in depth", `xlsxrb` configures the workbook to **never automatically update external links** when opened (`updateLinks="never"`). This is intentionally set to `never` by default to prevent Excel from silently reaching out to external resources or executing DDE (Dynamic Data Exchange) links, which is a known vector for malware.
+
+If you absolutely need external links to update automatically, you can explicitly override this (though **it is highly discouraged due to security risks**):
+
+```ruby
+Xlsxrb.generate("file.xlsx") do |wb|
+  # WARNING: Enabling this can expose users to malicious external reference vulnerabilities!
+  wb.workbook_property(:update_links, "always") 
+  # ...
+end
+```
+
 ## Testing & Quality Assurance
 
-To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a 4-tier testing strategy:
+To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a highly rigorous, enterprise-grade Quality Assurance (QA) and testing architecture.
+
+### Multi-Tier Testing Strategy
+* **Round-Trip Testing**: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
+* **Contract Consistency**: Ensures semantic output consistency between the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build`) APIs.
+* **Property-Based Testing (PBT)**: Automatically generates random data to catch edge cases (e.g., huge numbers, special characters) preventing unexpected crashes.
+* **Concurrency Validation**: Thread and Ractor safety checks to guarantee no global variable pollution during parallel execution.
+* **Security & DoS Protection**: Hardened against malicious files, including memory exhaustion (ZIP Bombs) and infinite parsing loops.
+
+### Strict Interoperability & Rendering
+* **Official Open XML SDK Validation (E2E)**: Every generated spreadsheet is structurally validated against the official Microsoft Open XML SDK to prevent file corruption warnings in Microsoft Excel.
+* **Visual Regression Testing (VRT)**: Spreadsheets are rendered via a headless LibreOffice Calc engine and compared pixel-by-pixel against visual baselines to catch subtle rendering regressions.
 
-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.
+### Performance & Types
+* **Continuous Benchmarking**: Memory usage and processing speeds are profiled in CI on large datasets to prevent performance regressions and OOM leaks.
+* **Runtime Type Validation**: Strong dynamic typing using `RBS::Test` to ensure the library's types are perfectly sound at runtime.
 
-For details on running the tests locally or within our pre-configured Dev Container, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+For a comprehensive breakdown of our QA matrix, see [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md). For details on running tests locally, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
 ## Development
 
 We welcome contributions! The project is configured with a ready-to-use Dev Container to streamline local environment setup.
 
-For contribution guidelines, E2E testing policies, and the step-by-step development workflow, please refer to [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+For contribution guidelines, E2E testing policies, and the step-by-step development workflow (including how to run the Dev Container from your terminal), 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).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/niku/xlsxrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/niku/xlsxrb/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/niku/xlsxrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -174,4 +248,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Xlsxrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/niku/xlsxrb/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Xlsxrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -88,6 +88,12 @@ end
 task test: %i[build_sdk_runner ensure_reader_fixtures]
 
 namespace :test do
+  desc "Run tests with runtime type checking enabled (RBS_TEST=1)"
+  task :rbs do
+    ENV["RBS_TEST"] = "1"
+    Rake::Task["test:unit"].invoke
+    Rake::Task["test:contract"].invoke
+  end
   Rake::TestTask.new(:unit) do |t|
     t.libs << "test"
     t.libs << "lib"
@@ -139,7 +145,10 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+require "bundler/audit/task"
+Bundler::Audit::Task.new
+
+task default: %i[bundle:audit rubocop typecheck test]
 
 namespace :visual do
   desc "Generate docs/visual/ README.md explanation gallery"
@@ -192,11 +201,13 @@ task :wasm do
     require "open-uri"
     wasm_url = "https://cdn.jsdelivr.net/npm/@ruby/4.0-wasm-wasi@2.9.3-2.9.4/dist/ruby.wasm"
     FileUtils.mkdir_p(File.dirname(original_wasm_cache))
+    # rubocop:disable Security/Open
     URI.open(wasm_url) do |stream|
       File.open(original_wasm_cache, "wb") do |file|
         IO.copy_stream(stream, file)
       end
     end
+    # rubocop:enable Security/Open
     puts "Original ruby.wasm cached successfully."
   end
 
@@ -208,6 +219,8 @@ task :wasm do
 
   # A. Write custom static stubs and gateways dynamically
   File.write(File.join(bundle_assets_dir, "openssl.rb"), "# frozen_string_literal: true\n")
+  time_rb_path = $LOAD_PATH.lazy.map { |p| File.join(p, "time.rb") }.find { |f| File.exist?(f) }
+  FileUtils.cp(time_rb_path, bundle_assets_dir) if time_rb_path
 
   File.write(File.join(bundle_assets_dir, "opentelemetry.rb"), <<~RUBY)
     # frozen_string_literal: true
@@ -231,9 +244,7 @@ task :wasm do
 
   # Resolve and copy host's rexml files
   rexml_spec_path = $LOAD_PATH.find { |p| File.exist?(File.join(p, "rexml/rexml.rb")) }
-  if rexml_spec_path
-    FileUtils.cp_r(File.join(rexml_spec_path, "rexml"), bundle_assets_dir)
-  end
+  FileUtils.cp_r(File.join(rexml_spec_path, "rexml"), bundle_assets_dir) if rexml_spec_path
 
   # Gateway for strscan
   File.write(File.join(bundle_assets_dir, "strscan.rb"), <<~RUBY)
@@ -259,11 +270,11 @@ task :wasm do
   ]
   stdlib_files.each do |name|
     path = $LOAD_PATH.find { |p| File.exist?(File.join(p, name)) }
-    if path
-      dest_path = File.join(bundle_assets_dir, name)
-      FileUtils.mkdir_p(File.dirname(dest_path))
-      FileUtils.cp(File.join(path, name), dest_path)
-    end
+    next unless path
+
+    dest_path = File.join(bundle_assets_dir, name)
+    FileUtils.mkdir_p(File.dirname(dest_path))
+    FileUtils.cp(File.join(path, name), dest_path)
   end
 
   # C. Patch tmpdir.rb to automatically create /tmp in Wasm virtual filesystem (since Wasm has no writable /tmp by default)
@@ -286,92 +297,104 @@ task :wasm do
   puts "Building packed ruby.wasm from staging bundle..."
   cmd = "bundle exec rbwasm pack #{original_wasm_cache} --dir #{wasm_bundle_dir}::/usr/local/lib/ruby/site_ruby -o #{packed_wasm_path}"
   puts "Executing: #{cmd}"
-  unless system(cmd)
-    raise "Failed to build packed ruby.wasm using rbwasm pack!"
-  end
+  raise "Failed to build packed ruby.wasm using rbwasm pack!" unless system(cmd)
 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
 
-  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))
 
-    puts "Downloading #{url} to #{dest}..."
-    FileUtils.mkdir_p(File.dirname(dest))
+  require "net/http"
+  uri = URI.parse(url)
+  temp_dest = "#{dest}.tmp"
 
-    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"
 
-    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
+      http.request(request) do |response|
+        raise "HTTP error #{response.code}: #{response.message}" if response.code.to_i != 200
 
-          File.open(temp_dest, "wb") do |output|
-            response.read_body do |chunk|
-              output.write(chunk)
-            end
+        File.open(temp_dest, "wb") do |output|
+          response.read_body do |chunk|
+            output.write(chunk)
           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
+    # Atomic rename to prevent leaving incomplete files on failure
+    File.rename(temp_dest, dest)
+    puts "Downloaded successfully."
+
+    # Dynamic Brotli Decompression if the server ignored identity encoding and sent Brotli (.br) data
+    if File.exist?(dest) && File.binread(dest, 4)&.bytes == [0xCF, 0xFF, 0xFF, 0x7F]
+      puts "Detected Brotli compression on #{dest}. Decompressing..."
+
+      unpacked = "#{dest}.unpacked"
+      if system("brotli -d -f -o #{unpacked} #{dest}")
+        File.rename(unpacked, dest)
+        puts "Decompressed #{dest} successfully."
+      else
+        FileUtils.rm_f(unpacked)
+        raise "Failed to decompress Brotli file: #{dest}"
+      end
+    end
+  rescue StandardError => e
+    puts "Failed to download #{url}: #{e.message}"
+    FileUtils.rm_f(temp_dest)
+    FileUtils.rm_f(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)
+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"
+  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
+  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
+    # rubocop:disable Security/Open
+    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
+    # rubocop:enable Security/Open
+  rescue StandardError => e
+    puts "Failed to fetch Google Fonts CSS: #{e.message}"
+    return
+  end
 
-    urls = css_content.scan(/url\((https:\/\/fonts\.gstatic\.com\/[^\)]+)\)/).flatten
+  urls = css_content.scan(%r{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."
+  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
+
+desc "Fetch required external assets for offline usage"
+task :fetch_assets do
+  require "open-uri"
+  require "fileutils"
+
   # Fetch Ruby WASI JS
   download_file(
     "https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@2.9.3-2.9.4/dist/browser.umd.js",
@@ -389,16 +412,16 @@ task :fetch_assets do
 end
 
 desc "Generate RDoc documentation including Visual Gallery"
-task doc: [:wasm, :fetch_assets] do
+task doc: %i[wasm fetch_assets] do
   FileUtils.rm_rf("doc")
 
   # 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/"
+  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 CHANGELOG.md CODE_OF_CONDUCT.md docs/*.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")
@@ -435,13 +458,14 @@ task doc: [:wasm, :fetch_assets] do
   # 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">}
+    coi_tag = %(<script src="#{rel_prefix}coi-serviceworker.js"></script>)
+    js_tag = %(<script src="#{rel_prefix}js/wasm_doc_helper.js" defer></script>)
+    css_tag = %(<link href="#{rel_prefix}css/wasm_doc_helper.css" rel="stylesheet">)
 
     if html_content.include?("<body")
       modified = html_content.sub("<body", "#{coi_tag}\n#{js_tag}\n#{css_tag}\n<body")
@@ -467,15 +491,17 @@ namespace :doc do
       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) {
+      RequestCallback: lambda { |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'
+            first_bytes = begin
+              File.binread(local_path, 4)
+            rescue StandardError
+              nil
             end
+            res["Content-Encoding"] = "br" if first_bytes != "\x00asm"
           end
         end
       }
@@ -499,3 +525,12 @@ namespace :doc do
     end
   end
 end
+desc "Generate RBS signature files from inline annotations"
+task :sig do
+  sh "bundle exec rbs-inline --output lib/**/*.rb"
+end
+
+desc "Run static type checking with Steep"
+task typecheck: :sig do
+  sh "bundle exec steep check"
+end

data/Steepfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+
+  check "lib/xlsxrb.rb"
+
+  library "date"
+  library "time"
+  library "securerandom"
+  library "openssl"
+  library "pathname"
+  library "tempfile"
+  library "bigdecimal"
+
+  repo_path "sig"
+
+  configure_code_diagnostics(Steep::Diagnostic::Ruby.lenient)
+end

data/docs/ARCHITECTURE.md

@@ -18,6 +18,23 @@ Xlsxrb uses **only** the Ruby standard library and Bundled Gems:
 
 ---
 
+## Coding Policies
+
+### 🚫 The `method_missing` Policy
+As a strict rule, **we do not accept dynamic method definitions using `method_missing`** anywhere in the codebase. All user-facing API methods and internal delegations must be explicitly defined in the code. This ensures:
+1. **Type Safety & Static Analysis**: RBS and Steep can completely validate arguments and structures.
+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.
+
+### 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.
+
+---
+
 ## Directory Structure
 
 ```

data/docs/DEVELOPMENT.md

@@ -65,3 +65,61 @@ Omission is only acceptable when **all** of the following hold:
 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.
+
+---
+
+## Development via Dev Container
+
+The project is pre-configured with a Dev Container to simplify local environment setup (installing .NET, LibreOffice, ImageMagick, and Noto fonts).
+
+### VS Code (GUI)
+You can open this repository in VS Code and select **"Dev Containers: Reopen in Container"** from the Command Palette.
+
+### Terminal (Devcontainer CLI)
+If you prefer to use the terminal instead of VS Code, you can run the devcontainer using the official `@devcontainers/cli`:
+
+1. Install the CLI on your host machine (if not already installed):
+   ```bash
+   npm install -g @devcontainers/cli
+   ```
+2. Use the helper script `bin/devcontainer` to start and interact with the container:
+   - **Interactive shell** (Automatically shares your host's Git/AI tool configs as read-only):
+     ```bash
+     bin/devcontainer
+     ```
+   - **Run commands directly**:
+     ```bash
+     bin/devcontainer rake test
+     ```
+
+### Customizing with Personal Overrides (e.g., Dotfiles, API Keys, Shell History)
+
+The `bin/devcontainer` script dynamically parses a personal configuration patch and maps it to devcontainer CLI flags on startup. This is a workaround for a specification limit of devcontainer CLI's `--override-config` flag, which acts as a complete replacement of the configuration rather than a partial merge, wiping out base configurations like build settings.
+
+To configure this, create a JSON (or JSONC) file at `${XDG_CONFIG_HOME:-~/.config}/devcontainer/override.jsonc` (or `override.json`) on your host machine.
+
+**Example: Persisting histories, forwarding API keys, and Auto-installing Dotfiles**
+```json
+{
+  "mounts": [
+    // Volume for general persistent directories (e.g., Claude Code history in ~/.local/share/claude)
+    "type=volume,source=xlsxrb-local-share,target=/home/vscode/.local/share"
+  ],
+  "containerEnv": {
+    // Explicitly forward API keys from your host shell to the container environment
+    "OPENAI_API_KEY": "${localEnv:OPENAI_API_KEY}",
+    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
+    "GEMINI_API_KEY": "${localEnv:GEMINI_API_KEY}"
+  },
+  "dotfiles": {
+    "repository": "https://github.com/<your-github-username>/dotfiles.git",
+    "targetPath": "~/dotfiles",
+    "installCommand": "install.sh"
+  }
+}
+```
+
+You can also use a custom file path by exporting the `DEVCONTAINER_OVERRIDE_CONFIG` environment variable in your host shell:
+```bash
+export DEVCONTAINER_OVERRIDE_CONFIG="/path/to/your/custom-override.json"
+```

data/docs/QUALITY_ASSURANCE.md

@@ -0,0 +1,26 @@
+# Quality Assurance (QA) & Testing Architecture
+
+`xlsxrb` is designed to be an enterprise-grade, highly reliable, and highly performant library for reading and writing Excel spreadsheets. To achieve and maintain this standard, we have implemented a comprehensive Quality Assurance matrix that covers everything from static code analysis and dynamic runtime validation to performance benchmarking and visual regression testing.
+
+Below is an overview of the inspection mechanisms, when they run, the quality attributes they guarantee, and the specific bugs they prevent.
+
+## QA Matrix
+
+| Inspection Mechanism / Tool | Execution Command / Mechanism | Local | CI (PR/Push) | Scheduled (Weekly) | Target Quality Attribute | Validation Method | Prevented Bugs / Issues |
+| :--- | :--- | :---: | :---: | :---: | :--- | :--- | :--- |
+| **RuboCop** | `rake rubocop` | ⭕ | ⭕ | - | Readability / Maintainability | Static Analysis (Syntax/Linting) | Overly complex methods, non-standard syntax, unused variables. |
+| **Steep & RBS** | `rake typecheck` | ⭕ | ⭕ | - | Type Safety (Static) | Static Analysis (Type Check) | `NoMethodError`, passing incorrect arguments, method typo bugs. |
+| **Bundler Audit** | `rake audit` | - | ⭕ | - | Security | Dependency Scanning | Inclusion of external gems with known vulnerabilities (CVEs). |
+| **Dependabot** | `.github/dependabot.yml` | - | - | ⭕ | Currency / Maintenance | Repository Monitoring | Outdated dependencies or CI actions. |
+| **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)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
+
+| **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. |
+| **E2E Interoperability Tests** | `rake test:e2e` | △ (Opt-in) | ⭕ | - | Compatibility (Real-world) | 3rd-party SDK Execution | Structural defects so severe that the official .NET SDK cannot read them. |
+| **Load / Stress Testing** | Action: `benchmark.yml` | - | ⭕ | - | Performance / Stability | Massive Data Generation (e.g., 10k+ rows) | Out of Memory (OOM) crashes or extreme delays when processing large datasets. |
+| **Memory & Speed Benchmark** | Action: `benchmark.yml` | - | ⭕ | - | Performance | Continuous Profiling | Memory leaks, severe performance degradation due to inefficient loop additions. |
+| **Visual Regression Testing (VRT)** | `rake test:visual` | - | ⭕ | - | Visual Accuracy (UI/UX) | Headless Rendering / Pixel Diff | Visual bugs like "cell background colors dropping" or "chart layouts breaking" after code changes. |
+