ruact 0.0.7 → 0.0.9

data/lib/ruact/testing/flight_structure_diff.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Testing
+    # Pure structural diff + predicate-matching engine over parsed Flight rows
+    # (see {FlightWireParser}). No RSpec dependency — the RSpec matcher DSL that
+    # consumes it (the public `have_ruact_component` and the internal
+    # `match_flight_structure`/`include_flight_row`) lives elsewhere. Promoted
+    # from `spec/support` in Story 15.4 so the public helper and the internal
+    # matchers share ONE implementation (wrap, not fork).
+    # rubocop:disable Metrics/ClassLength -- single cohesive helper for matcher diffing/formatting; splitting would scatter related logic across files.
+    class FlightStructureDiff
+      # Keys the parser produces on every row. Predicates and expected rows
+      # may only reference these keys; unknown keys raise upfront so typos
+      # like `payloed:` don't silently match every row via `nil == nil`.
+      KNOWN_ROW_KEYS = %i[id class payload raw].freeze
+
+      # Keys that must be present in every expected-row hash passed to
+      # `match_flight_structure`. Excludes `:raw` because expected rows are
+      # authored as semantic descriptions, not byte-level snapshots.
+      REQUIRED_EXPECTED_KEYS = %i[id class payload].freeze
+
+      # Compute the set of differences between actual parsed rows and the
+      # expected structure. Import rows are matched as a multiset (their
+      # relative order among each other is not significant per AC1);
+      # everything else compares positionally.
+      def self.compute(actual_rows, expected_rows)
+        validate_expected_rows!(expected_rows)
+        return diffs_for_length_mismatch(actual_rows, expected_rows) if actual_rows.length != expected_rows.length
+
+        diffs = []
+        pending_actual_imports = []
+        pending_expected_imports = []
+
+        actual_rows.zip(expected_rows).each_with_index do |(actual, expected), i|
+          if actual[:class] == :import && expected[:class] == :import
+            pending_actual_imports << [i, actual]
+            pending_expected_imports << [i, expected]
+            next
+          end
+
+          next if rows_equal?(actual, expected)
+
+          diffs << build_field_diff(i, actual, expected)
+        end
+
+        diffs.concat(diff_imports_unordered(pending_actual_imports, pending_expected_imports))
+        diffs.sort_by { |d| d[:idx] }
+      end
+
+      # Imports are an unordered multiset within their class (AC1). Sort both
+      # sides by `:id` (always unique per render) and any leftover diffs come
+      # from semantic mismatch in the same-position-after-sort pair.
+      def self.diff_imports_unordered(actual_pairs, expected_pairs)
+        return [] if actual_pairs.empty? && expected_pairs.empty?
+
+        sort_key = ->(pair) { [pair[1][:id].to_i, pair[1][:payload].to_s] }
+        sorted_actual = actual_pairs.sort_by(&sort_key)
+        sorted_expected = expected_pairs.sort_by(&sort_key)
+
+        sorted_actual.zip(sorted_expected).filter_map do |(act_idx, act_row), (_exp_idx, exp_row)|
+          next if rows_equal?(act_row, exp_row)
+
+          build_field_diff(act_idx, act_row, exp_row)
+        end
+      end
+
+      def self.diffs_for_length_mismatch(actual_rows, expected_rows)
+        diffs = []
+        [actual_rows.length, expected_rows.length].max.times do |i|
+          actual = actual_rows[i]
+          expected = expected_rows[i]
+          if actual.nil?
+            diffs << { kind: :missing, idx: i, expected_row: expected }
+          elsif expected.nil?
+            diffs << { kind: :extra, idx: i, actual_row: actual }
+          elsif !rows_equal?(actual, expected)
+            diffs << build_field_diff(i, actual, expected)
+          end
+        end
+        diffs
+      end
+
+      def self.rows_equal?(actual, expected)
+        REQUIRED_EXPECTED_KEYS.all? { |k| actual[k] == expected[k] }
+      end
+
+      def self.build_field_diff(idx, actual, expected)
+        field_diff = nil
+        REQUIRED_EXPECTED_KEYS.each do |key|
+          next if actual[key] == expected[key]
+
+          path, sub_expected, sub_actual = first_difference(expected[key], actual[key], ".#{key}")
+          field_diff = { path: path, expected: sub_expected, got: sub_actual }
+          break
+        end
+
+        {
+          kind: :differs,
+          idx: idx,
+          row_class: actual[:class],
+          path: field_diff[:path],
+          expected: field_diff[:expected],
+          got: field_diff[:got],
+          expected_row: expected,
+          got_row: actual
+        }
+      end
+
+      # Walks parallel structures (Hash/Array/scalar) and returns the path,
+      # expected leaf, and actual leaf at the first differing position.
+      def self.first_difference(expected, actual, path)
+        return [path, expected, actual] if expected.class != actual.class
+        return [path, expected, actual] unless expected.is_a?(Array) || expected.is_a?(Hash)
+
+        return diff_in_array(expected, actual, path) if expected.is_a?(Array)
+
+        diff_in_hash(expected, actual, path)
+      end
+
+      def self.diff_in_array(expected, actual, path)
+        [expected.length, actual.length].max.times do |i|
+          return ["#{path}[#{i}]", expected[i], actual[i]] if i >= expected.length || i >= actual.length
+          next if expected[i] == actual[i]
+
+          return first_difference(expected[i], actual[i], "#{path}[#{i}]")
+        end
+        [path, expected, actual]
+      end
+
+      def self.diff_in_hash(expected, actual, path)
+        (expected.keys | actual.keys).each do |key|
+          return ["#{path}[#{key.inspect}]", expected[key], actual[key]] if !expected.key?(key) || !actual.key?(key)
+          next if expected[key] == actual[key]
+
+          return first_difference(expected[key], actual[key], "#{path}[#{key.inspect}]")
+        end
+        [path, expected, actual]
+      end
+
+      # Validates each expected row carries the required `:id`, `:class`,
+      # `:payload` keys. Without this, an expected row of `{ id: 0, class:
+      # :model }` would silently pass against any actual row whose payload
+      # was nil — because the `==` check reads `expected[:payload]` as nil.
+      def self.validate_expected_rows!(expected_rows)
+        expected_rows.each_with_index do |row, i|
+          unless row.is_a?(Hash)
+            raise ArgumentError,
+                  "match_flight_structure: expected row #{i} must be a Hash, got #{row.class}: #{row.inspect}"
+          end
+
+          missing = REQUIRED_EXPECTED_KEYS.reject { |k| row.key?(k) }
+          next if missing.empty?
+
+          raise ArgumentError,
+                "match_flight_structure: expected row #{i} is missing required keys: #{missing.inspect}. " \
+                "Each expected row must include :id, :class, and :payload."
+        end
+      end
+
+      # Validates a predicate hash for `include_flight_row`. Unknown keys
+      # (typos like `payloed:` or `clas:`) raise immediately so they don't
+      # silently match any row via `row[:payloed]` returning nil.
+      def self.validate_predicate!(predicate)
+        unless predicate.is_a?(Hash)
+          raise ArgumentError,
+                "include_flight_row: predicate must be a Hash, got #{predicate.class}: #{predicate.inspect}"
+        end
+        raise ArgumentError, "include_flight_row: predicate cannot be empty" if predicate.empty?
+
+        unknown = predicate.keys - KNOWN_ROW_KEYS
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "include_flight_row: predicate has unknown keys: #{unknown.inspect}. " \
+              "Allowed keys: #{KNOWN_ROW_KEYS.inspect}."
+      end
+
+      def self.format_single(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          format_field_diff(diff)
+        end
+      end
+
+      def self.format_field_diff(diff)
+        <<~MSG.strip
+          Expected Flight output to match structure.
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+            expected: #{diff[:expected].inspect}
+            got:      #{diff[:got].inspect}
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) full diff:
+            expected: #{diff[:expected_row][:payload].inspect}
+            got:      #{diff[:got_row][:payload].inspect}
+        MSG
+      end
+
+      # Builds the multi-row failure message: header naming the diff count,
+      # AC3-specified wording for missing / extra / differing rows, and a
+      # `Row N (<class>): ✓` summary line for every matching row so the
+      # reader can see what passed.
+      def self.format_multi(diffs, actual_rows, expected_rows)
+        header = "Expected Flight output to match structure. #{diffs.length} rows differ:"
+        total = [actual_rows.length, expected_rows.length].max
+        diff_by_idx = diffs.to_h { |d| [d[:idx], d] }
+
+        body = (0...total).map do |i|
+          diff = diff_by_idx[i]
+          if diff
+            format_entry(diff)
+          else
+            row_class = (actual_rows[i] || expected_rows[i])[:class]
+            "Row #{i} (#{row_class}): ✓"
+          end
+        end
+
+        ([header, ""] + body).join("\n")
+      end
+
+      def self.format_entry(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          <<~ENTRY.strip
+            Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+              expected: #{diff[:expected].inspect}
+              got:      #{diff[:got].inspect}
+          ENTRY
+        end
+      end
+
+      # Subset / case-equality match used by `include_flight_row`. Plain
+      # values use `==`; richer matchers (`hash_including`, `array_including`,
+      # `kind_of`, regexes) use `===` which delegates to their custom logic.
+      # Predicate keys are validated upfront by `validate_predicate!`, so
+      # this method can assume every key is one of the known row keys.
+      def self.row_matches?(row, predicate)
+        predicate.all? do |key, expected_value|
+          actual_value = row[key]
+          case expected_value
+          when Symbol, Numeric, NilClass, TrueClass, FalseClass
+            expected_value == actual_value
+          else
+            # rubocop:disable Style/CaseEquality -- intentional: lets RSpec mock argument matchers
+            # (hash_including, array_including, kind_of, etc.) drive predicate semantics via #===.
+            expected_value === actual_value
+            # rubocop:enable Style/CaseEquality
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

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.9"
 end

data/lib/ruact/view_helper.rb

@@ -44,12 +44,21 @@ module Ruact
     # (no drift). Available in every view via the railtie's
     # `ActionView::Base.include(Ruact::ViewHelper)`.
     #
+    # Called from a LAYOUT the argument is normally omitted: the payload for the
+    # render in flight is picked up from `@ruact_flight_payload`, which
+    # `Ruact::Controller#render_ruact_document` sets on the controller and Rails
+    # copies to the view (the name does not match the `/\A@_/` protected-ivar
+    # filter). On a plain Rails page — no ruact render in flight — that ivar is
+    # absent and the helper emits only the entry tags, exactly as before.
+    #
     # @param flight_payload [String, nil] the per-render Flight wire payload to
-    #   inline as `__FLIGHT_DATA`; omit (or pass nil) to emit only the entry tags.
+    #   inline as `__FLIGHT_DATA`. Omit inside a layout to use the render in
+    #   flight; an explicit argument always wins.
     # @return [ActiveSupport::SafeBuffer] the asset markup, html_safe
     # @example In a layout
     #   <%= ruact_js_assets %>
     def ruact_js_assets(flight_payload = nil)
+      flight_payload ||= @ruact_flight_payload
       parts = []
       parts << ruact_flight_data_script(flight_payload) unless flight_payload.nil?
       parts << ruact_vite_tags

data/lib/ruact.rb

@@ -7,6 +7,7 @@ require_relative "ruact/serializable"
 require_relative "ruact/signed_references"
 require_relative "ruact/flight"
 require_relative "ruact/string_distance"
+require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"

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/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/rootless_layout_demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/controller_request_spec_support/unwired_layout_demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/fixtures/story_7_9_views/layouts/bare_host.html.erb

@@ -0,0 +1,16 @@
+<%# An UNMIGRATED host layout: it has the React root but never calls
+    `ruact_js_assets`, so rendering the page through it would produce a
+    document with no bootstrap entry and no Flight payload — a blank page.
+    ruact must detect that and fall back to its built-in shell instead. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="/host-app.css" />
+    <title>Host App Title</title>
+  </head>
+  <body>
+    <%= yield %>
+    <%# ruact: root %>
+    <div id="root"></div>
+  </body>
+</html>

data/spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb

@@ -0,0 +1,24 @@
+<%# An UNMIGRATED layout that cannot survive being rendered on a ruact page.
+    It reads an ivar that only a plain Rails action would have set — exactly the
+    shape of a real pre-migration app, whose layout has never once run on a
+    ruact-rendered page. If ruact renders this speculatively just to discover it
+    lacks `ruact_js_assets`, the app 500s on a page that used to work.
+
+    NOTE: this comment MENTIONS the helper name on purpose — a readiness check
+    that greps for the bare string counts this layout as wired and renders it. %>
+<%# <%= ruact_js_assets %> %>
+<%# ...and the line above is a genuinely COMMENTED-OUT call, which is the
+    sharper version of the same trap: ERB comments do not nest, so it emits
+    nothing, but a check that only looks for `<%=` sees a call. Both shapes must
+    read as UNMIGRATED, or this layout gets rendered and 500s below. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= @page_title.upcase %></title>
+  </head>
+  <body>
+    <%= yield %>
+    <%# ruact: root %>
+    <div id="root"></div>
+  </body>
+</html>