ruact 0.0.2 → 0.0.3

data/spec/ruact/server_upload_request_spec.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+# Story 9.1 — request-cycle + unit spec for the Story 8.5 upload guard
+# RE-ANCHORED on the `Ruact::Server` concern (its final, v2 home). Replaces
+# `server_functions/endpoint_controller_upload_spec.rb` (removed in the same
+# commit — AC5). Pins, against REAL host-controller routes:
+#
+#   - oversized multipart → 413 + structured `upload_limit` payload through
+#     the concern's salvaged chain (inventory A7, A14, B7, B9, B11)
+#   - guard fires BEFORE CSRF verification on correctly ordered hosts —
+#     413, not 403 (B6 / Pitfall #4)
+#   - the three carve-outs: nil limit (B2), content-type allowlist (B3),
+#     absent Content-Length (B4); off-by-one equal-passes (B5)
+#   - D1: the 413 renders structured for native form submits too (no
+#     function-call Accept header) — the documented UploadTooLargeError
+#     exception to the re-raise rule
+#   - D2: GET/HEAD requests skip the guard entirely (C5)
+#   - small uploads reach the action as ActionDispatch::Http::UploadedFile
+#     with metadata + mixed non-file fields intact (transplant sanity)
+#
+# Mounts on the shared Story-7.9 Rails app; deliberately independent of the
+# v1 `server_functions/dispatch_request_spec.rb` (demolished in Story 9.9).
+
+require "action_controller/railtie"
+require "action_view/railtie"
+
+require "spec_helper"
+require "rack/test"
+require "tempfile"
+
+require "ruact/server"
+
+require_relative "controller_request_spec" unless defined?(ControllerRequestSpecSupport)
+
+SERVER_UPLOAD_SPEC_PNG_PATH =
+  File.expand_path("../support/fixtures/pixel.png", __dir__).freeze
+SERVER_UPLOAD_SPEC_PNG_BYTES = File.binread(SERVER_UPLOAD_SPEC_PNG_PATH).freeze
+
+module ServerUploadSpecSupport
+  class UploadsServerController < ActionController::Base
+    include Ruact::Server
+
+    def create_upload
+      uploaded = params[:cover]
+      render json: {
+        "title" => params[:title].to_s,
+        "uploaded_class" => uploaded.class.name,
+        "original_filename" => uploaded.respond_to?(:original_filename) ? uploaded.original_filename : nil,
+        "byte_size" => uploaded.respond_to?(:read) ? uploaded.read.bytesize : nil
+      }
+    end
+  end
+
+  # CSRF-enforcing host for the Pitfall #4 ordering proof (B6) — forgery is
+  # flipped on per-example via the class-level `allow_forgery_protection`.
+  class ForgeryUploadsServerController < ActionController::Base
+    include Ruact::Server
+
+    protect_from_forgery with: :exception
+
+    def create_protected_upload
+      render json: { "ok" => true }
+    end
+  end
+end
+
+if defined?(ControllerRequestSpecSupport) &&
+   !ControllerRequestSpecSupport.instance_variable_get(:@__ruact_server_upload_routes_appended)
+  ControllerRequestSpecSupport.instance_variable_set(:@__ruact_server_upload_routes_appended, true)
+  ControllerRequestSpecSupport.app_class.routes.append do
+    post "/server_upload",           to: "server_upload_spec_support/uploads_server#create_upload"
+    post "/server_upload/protected", to: "server_upload_spec_support/forgery_uploads_server#create_protected_upload"
+  end
+end
+
+RSpec.describe "Story 9.1: Ruact::Server concern — salvaged upload guard", :story_9_1 do
+  include Rack::Test::Methods
+
+  let(:app_class) { ControllerRequestSpecSupport.app_class }
+  let(:app)       { app_class.instance }
+
+  let(:function_call_accept) { { "HTTP_ACCEPT" => "application/json" } }
+
+  before do
+    Rails.logger = Logger.new(IO::NULL)
+    ControllerRequestSpecSupport.boot!
+  end
+
+  def with_oversized_tempfile
+    large = Tempfile.new(["big", ".bin"])
+    large.binmode
+    large.write("x" * 4096) # 4 KB > the 1 KB caps below
+    large.rewind
+    yield large
+  ensure
+    large.close
+    large.unlink
+  end
+
+  def cap_max_upload_bytes(value)
+    # spec_helper's global before-hook resets @config; re-prime AFTER it so
+    # the tight cap sticks for the example body (same dance as the v1 spec).
+    Ruact.instance_variable_set(:@config, nil)
+    Ruact.instance_variable_set(:@configured_at_least_once, false)
+    Ruact.configure { |c| c.max_upload_bytes = value }
+  end
+
+  describe "transplant sanity — small multipart upload reaches the action" do
+    it "params[:cover] arrives as ActionDispatch::Http::UploadedFile with metadata; mixed fields intact" do
+      post "/server_upload",
+           {
+             "title" => "My Post",
+             "cover" => Rack::Test::UploadedFile.new(SERVER_UPLOAD_SPEC_PNG_PATH, "image/png")
+           },
+           function_call_accept
+      expect(last_response.status).to eq(200)
+      body = JSON.parse(last_response.body)
+      expect(body.fetch("uploaded_class")).to eq("ActionDispatch::Http::UploadedFile")
+      expect(body.fetch("original_filename")).to eq("pixel.png")
+      expect(body.fetch("byte_size")).to eq(SERVER_UPLOAD_SPEC_PNG_BYTES.bytesize)
+      expect(body.fetch("title")).to eq("My Post")
+    end
+  end
+
+  describe "oversized multipart → 413 + structured upload_limit payload (A7/A14/B7/B9/B11)" do
+    before { cap_max_upload_bytes(1024) }
+
+    it "function-call request: 413 with discriminator, real action_name, and the dev-only upload_limit block" do
+      with_oversized_tempfile do |large|
+        post "/server_upload",
+             {
+               "title" => "Too big",
+               "cover" => Rack::Test::UploadedFile.new(large.path, "application/octet-stream")
+             },
+             function_call_accept
+        expect(last_response.status).to eq(413)
+        body = JSON.parse(last_response.body)
+        expect(body).to include(
+          "_ruact_server_action_error" => true,
+          "error_class" => "Ruact::UploadTooLargeError",
+          # A14 — the controller's REAL action name, no registry-symbol
+          # fallback dance (the v1 path_parameters[:name] fallback is gone).
+          "action_name" => "create_upload"
+        )
+        expect(body.fetch("upload_limit")).to include("limit_bytes" => 1024)
+        # B7 — received_bytes is the WIRE Content-Length: file bytes PLUS
+        # multipart boundary + field overhead.
+        expect(body.fetch("upload_limit").fetch("received_bytes")).to be > 4096
+      end
+    end
+
+    it "D1 — a native form submit (no function-call Accept) ALSO gets the structured 413" do
+      # UploadTooLargeError is the documented exception to the re-raise rule:
+      # the guard only exists on requests that opted into the concern, and a
+      # meaningful 413 beats a re-raised 500 for every caller shape.
+      with_oversized_tempfile do |large|
+        post "/server_upload",
+             {
+               "title" => "Too big, browser shape",
+               "cover" => Rack::Test::UploadedFile.new(large.path, "application/octet-stream")
+             }
+        expect(last_response.status).to eq(413)
+        body = JSON.parse(last_response.body)
+        expect(body.fetch("_ruact_server_action_error")).to be(true)
+        expect(body.fetch("error_class")).to eq("Ruact::UploadTooLargeError")
+      end
+    end
+  end
+
+  describe "guard fires BEFORE CSRF verification (B6 / Pitfall #4)" do
+    around do |example|
+      previous = ServerUploadSpecSupport::ForgeryUploadsServerController.allow_forgery_protection
+      ServerUploadSpecSupport::ForgeryUploadsServerController.allow_forgery_protection = true
+      example.run
+    ensure
+      ServerUploadSpecSupport::ForgeryUploadsServerController.allow_forgery_protection = previous
+    end
+
+    before { cap_max_upload_bytes(1024) }
+
+    it "oversized request WITHOUT a CSRF token returns 413, not 403" do
+      with_oversized_tempfile do |large|
+        post "/server_upload/protected",
+             {
+               "title" => "Too big, no token",
+               "cover" => Rack::Test::UploadedFile.new(large.path, "application/octet-stream")
+             },
+             function_call_accept
+        expect(last_response.status).to eq(413)
+        expect(JSON.parse(last_response.body).fetch("error_class")).to eq("Ruact::UploadTooLargeError")
+      end
+    end
+  end
+
+  describe "carve-out — max_upload_bytes = nil disables the gem-side guard (B2)" do
+    before { cap_max_upload_bytes(nil) }
+
+    it "a body of any size flows through to the action" do
+      with_oversized_tempfile do |large|
+        post "/server_upload",
+             {
+               "title" => "no cap",
+               "cover" => Rack::Test::UploadedFile.new(large.path, "application/octet-stream")
+             },
+             function_call_accept
+        expect(last_response.status).to eq(200)
+        expect(JSON.parse(last_response.body).fetch("uploaded_class")).to eq("ActionDispatch::Http::UploadedFile")
+      end
+    end
+  end
+
+  describe "carve-out — application/json bypasses the guard (B3, request-cycle)" do
+    before { cap_max_upload_bytes(1024) }
+
+    it "a 4 KB JSON body passes the guard and reaches the action" do
+      payload = { "title" => "big json", "blob" => "x" * 4096 }
+      post "/server_upload", payload.to_json,
+           { "CONTENT_TYPE" => "application/json", "HTTP_ACCEPT" => "application/json" }
+      expect(last_response.status).to eq(200)
+      # No file in a JSON body — the action reports the params leaf class.
+      expect(JSON.parse(last_response.body).fetch("uploaded_class")).to eq("NilClass")
+    end
+  end
+
+  # Unit-level coverage of the short-circuit branches — directly against a
+  # host controller instance, mirroring the v1 unit block but with the
+  # concern's D2 verb gate in play (request.get? / request.head?).
+  describe "Unit — __ruact_enforce_upload_limit! short-circuits (B2–B5, C5/D2)" do
+    let(:controller) { ServerUploadSpecSupport::UploadsServerController.new }
+
+    def with_max_upload_bytes(value)
+      cap_max_upload_bytes(value)
+      yield
+    ensure
+      Ruact.instance_variable_set(:@config, nil)
+      Ruact.instance_variable_set(:@configured_at_least_once, false)
+    end
+
+    def stub_request(content_type:, content_length:, http_method: "POST")
+      request = instance_double(
+        ActionDispatch::Request,
+        content_length: content_length,
+        get?: http_method == "GET",
+        head?: http_method == "HEAD"
+      )
+      allow(request).to receive(:content_mime_type)
+        .and_return(content_type ? Mime::Type.lookup(content_type) : nil)
+      allow(controller).to receive(:request).and_return(request)
+    end
+
+    it "B4 — nil Content-Length (chunked transfer) bypasses the guard" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "multipart/form-data", content_length: nil)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "B2 — max_upload_bytes = nil bypasses the guard even with oversized Content-Length" do
+      with_max_upload_bytes(nil) do
+        stub_request(content_type: "multipart/form-data", content_length: 10 * 1024 * 1024)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "B3 — application/json content type bypasses the guard" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "application/json", content_length: 10 * 1024 * 1024)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "B3 — missing content type (nil) bypasses the guard" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: nil, content_length: 10_000)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "B3/B8 — application/x-www-form-urlencoded is subject to the guard" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "application/x-www-form-urlencoded", content_length: 2048)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }
+          .to raise_error(Ruact::UploadTooLargeError) do |error|
+            expect(error.received_bytes).to eq(2048)
+            expect(error.limit_bytes).to eq(1024)
+          end
+      end
+    end
+
+    it "B5 — Content-Length exactly equal to the limit passes the guard (off-by-one)" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "multipart/form-data", content_length: 1024)
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "C5/D2 — a GET request skips the guard even with an oversized multipart body" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "multipart/form-data", content_length: 10 * 1024 * 1024, http_method: "GET")
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+
+    it "C5/D2 — a HEAD request skips the guard" do
+      with_max_upload_bytes(1024) do
+        stub_request(content_type: "multipart/form-data", content_length: 10 * 1024 * 1024, http_method: "HEAD")
+        expect { controller.send(:__ruact_enforce_upload_limit!) }.not_to raise_error
+      end
+    end
+  end
+end

data/spec/ruact/view_helper_spec.rb

@@ -5,42 +5,48 @@ require "active_support/core_ext/string/output_safety"
 
 module Ruact
   RSpec.describe ViewHelper do
+    let(:render_context) { RenderContext.new }
     let(:helper_obj) do
       obj = Object.new
       obj.extend(described_class)
+      obj.instance_variable_set(:@ruact_render_context, render_context)
       obj
     end
 
-    before { ComponentRegistry.start }
-    after  { ComponentRegistry.reset }
-
-    describe "#__rsc_component__" do
-      it "registers the component in ComponentRegistry and returns an HTML comment" do
-        result = helper_obj.__rsc_component__("NavBar", { "currentUser" => 1 })
-        expect(result).to match(/<!-- __RSC_\d+__ -->/)
-        expect(ComponentRegistry.components.length).to eq(1)
-        expect(ComponentRegistry.components.first[:name]).to eq("NavBar")
-        expect(ComponentRegistry.components.first[:props]).to eq({ "currentUser" => 1 })
+    describe "#__ruact_component__" do
+      it "registers the component in the render context and returns an HTML comment" do
+        result = helper_obj.__ruact_component__("NavBar", { "currentUser" => 1 })
+        expect(result).to match(/<!-- __RUACT_\d+__ -->/)
+        expect(render_context.components.length).to eq(1)
+        expect(render_context.components.first[:name]).to eq("NavBar")
+        expect(render_context.components.first[:props]).to eq({ "currentUser" => 1 })
       end
 
       it "returns an html_safe string so ActionView does not escape the comment" do
-        result = helper_obj.__rsc_component__("Button", {})
+        result = helper_obj.__ruact_component__("Button", {})
         expect(result).to be_html_safe
       end
 
       it "uses incrementing token numbers for successive registrations" do
-        token0 = helper_obj.__rsc_component__("Foo", {})
-        token1 = helper_obj.__rsc_component__("Bar", {})
-        expect(token0).to include("__RSC_0__")
-        expect(token1).to include("__RSC_1__")
+        token0 = helper_obj.__ruact_component__("Foo", {})
+        token1 = helper_obj.__ruact_component__("Bar", {})
+        expect(token0).to include("__RUACT_0__")
+        expect(token1).to include("__RUACT_1__")
       end
 
       it "passes props through to the registry entry" do
-        helper_obj.__rsc_component__("LikeButton", { "postId" => 42, "label" => "Like" })
-        entry = ComponentRegistry.components.first
+        helper_obj.__ruact_component__("LikeButton", { "postId" => 42, "label" => "Like" })
+        entry = render_context.components.first
         expect(entry[:props]["postId"]).to eq(42)
         expect(entry[:props]["label"]).to eq("Like")
       end
+
+      it "raises a clear error when called outside a ruact_render flow" do
+        bare = Object.new
+        bare.extend(described_class)
+        expect { bare.__ruact_component__("NavBar", {}) }
+          .to raise_error(Ruact::Error, /__ruact_component__ called outside a ruact_render flow/)
+      end
     end
   end
 end

data/spec/spec_helper.rb

@@ -1,9 +1,36 @@
 # frozen_string_literal: true
 
+require "simplecov"
+require "simplecov-lcov"
+
+SimpleCov::Formatter::LcovFormatter.config do |c|
+  c.report_with_single_file = true
+  c.single_report_path = "coverage/lcov.info"
+end
+
+SimpleCov.start do
+  enable_coverage :branch
+  primary_coverage :line
+  formatter SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::LcovFormatter
+    ]
+  )
+  add_filter %r{^/spec/}
+  add_filter %r{^/bin/}
+  add_filter %r{lib/generators/.+/templates/}
+  add_filter "lib/ruact/version.rb"
+end
+
 require "logger"
 require "ruact"
 
-Dir[File.join(__dir__, "support", "**", "*.rb")].each { |f| require f }
+Dir[File.join(__dir__, "support", "**", "*.rb")].each do |f|
+  next if f.end_with?("_spec.rb") # spec files are loaded by the RSpec runner; avoid double registration
+
+  require f
+end
 
 RSpec.configure do |config|
   config.order = :random
@@ -13,4 +40,28 @@ RSpec.configure do |config|
   config.mock_with :rspec do |mocks|
     mocks.verify_partial_doubles = true
   end
+
+  # Story 7.3: Ruact.config is a frozen singleton with a boot-state flag for the
+  # re-configuration warning. Reset both before every example so the boot flag
+  # cannot leak between specs — otherwise the AC3 warning may fire into a
+  # Rails.logger that has become a per-example RSpec double from an earlier
+  # spec, producing "originally created in one example but has leaked" failures
+  # under random order.
+  config.before do
+    Ruact.instance_variable_set(:@config, nil)
+    Ruact.instance_variable_set(:@configured_at_least_once, false)
+    # Story 8.0a: both server-function registries are lazy-initialized module
+    # singletons. Wipe them between examples so register/clear specs in one file
+    # cannot bleed entries into another under random order.
+    Ruact.instance_variable_set(:@action_registry, nil)
+    Ruact.instance_variable_set(:@query_registry, nil)
+    # Story 9.3: specs that set `Rails.logger = instance_double(Logger)` (e.g.
+    # railtie_spec, configuration_spec) leave a per-example double on the global
+    # after they finish; rspec then refuses to call it from the NEXT example.
+    # That was harmless until the codegen/rake paths began reading `Rails.logger`
+    # (the `[ruact] codegen: exposing …` line). Reset it to a real, silent logger
+    # before every example so no leaked double survives — examples that need a
+    # specific logger set their own in their own `before` (which runs after this).
+    Rails.logger = Logger.new(IO::NULL) if defined?(Rails) && Rails.respond_to?(:logger=)
+  end
 end

data/spec/support/flight_wire_parser.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "strscan"
+require "json"
+
+module Ruact
+  # Test-support utilities. Code under `Ruact::Spec` is consumed only by the
+  # gem's own RSpec suite; it is not part of the public API and may change
+  # shape across stories without a deprecation cycle.
+  module Spec
+    # Raised when {FlightWireParser.parse} encounters input it cannot decode.
+    # The message names the byte offset of the unparseable row so the spec
+    # author 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 RSpec matchers
+    # (`match_flight_structure` / `include_flight_row`) 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::Spec::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::Spec::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/spec/support/flight_wire_parser_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "flight_wire_parser"
+
+module Ruact
+  module Spec
+    RSpec.describe FlightWireParser do
+      describe ".parse" do
+        it "parses a single model row" do
+          rows = described_class.parse(%(0:{"className":"box"}\n))
+
+          expect(rows).to eq([
+                               {
+                                 id: 0,
+                                 class: :model,
+                                 payload: { "className" => "box" },
+                                 raw: %(0:{"className":"box"}\n)
+                               }
+                             ])
+        end
+
+        it "parses a single import row and decodes the hex id" do
+          rows = described_class.parse(%(a:I["/L.jsx","L",["/L.jsx"]]\n))
+
+          expect(rows.length).to eq(1)
+          expect(rows.first).to include(
+            id: 10,
+            class: :import,
+            payload: ["/L.jsx", "L", ["/L.jsx"]]
+          )
+        end
+
+        it "parses a single error row" do
+          rows = described_class.parse(%(2:E{"message":"boom"}\n))
+
+          expect(rows.first).to include(
+            id: 2,
+            class: :error,
+            payload: { "message" => "boom" }
+          )
+        end
+
+        it "parses a hint row with no id" do
+          rows = described_class.parse(%(:HL"/preload.js"\n))
+
+          expect(rows.first).to include(
+            id: nil,
+            class: :hint,
+            payload: ["L", "/preload.js"]
+          )
+        end
+
+        it "parses a T row of exactly LARGE_TEXT_THRESHOLD bytes followed by a model row that references it" do
+          large_text = "a" * 1024
+          wire = "1:T#{1024.to_s(16)},#{large_text}0:\"$T1\"\n"
+
+          rows = described_class.parse(wire)
+
+          expect(rows.length).to eq(2)
+          expect(rows[0]).to include(id: 1, class: :text, payload: large_text)
+          expect(rows[1]).to include(id: 0, class: :model, payload: "$T1")
+        end
+
+        it "parses a mixed-row sequence preserving wire order" do
+          wire = %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{}]\n)
+
+          rows = described_class.parse(wire)
+
+          expect(rows.map { |r| [r[:id], r[:class]] }).to eq([[1, :import], [0, :model]])
+        end
+
+        it "parses empty input as an empty array" do
+          expect(described_class.parse("")).to eq([])
+        end
+
+        it "raises FlightWireParseError naming the byte offset on malformed JSON" do
+          wire = %(0:{not-json}\n)
+
+          expect { described_class.parse(wire) }
+            .to raise_error(FlightWireParseError, /cannot parse row at offset \d+/)
+        end
+
+        it "raises FlightWireParseError when a T row is truncated" do
+          wire = "0:T#{10.to_s(16)},abc" # claims 16 bytes but provides 3
+
+          expect { described_class.parse(wire) }
+            .to raise_error(FlightWireParseError, /cannot parse row at offset 0: T row truncated/)
+        end
+      end
+    end
+  end
+end