AGENTS.md

Single source of truth for AI coding agents (Claude Code, Codex, Cursor, Copilot, ...) working on this repo. CLAUDE.md is a symlink to this file: edit only AGENTS.md; there are no other per-tool instruction files.

Writing ruby2html templates/components (here or in a user app)? Load llms.txt — the complete user reference (DSL, attributes, Rails, components, forms, API, pitfalls). Internals: docs/architecture.md. Releases: docs/release.md.

Stack

ruby2html (RubyGems; version in lib/gem/ruby2html/version.rb) renders HTML from a Ruby block DSL; the repo is both the gem and a Rails demo app.

• Supported: all maintained CRuby versions (>= 3.1, gemspec floor; CI tracks the official list — currently 3.3, 3.4, 4.0), JRuby (pure Ruby + the Java escaper), TruffleRuby (pure Ruby), Rails 7.2+.
• Dev Ruby: .ruby-version (latest stable). The CRuby CI matrix is generated automatically from the maintained-versions list, so a new release (e.g. a new 4.x) joins CI with no edit.
• rubocop TargetRubyVersion matches the floor (no newer syntax in lib/).
• Dependency versions: Gemfile.lock and gemfiles/*.gemfile (CI matrix gemfiles, unlocked).

Non-negotiables

Commands

• Gem tasks (compile clean clobber spec spec:gem spec:standalone bench smoke build install release default) do not boot Rails; any other task loads the Rails tasks. RUBY2HTML_RAILS_TASKS=1 forces that.
• After editing ext/ always rake compile; otherwise specs run the stale .so (or PureRuby if none).
• Never run rake release, push v* tags or gem push: merging a version bump to main is the release (docs/release.md).

Code map

How to verify a change

Sharp edges / invariants

1. Native and PureRuby must produce byte-identical output (HTML, encoding, raised errors) for every input. Any rule change goes into content.c/attributes.c/tag_render.c and pure_ruby.rb, with specs in the RenderSpecHelper.describe_each groups / render_parity_spec.rb; start-tag exceptions roll the buffer back to before the tag (both sides). The JRuby Java escaper (ext/java) is a third side of the escape rule only: byte-identical with html_escape.c / PureRuby.escape (the JRuby standalone run exercises it, and a render_spec example checks it is loaded and matches).
2. Never cache by Object#hash: collisions return another input's output (the old ATTRIBUTE_CACHE did exactly this and was removed). Exact-equality keys only, and only with a benchmark proving a win.
3. GC safety in C: any VALUE whose RSTRING_PTR/internal pointer is used after a call that can allocate or yield (rb_funcall, rb_yield, rb_str_*, rb_obj_as_string) needs RB_GC_GUARD(v) after its last use; re-read RSTRING_PTR(buf) after anything that can grow buf; use buffer.h (r2h_buf_reserve/commit), never manual rb_str_set_len arithmetic.
4. Escaping is a security boundary. Text and attribute values escaped by default; raw only for html_safe? objects and component; plain String (exact class) never safe. Attribute/tag names are validated (raise), not escaped. Every escaping change: specs (both modes) + xss-auditor pass.
5. Speed over memory. No per-call allocations on hot paths (tag methods, plain, attributes, escape); intern IDs at Init; write straight into the output buffer; generate at load/compile time, not per call. Perf claims need before/after numbers (.claude/skills/benchmark).
6. Tag methods: max one positional arg; with a block the block wins; a block's return value counts only if the block wrote nothing (String/Symbol/Numeric); void tags ignore content and block.
7. Renderer method_missing forwards only public context methods; forwarded return values are not appended. Compiled .html.rb templates and Ruby2html::Component run with self = view/component (no forwarding); ComponentHelper#html blocks and the closure fallback run on the renderer, so tag names beat same-named component methods/slots (header renders <header>).
8. Never add public Render methods whose names are tag names (Render#output once hid <output>). In compiled templates capture/content_for/provide route to TemplateHelpers, which swaps the renderer buffer (ActionView's own capture can't see ruby2html output); inside ViewComponent html blocks they still go to the view.
9. TemplateCompiler inserts text only (never newlines) so template line numbers stay correct; it skips def/class/module bodies, explicit-receiver calls, and Render.new { } blocks (they run on their own renderer).
10. Adding a tag: HTML5_TAGS (+ VOID_ELEMENTS) only; no C change unless exceeding 200 tags or 32-char names (.claude/skills/add-html-tag).
11. Public API used downstream — Render.new(ctx, &blk), #render, #plain, #component, tag methods, Ruby2html.escape_html, Ruby2html.native?, Ruby2html::Component, RailsHelper#html, ComponentHelper#html / #__ruby2html_renderer__, the .rb handler, HtmlBeautifierMiddleware — breaking changes need a CHANGELOG entry ("Upgrading to 2.0") and a major bump.
12. Style: rubocop-rails_config, single quotes, # frozen_string_literal: true, nested modules, Rails-style indented private methods. C: gnu99, no warnings under -Wall -Wextra.
13. Never commit lib/ruby2html/*.so, *.jar, *.class, tmp/, pkg/, *.gem, log/.

Maintenance model

Goal: the repo needs no hand maintenance except major-version dependency upgrades.

AI tooling in this repo

Definition of done

rake compile clean → CI=1 bundle exec rspec and RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem green → bundle exec rubocop clean → CHANGELOG/docs updated if behavior changed → benchmark numbers if a speedup is claimed.