ruact 0.0.7 → 0.0.8

data/lib/ruact/testing/flight_wire_parser.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "strscan"
+require "json"
+
+module Ruact
+  # Public, host-app-facing test-support surface (FR108, Story 15.4). Loaded
+  # ONLY by an explicit `require "ruact/testing"` (or one of the files under
+  # `ruact/testing/`) — never by `require "ruact"`, so a production boot carries
+  # no RSpec/test dependency. The pure wire parser + structural diff engine live
+  # here as the SINGLE shipped implementation shared by both the public
+  # `have_ruact_component` matcher and the gem's internal `Ruact::Spec::*`
+  # matchers (promoted from `spec/support` in Story 15.4 — wrap, not fork).
+  module Testing
+    # Raised when {FlightWireParser.parse} encounters input it cannot decode.
+    # The message names the byte offset of the unparseable row so the caller
+    # can locate the problem in a printed wire string.
+    class FlightWireParseError < StandardError; end
+
+    # Parses a Flight wire byte string into an ordered array of row records.
+    #
+    # Used by the structural Flight matchers to assert on parsed semantics
+    # rather than literal bytes. Pure function — no I/O, no global state, no
+    # `Thread.current`.
+    #
+    # @example
+    #   wire = "1:I[\"/L.jsx\",\"L\",[\"/L.jsx\"]]\n0:[\"$\",\"$L1\",null,{}]\n"
+    #   Ruact::Testing::FlightWireParser.parse(wire)
+    #   # => [
+    #   #      { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]], raw: "1:I...\n" },
+    #   #      { id: 0, class: :model,  payload: ["$", "$L1", nil, {}],       raw: "0:[\"$\"...\n" }
+    #   #    ]
+    class FlightWireParser
+      # Parse a complete Flight wire byte string.
+      #
+      # @param wire [String] the raw bytes emitted by `Ruact::Flight::Renderer`.
+      # @return [Array<Hash>] one hash per row, in wire order. See class docs
+      #   for the hash shape (`:id`, `:class`, `:payload`, `:raw`).
+      # @raise [Ruact::Testing::FlightWireParseError] when a row is malformed.
+      def self.parse(wire)
+        rows = []
+        scanner = StringScanner.new(wire)
+
+        until scanner.eos?
+          start_offset = scanner.pos
+          rows << parse_row(scanner, start_offset)
+        end
+
+        rows
+      end
+
+      def self.parse_row(scanner, start_offset)
+        # Hint rows have no ID: ":H<code><json>\n"
+        if scanner.peek(2) == ":H"
+          scanner.pos += 2
+          code = scanner.getch
+          raise_parse_error(start_offset, "missing hint code char") if code.nil?
+
+          json = read_to_newline(scanner, start_offset)
+          return {
+            id: nil,
+            class: :hint,
+            payload: [code, parse_json(json, start_offset)],
+            raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+          }
+        end
+
+        hex = scanner.scan(/\h+/) || raise_parse_error(start_offset, "expected hex id")
+        scanner.skip(":") || raise_parse_error(start_offset, "expected ':' after id")
+        id = hex.to_i(16)
+
+        case scanner.peek(1)
+        when "I" then parse_tagged(:import, scanner, id, start_offset)
+        when "T" then parse_text_row(scanner, id, start_offset)
+        when "E" then parse_tagged(:error, scanner, id, start_offset)
+        else          parse_model_row(scanner, id, start_offset)
+        end
+      end
+
+      def self.parse_tagged(klass, scanner, id, start_offset)
+        scanner.getch # consume the tag byte (I or E)
+        json = read_to_newline(scanner, start_offset)
+        {
+          id: id,
+          class: klass,
+          payload: parse_json(json, start_offset),
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.parse_model_row(scanner, id, start_offset)
+        json = read_to_newline(scanner, start_offset)
+        {
+          id: id,
+          class: :model,
+          payload: parse_json(json, start_offset),
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.parse_text_row(scanner, id, start_offset)
+        scanner.getch # consume "T"
+        len_hex = scanner.scan(/\h+/) || raise_parse_error(start_offset, "expected hex length after T")
+        scanner.skip(",") || raise_parse_error(start_offset, "expected ',' after T<len>")
+        len = len_hex.to_i(16)
+
+        text = scanner.peek(len)
+        raise_parse_error(start_offset, "T row truncated") if text.nil? || text.bytesize < len
+
+        scanner.pos += len
+        {
+          id: id,
+          class: :text,
+          payload: text,
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.read_to_newline(scanner, start_offset)
+        line = scanner.scan_until(/\n/) || raise_parse_error(start_offset, "missing trailing newline")
+        line.chomp
+      end
+
+      def self.parse_json(str, offset)
+        JSON.parse(str)
+      rescue JSON::ParserError => e
+        raise_parse_error(offset, "invalid JSON: #{e.message}")
+      end
+
+      def self.raise_parse_error(offset, reason)
+        raise FlightWireParseError, "FlightWireParser: cannot parse row at offset #{offset}: #{reason}"
+      end
+
+      private_class_method :parse_row, :parse_tagged, :parse_model_row, :parse_text_row,
+                           :read_to_newline, :parse_json, :raise_parse_error
+    end
+  end
+end

data/lib/ruact/testing.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+require_relative "testing/flight_wire_parser"
+require_relative "testing/flight_structure_diff"
+require_relative "testing/flight_extractor"
+require_relative "testing/component_query"
+
+# Public, host-app-facing render-assertion helpers (FR108, Story 15.4).
+#
+# Load this EXPLICITLY from your `spec_helper.rb`/`rails_helper.rb`:
+#
+#   require "ruact/testing"
+#
+# It is NOT auto-loaded by `require "ruact"` — a production boot never pulls in
+# RSpec. Requiring this file registers the `have_ruact_component` RSpec matcher
+# so request/controller specs can assert a page rendered a given component:
+#
+#   expect(response).to have_ruact_component("PostList")
+#   expect(response).to have_ruact_component("PostList").with_props(including("posts"))
+#   expect(response).not_to have_ruact_component("Admin")
+#
+# `response` may be an ActionDispatch/Rack response (its `.body` is read) or a
+# raw String, in either page shape: a raw `text/x-component` body or an HTML
+# shell embedding `__FLIGHT_DATA`. A `Ruact::Server` function-call/query answer
+# is plain JSON, not Flight — passing it raises a clear error pointing you at
+# `JSON.parse(response.body)` (see the "Testing" docs page).
+#
+# This is a STABLE public API (a conventional test matcher) — it wraps, and
+# does not fork, the internal Story-7.5 structural parser/diff promoted to
+# `Ruact::Testing::FlightWireParser` / `Ruact::Testing::FlightStructureDiff`.
+module Ruact
+  module Testing
+    # Compares a rendered instance's serialized props against the value passed
+    # to `.with_props`. A plain Hash requires exact equality (via `===`, i.e.
+    # `==`); an RSpec argument matcher (`hash_including`, `including`, `a_hash_…`)
+    # drives subset/fuzzy semantics through its own `#===`.
+    def self.props_match?(expected, actual_props)
+      # rubocop:disable Style/CaseEquality -- intentional: lets RSpec matchers (hash_including, …) drive semantics via #===.
+      expected === actual_props
+      # rubocop:enable Style/CaseEquality
+    end
+  end
+end
+
+# rubocop:disable Metrics/BlockLength -- a single cohesive RSpec matcher definition (match + chain + messages).
+RSpec::Matchers.define :have_ruact_component do |name|
+  match do |actual|
+    @query = Ruact::Testing::ComponentQuery.new(Ruact::Testing::FlightExtractor.extract(actual))
+    @instances_props = @query.props_for(name)
+    next false if @instances_props.empty?
+    next true unless defined?(@expected_props)
+
+    @instances_props.any? { |props| Ruact::Testing.props_match?(@expected_props, props) }
+  end
+
+  chain :with_props do |expected|
+    @expected_props = expected
+  end
+
+  failure_message do |_actual|
+    if @instances_props && @instances_props.empty?
+      rendered = @query.rendered_names
+      found = rendered.empty? ? "no ruact components" : "components: #{rendered.inspect}"
+      "expected the response to have rendered a ruact component named #{name.inspect}, " \
+        "but found #{found}."
+    else
+      "expected a rendered #{name.inspect} to have props matching #{@expected_props.inspect}, " \
+        "but none did. Rendered instance props (serialized wire form):\n" \
+        "#{@instances_props.map(&:inspect).join("\n")}"
+    end
+  end
+
+  failure_message_when_negated do |_actual|
+    if defined?(@expected_props)
+      "expected the response NOT to have a #{name.inspect} with props matching " \
+        "#{@expected_props.inspect}, but one did."
+    else
+      "expected the response NOT to have rendered a ruact component named #{name.inspect}, " \
+        "but it did."
+    end
+  end
+
+  description do
+    base = "have ruact component #{name.inspect}"
+    defined?(@expected_props) ? "#{base} with props #{@expected_props.inspect}" : base
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/lib/tasks/ruact.rake

@@ -1,10 +1,63 @@
 # frozen_string_literal: true
 
 namespace :ruact do
-  desc "Check ruact installation and configuration (FR27)"
+  # Story 15.3 (FR107) — `--json` is passed after a `--` separator so neither
+  # Rails nor Rake tries to parse it as an option: `bin/rails ruact:doctor -- --json`.
+  # Everything after `--` lands in ARGV, which the task scans. A captured local
+  # (not a constant) so re-loading this rakefile — e.g. specs that load it into
+  # an isolated Rake::Application — does not warn about constant redefinition.
+  json_mode = -> { ARGV.include?("--json") }
+
+  desc "Check ruact installation and configuration (FR27). Append `-- --json` " \
+       "for a machine-readable report (EXPERIMENTAL shape — gate on schema_version)."
   task doctor: :environment do
     require "ruact/doctor"
-    exit 1 unless Ruact::Doctor.run
+
+    if json_mode.call
+      require "json"
+      report = Ruact::Doctor.new.as_json
+      puts JSON.pretty_generate(report)
+      exit 1 unless report["status"] == "pass"
+    else
+      exit 1 unless Ruact::Doctor.run
+    end
+  end
+
+  # Story 15.3 (FR107) — read-only introspection of the accessor/route table
+  # (the SAME single source of truth codegen consumes) for headless agents & CI.
+  # Side-effect-free: it does NOT write the codegen bridge or the TS module.
+  # `-- --json` emits the machine-readable document; the bare task prints a
+  # compact human table. Exits 1 (message on stderr) on a naming collision,
+  # mirroring `ruact:server_functions:generate`.
+  desc "Print the ruact accessor/route table. Append `-- --json` for a " \
+       "machine-readable document (EXPERIMENTAL shape — gate on schema_version)."
+  task routes: :environment do
+    require "ruact/server_functions"
+
+    begin
+      Rails.application.routes_reloader.execute_unless_loaded
+
+      if json_mode.call
+        require "json"
+        puts JSON.pretty_generate(
+          Ruact::ServerFunctions::Introspection.as_json(route_set: Rails.application.routes)
+        )
+      else
+        entries = Ruact::ServerFunctions.introspect(route_set: Rails.application.routes)
+        if entries.empty?
+          puts "[ruact] no server-function accessors (no Ruact::Server actions or mounted queries)"
+        else
+          puts "[ruact] server-function accessors:"
+          entries.each do |entry|
+            puts format("  %-6<verb>s %-28<accessor>s %<path>s",
+                        verb: entry["http_method"], accessor: entry["js_identifier"], path: entry["path"])
+          end
+        end
+      end
+    rescue Ruact::ConfigurationError, Errno::ENOENT, JSON::ParserError => e
+      warn "[ruact] error: #{e.message}"
+      exit 1
+    end
   end
 
   namespace :server_functions do

data/spec/ruact/doctor_spec.rb

@@ -511,6 +511,141 @@ RSpec.describe Ruact::Doctor do
     end
   end
 
+  # --- JSON introspection (Story 15.3, FR107, AC1 + AC3 + AC4) ---
+
+  describe "#as_json (machine-readable report)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    context "when all checks pass" do
+      before do
+        make_manifest
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+      end
+
+      it "returns a document that round-trips through JSON.parse", :aggregate_failures do
+        report = doctor.as_json
+        reparsed = JSON.parse(JSON.generate(report))
+        expect(reparsed).to eq(report)
+      end
+
+      it "gates the document with the EXPERIMENTAL schema_version (0)" do
+        expect(doctor.as_json["schema_version"]).to eq(0)
+        expect(doctor.as_json["schema_version"]).to eq(Ruact::Doctor::SCHEMA_VERSION)
+      end
+
+      it "carries every check with name/status/message/remediation keys", :aggregate_failures do
+        checks = doctor.as_json["checks"]
+        expect(checks.map { |c| c["name"] }).to eq(described_class::CHECKS.map(&:to_s))
+        checks.each do |check|
+          expect(check.keys).to contain_exactly("name", "status", "message", "remediation")
+          expect(check["status"]).to be_a(String)
+          expect(check["message"]).to be_a(String)
+        end
+      end
+
+      it "reports top-level status 'pass' and exits-zero semantics" do
+        expect(doctor.as_json["status"]).to eq("pass")
+      end
+
+      it "emits NO prose to stdout (JSON mode is the document only)" do
+        expect { doctor.as_json }.not_to output.to_stdout
+      end
+    end
+
+    context "when a check fails" do
+      before do
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+        # manifest is missing → check_manifest fails
+      end
+
+      it "reports top-level status 'fail' (non-zero exit semantics)" do
+        expect(doctor.as_json["status"]).to eq("fail")
+      end
+
+      it "carries the separate machine-readable remediation for the failing check" do
+        manifest = doctor.as_json["checks"].find { |c| c["name"] == "manifest" }
+        expect(manifest["status"]).to eq("fail")
+        expect(manifest["remediation"]).to eq("Run vite build (or bin/dev) to generate the client manifest.")
+      end
+    end
+
+    context "when a check warns (Rack::Deflater mounted)" do
+      before do
+        make_manifest
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+        app = Struct.new(:middleware).new([Struct.new(:name).new("Rack::Deflater")])
+        allow(Rails).to receive(:application).and_return(app)
+      end
+
+      it "keeps status 'pass' — a :warn does not fail — but exposes the warn check" do
+        report = doctor.as_json
+        expect(report["status"]).to eq("pass")
+        flight = report["checks"].find { |c| c["name"] == "flight_middleware" }
+        expect(flight["status"]).to eq("warn")
+        expect(flight["remediation"]).to include("Exclude text/x-component from compression")
+      end
+    end
+
+    it "keeps the message byte-identical to the human tuple (remediation is separate)" do
+      _status, human_message = doctor.send(:check_manifest)
+      json_message = doctor.as_json["checks"].find { |c| c["name"] == "manifest" }["message"]
+      expect(json_message).to eq(human_message)
+    end
+  end
+
+  describe "#results / #passed? (shared compute, Story 15.3)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    before do
+      make_manifest
+      make_controller(with_include: true)
+      make_layout(with_sentinel: true)
+      allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+    end
+
+    it "returns one tuple per check, index-aligned with CHECKS" do
+      expect(doctor.results.length).to eq(described_class::CHECKS.length)
+    end
+
+    it "passed? is true when all checks pass/warn" do
+      expect(doctor.passed?).to be true
+    end
+
+    it "runs each check exactly once (as_json does not double-run check_vite's socket)" do
+      # check_vite opens a socket via TCPSocket.new; a single as_json must open it
+      # exactly once — proving #results is computed once, not per consumer.
+      doctor.as_json
+      expect(TCPSocket).to have_received(:new).once
+    end
+  end
+
+  describe "#run stays byte-identical after the #results refactor (Story 15.3, AC4a)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    before do
+      make_manifest
+      make_controller(with_include: true)
+      make_layout(with_sentinel: true)
+      allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+    end
+
+    it "prints exactly the header + one format_result line per check (no JSON/prose leak), returns true" do
+      # Reconstruct the expected output from the SAME format_result the human
+      # path uses — proves #run still emits header + one glyph line per check
+      # (the optional 3rd remediation element is ignored) and nothing else.
+      lines = doctor.results.map { |status, message| doctor.send(:format_result, status, message) }.join("\n")
+      expected = "[ruact] Health check\n#{lines}\n"
+
+      expect { expect(doctor.run).to be true }.to output(expected).to_stdout
+    end
+  end
+
   describe "Rake task definition (Story 5.12)", :story_5_12 do
     # Loads gem/lib/tasks/ruact.rake into a fresh Rake::Application so the
     # task table is isolated from any other spec that may have loaded tasks.
@@ -549,5 +684,11 @@ RSpec.describe Ruact::Doctor do
       # actions is a list of Procs; just assert at least one is attached
       expect(task.actions).not_to be_empty
     end
+
+    it "defines Rake::Task['ruact:routes'] with an action (Story 15.3)", :story_15_3 do
+      task = rake_app.lookup("ruact:routes")
+      expect(task).not_to be_nil
+      expect(task.actions).not_to be_empty
+    end
   end
 end

data/spec/ruact/erb_preprocessor_spec.rb

@@ -116,6 +116,151 @@ module Ruact
       end
     end
 
+    # Story 15.2 (FR106) — children inside a PascalCase component tag (a matching
+    # closing tag) fail LOUDLY at preprocess time instead of degrading silently.
+    describe "loud children error (FR106)", :story_15_2 do
+      def run(source, identifier: nil)
+        described_class.transform(source, identifier: identifier)
+      end
+
+      it "raises on `<Card>Hello</Card>` naming component + fix (AC#1)" do
+        expect { run("<Card>Hello</Card>") }
+          .to raise_error(ChildrenNotSupportedError) do |e|
+            expect(e.message).to include("Card")
+            expect(e.message).to include("children are not supported")
+            expect(e.message).to include("pass content as a prop")
+            expect(e.message).to include("<Card content={...} />")
+          end
+      end
+
+      it "is a Ruact::PreprocessorError (AC#1 — subclass IS-A base)" do
+        expect { run("<Card>Hello</Card>") }.to raise_error(Ruact::PreprocessorError)
+      end
+
+      it "raises on an empty pair `<Card></Card>` (AC#1)" do
+        expect { run("<Card></Card>") }.to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      it "raises on multi-line children (AC#1)" do
+        source = "<Card>\n  <p>hi</p>\n</Card>"
+        expect { run(source) }.to raise_error(ChildrenNotSupportedError, /children are not supported/)
+      end
+
+      it "raises on a paired tag that also holds a nested component" do
+        expect { run("<Card><Button /></Card>") }
+          .to raise_error(ChildrenNotSupportedError, /<Card>/)
+      end
+
+      it "names the supplied identifier and the correct line for a non-first-line pair (AC#4)" do
+        source = "line1\nline2\n<Card>Hello</Card>"
+        expect { run(source, identifier: "app/views/posts/show.html.erb") }
+          .to raise_error(ChildrenNotSupportedError) do |e|
+            expect(e.message).to include("app/views/posts/show.html.erb:3")
+          end
+      end
+
+      it "reports the opening tag's line, honoring attributes on the opening tag" do
+        expect { run("<Card variant={:wide}>x</Card>", identifier: "t.erb") }
+          .to raise_error(ChildrenNotSupportedError, /t\.erb:1/)
+      end
+
+      # Regression (Codex Round 1, Patch 1): a MULTI-LINE Suspense opening tag
+      # must not shift the reported line — the `<Card>` below is physically on
+      # line 5 and must report :5 (Suspense is masked newline-for-newline).
+      it "reports the exact source line even after a multi-line Suspense opening" do
+        source = <<~ERB
+          <Suspense
+            fallback="loading"
+            delay="2.5">
+          </Suspense>
+          <Card>Hello</Card>
+        ERB
+        expect { run(source, identifier: "t.erb") }
+          .to raise_error(ChildrenNotSupportedError, /t\.erb:5/)
+      end
+
+      # Regression (Codex Round 2, Patch 1): a `</Dialog>` living inside an ERB
+      # island (Ruby string/comment) must NOT be mistaken for a real component
+      # closing tag — a valid bare `<Dialog open={true}>` stays valid.
+      it "does not false-pair a bare opening with a `</Tag>` inside an ERB island" do
+        source = %(<Dialog open={true}>\n<% x = "</Dialog>" %>)
+        expect { run(source) }.not_to raise_error
+      end
+
+      it "still fires when the closing tag is real ERB body, not inside `<% %>`" do
+        expect { run("<Card><%= @body %></Card>") }
+          .to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      # Regression (Codex Round 2, Patch 2): many bare non-self-closing openings
+      # with no close must stay linear (single-pass stack scan) and silent (D3).
+      it "stays silent and does not blow up on many bare unclosed openings" do
+        source = "<Dialog open={true}>\n" * 5000
+        expect { run(source) }.not_to raise_error
+      end
+
+      # Regression (Codex Round 3, Patch 1): stray/unmatched PascalCase closing
+      # tags (no preceding matching open) are literal text — never an error — and
+      # must stay linear (per-name O(1) lookup, no `rindex`). Correctness pin;
+      # perf verified live, not timed here (avoids a flaky benchmark spec).
+      it "does not raise on stray closing tags with no matching opening" do
+        source = "</Card>\n" * 5000
+        expect { run(source) }.not_to raise_error
+      end
+
+      it "still raises when a real opening precedes the stray closes" do
+        source = "<Card>x</Card>\n#{'</Card>' * 100}"
+        expect { run(source) }.to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      # AC#2 regression — the loud error must NOT fire on any valid pattern.
+      describe "does NOT fire on valid patterns (AC#2 byte-identical)" do
+        it "self-closing tag, no props" do
+          expect { run("<Button />") }.not_to raise_error
+        end
+
+        it "self-closing tag with props" do
+          expect { run("<LikeButton postId={@post.id} />") }.not_to raise_error
+        end
+
+        it "bare non-self-closing opening tag with NO closing tag (`<Dialog open={true}>`)" do
+          expect { run("<Dialog open={true}>") }.not_to raise_error
+        end
+
+        it "nested-brace prop value" do
+          expect { run("<Select options={Category.all.map { |c| c.id }} />") }.not_to raise_error
+        end
+
+        it "multiple self-closing components" do
+          expect { run('<Button /> and <Badge label={"hello"} />') }.not_to raise_error
+        end
+
+        it "mixed HTML around a self-closing component" do
+          source = %(<div class="container">\n  <h1>Hi</h1>\n  <LikeButton postId={1} />\n</div>)
+          expect { run(source) }.not_to raise_error
+        end
+
+        it "emits byte-identical output for `<Dialog open={true}>`" do
+          expect(run("<Dialog open={true}>"))
+            .to eq(%(<%= __ruact_component__("Dialog", { "open" => true }) %>))
+        end
+      end
+
+      # AC#3 — Suspense children are the ONE legitimate paired PascalCase tag and
+      # must never trip the error (normalized to <ruact-suspense> in Step 1).
+      describe "Suspense children never trip the error (AC#3)" do
+        it "does not raise for `<Suspense><Spinner /></Suspense>`" do
+          expect { run(%(<Suspense fallback="loading"><Spinner /></Suspense>)) }.not_to raise_error
+        end
+
+        it "normalizes Suspense to <ruact-suspense> exactly as today" do
+          result = run(%(<Suspense fallback="loading"><Spinner /></Suspense>))
+          expect(result).to include(%(data-ruact-fallback="loading"))
+          expect(result).to include("</ruact-suspense>")
+        end
+      end
+    end
+
     # Story 13.5 (FR100) — preprocess-time component-contract validation, wired
     # through an injectable registry seam (a stub responding to +contract_for+).
     describe "component contract validation", :story_13_5 do