[Feature] Golden HTML suite: the 1.6 parity ruler

[cirdes]

What

Adds the golden HTML suite: every component in the catalog is rendered, reduced
to a canonical form by an HTML5-spec parser, and compared byte-for-byte against
a committed snapshot. 188 snapshots over 54 component directories.

Three coverage tests stop the ruler from quietly shrinking: every component
directory must have a scenario, every RubyUI::Base subclass must actually
render in one (recorded at before_template, not at initialize), and no
snapshot may exist without a scenario. The normalizer is asserted to be
idempotent over every snapshot on every run, which is what makes the final byte
comparison a structural comparison rather than a string one, and every scenario
is rendered twice to catch unpinned randomness.

rake golden is reached by rake test, so CI covers it on Ruby 3.3 and 3.4
with no workflow change. nokogiri is added as a development dependency; the
gem still ships with no runtime dependencies.

Why now

This is Phase 1 of design/2026-09-19-rubyui-2-0-design.md, which this PR
also carries along with its implementation plan. The 2.0 migration replaces
Phlex with plain Ruby classes and ERB templates, and it needs an executable
definition of "the HTML did not change" before the first component moves. A
ruler written after the thing it measures is not a ruler.

It also earns its place on main on its own: it catches markup regressions in
ordinary bug-fix PRs today.

Also in this PR

• The ruler is hardened against five false equivalences found in review,
  each with a test that failed before its fix: a stray </template> silently
  truncated the input; an empty element and a whitespace-only element compared
  equal (they are different to FormField's controller and to empty:hidden);
  class tokens and text collapsed on Ruby's \s, which includes U+000B, rather
  than HTML's whitespace; and the LF the parser drops after <pre> /
  <textarea> was never re-emitted, so a preserved block starting with a blank
  line could not be pinned. No recorded snapshot changed.
• HoverCard snapshots re-recorded. [Bug Fix] HoverCard: let the card escape a clipping ancestor #530 changed its markup after the
  snapshots were first taken. Those two files are the only difference between
  the recording on v2-herb and the recording against main — which is what
  validates the ruler.
• ContextMenuLabel bug fix. class: [..., inset?: "pl-8"] is an Array
  whose second element is a Hash, so every label shipped a literal
  {inset?: "pl-8"} class token, inset: never applied pl-8, and the
  output differed between Ruby 3.3 and 3.4. Fixing it pins the last two
  unpinned scenarios. The MCP registry is rebuilt to match.
• A whitespace inventory. The canonical form is, by design, blind to
  whitespace between element siblings and at text boundaries.
  gem/test/golden/tools/inline_adjacency.rb lists candidate spots; the
  decision it informs — an inventory, not a bound — and the observations from
  the whole-branch review are in design/v2/decisions.md.
• gem/Gemfile.lock gains the x86_64-linux platform so CI installs the
  prebuilt nokogiri instead of compiling it per job.

Test steps

cd gem
bundle exec rake golden    # the suite plus the ruler's own tests
bundle exec rake           # unit tests + golden + standardrb

Both green, zero skips. To see the ruler work, change a class in any component
and re-run rake golden. To see the hardening, feed
Golden::CanonicalHtml.call a <div>\n</div> and a <div></div>.

🤖 Generated with Claude Code

---

Summary by cubic

Adds the golden HTML suite that renders every component, normalizes the output with an HTML5 parser, and compares it byte-for-byte against committed snapshots, giving the RubyUI 2.0 migration an executable definition of "the HTML did not change." rake golden runs under rake test, so CI covers all 188 snapshots on Ruby 3.3 and 3.4 with no workflow change. The PR also carries the RubyUI 2.0 design doc and Phase 1 plan, defers follow-up issues #537–#543 to the 2.0 line, and keeps the docs generator in 2.0.

New Features

• Coverage tests require every component directory, every RubyUI::Base subclass, and every snapshot to have a matching scenario; scenarios render twice to catch unpinned randomness, and the normalizer is checked for idempotence on every snapshot on every run.
• rake golden:update re-records snapshots; nokogiri is a development dependency only.
• rake golden also runs the ruler's own tests.

Bug Fixes

• Fixes ContextMenuLabel so inset: applies pl-8; it previously emitted a literal {inset?: "pl-8"} class token.
• Hardens the normalizer against a stray </template> truncating output, empty vs whitespace-only elements, non-HTML whitespace, and lost newlines after <pre>/<textarea>.
• Keeps the canonical form a fixed point for nested preserved and raw-text elements; the normalizer hardening changes no snapshot.
• Re-records HoverCard snapshots and 47 snapshots carrying xmlns:xmlns; the harness bounds pinned ranges before materialising them, proves the same value returns on every render, and lets golden:update run after golden in the same rake process.
• Fixes the custom-keybindings command scenario to use keydown.ctrl+p@window so the snapshot pins a keybinding that actually fires.

^{Written for commit ca928cb. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 208 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="gem/AGENTS.md">

<violation number="1" location="gem/AGENTS.md:37">
P3: `bundle exec rake test N=/button/` does not do what this comment claims. Rake turns `N=/button/` into an unused environment variable; `Minitest::TestTask` (used in gem/Rakefile) consumes neither `N=` nor `TEST=`, so the `-n` filter is silently ignored and the whole suite runs. Either pass the filter to the runner's command line (`bundle exec rake test TESTOPTS="-n /button/"` is minitest's documented rake path) or point to a ruby invocation like `bundle exec ruby -Ilib:test test/ruby_ui/button_test.rb -n /button/`. Please verify the documented command narrows the run before merging, since the parenthetical promises single-test behavior.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 55 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>