ruact 0.0.1

data/lib/ruact.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "ruact/version"
+require_relative "ruact/errors"
+require_relative "ruact/configuration"
+require_relative "ruact/serializable"
+require_relative "ruact/flight"
+require_relative "ruact/erb_preprocessor"
+require_relative "ruact/component_registry"
+require_relative "ruact/html_converter"
+require_relative "ruact/client_manifest"
+require_relative "ruact/render_pipeline"
+require_relative "ruact/view_helper"
+require_relative "ruact/erb_preprocessor_hook"
+# Railtie loads ruact/controller when inside a Rails app
+require_relative "ruact/railtie" if defined?(Rails)
+
+module Ruact
+  class << self
+    attr_accessor :manifest, :streaming_mode
+
+    # Returns the absolute path to the Vite plugin bundled inside this gem.
+    # Use this in vite.config.js: import ruact from '<%= Ruact.vite_plugin_path %>'
+    # Re-run `rails generate ruact:install` after gem upgrades to refresh the path.
+    #
+    # @return [String] absolute path to vendor/javascript/vite-plugin-ruact/index.js
+    def vite_plugin_path
+      File.expand_path("../vendor/javascript/vite-plugin-ruact/index.js", __dir__)
+    end
+
+    # Yields the configuration object for block-style setup.
+    #
+    # @example
+    #   Ruact.configure do |config|
+    #     config.strict_serialization = true
+    #   end
+    def configure
+      yield config
+    end
+
+    # Returns the singleton configuration instance.
+    #
+    # @return [Ruact::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/lib/rubocop/cop/ruact/no_extend_self.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Ruact
+      # Prohibits `extend self` and `module_function` in all files.
+      # Modules must use explicit class methods or classes with initialize (NFR13).
+      #
+      # @example
+      #   # bad
+      #   module MyModule
+      #     extend self
+      #     def do_thing; end
+      #   end
+      #
+      #   # good
+      #   module MyModule
+      #     def self.do_thing; end
+      #   end
+      class NoExtendSelf < Base
+        MSG = "extend self is prohibited (NFR13). Use explicit class methods or a class with initialize."
+
+        def on_send(node)
+          return unless extend_self?(node) || module_function_bare?(node)
+
+          add_offense(node)
+        end
+
+        private
+
+        def extend_self?(node)
+          node.method_name == :extend &&
+            node.receiver.nil? &&
+            node.arguments.one? &&
+            node.first_argument.self_type?
+        end
+
+        def module_function_bare?(node)
+          node.method_name == :module_function &&
+            node.receiver.nil? &&
+            node.arguments.empty?
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/ruact/no_io_in_flight.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Ruact
+      # Prohibits I/O calls in lib/ruact/flight/** modules.
+      # Flight modules must be pure value transformations with no side effects (NFR10).
+      #
+      # @example
+      #   # bad (in lib/ruact/flight/serializer.rb)
+      #   File.read("manifest.json")
+      #   Rails.logger.debug("serializing")
+      #   puts "debug"
+      #
+      #   # good
+      #   def serialize(value, request:)
+      #     case value
+      #     when NilClass then "null"
+      #     end
+      #   end
+      class NoIoInFlight < Base
+        MSG = "I/O is not allowed in flight/** modules (NFR10). Move I/O to the imperative shell."
+
+        IO_METHODS = %i[
+          read write open puts print p pp warn
+        ].freeze
+
+        IO_RECEIVERS = %w[
+          File IO Rails.logger Net Socket TCPSocket UDPSocket
+        ].freeze
+
+        # @!method io_send?(node)
+        def_node_matcher :io_send?, <<~PATTERN
+          (send {nil? (const ...) (send ...)} {#{IO_METHODS.map { |m| ":#{m}" }.join(' ')}} ...)
+        PATTERN
+
+        def on_send(node)
+          return unless flight_file?
+
+          receiver = node.receiver
+          method   = node.method_name
+
+          io_via_nil_receiver = IO_METHODS.include?(method) && receiver.nil?
+          io_via_logger       = IO_METHODS.include?(method) && !receiver.nil? && rails_logger_receiver?(receiver)
+          io_via_class        = receiver && io_class_receiver?(receiver)
+
+          add_offense(node) if io_via_nil_receiver || io_via_logger || io_via_class
+        end
+
+        private
+
+        def flight_file?
+          processed_source.path.to_s.include?("lib/ruact/flight/")
+        end
+
+        def rails_logger_receiver?(node)
+          return false unless node.send_type? || node.const_type?
+
+          src = node.source
+          src == "Rails.logger" || src.start_with?("Rails.logger.")
+        end
+
+        def io_class_receiver?(node)
+          return false unless node.const_type? || node.send_type?
+
+          src = node.source
+          %w[File IO Net Socket TCPSocket UDPSocket].any? { |cls| src == cls || src.start_with?("#{cls}::") }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/ruact/no_shared_state.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Ruact
+      # Prohibits shared mutable state: class variables, Thread.current, and
+      # module-level instance variables. All data must flow via explicit method
+      # arguments (NFR8, NFR13).
+      #
+      # @example
+      #   # bad
+      #   @@manifest = nil
+      #   Thread.current[:rsc_request] = req
+      #
+      #   # good
+      #   def serialize(value, request:)
+      #     request.allocate_id
+      #   end
+      class NoSharedState < Base
+        MSG = "Shared state is prohibited (NFR8/NFR13). Pass data as explicit method arguments."
+
+        def on_cvasgn(node)
+          add_offense(node)
+        end
+
+        def on_send(node)
+          return unless thread_current_write?(node)
+
+          add_offense(node)
+        end
+
+        private
+
+        def thread_current_write?(node)
+          # Thread.current[:key] = value  → send(send(const nil :Thread) :current) :[]= ...
+          # Thread.current[:key]          → send(send(const nil :Thread) :current) :[] ...
+          return false unless %i[[]= []].include?(node.method_name)
+
+          receiver = node.receiver
+          return false unless receiver&.send_type?
+          return false unless receiver.method_name == :current
+
+          recv2 = receiver.receiver
+          recv2&.const_type? && recv2.short_name == :Thread
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/ruact.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "ruact/no_io_in_flight"
+require_relative "ruact/no_shared_state"
+require_relative "ruact/no_extend_self"

data/lib/tasks/benchmark.rake

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "json"
+
+namespace :benchmark do
+  desc "Run speed benchmark with benchmark-ips (development reporting)"
+  task :speed do
+    require "benchmark/ips"
+    require "rails_rsc"
+
+    manifest = RailsRsc::ClientManifest.from_hash(
+      (1..20).to_h do |i|
+        ["Component#{i}", { "id" => "/assets/Component#{i}.js",
+                            "name" => "Component#{i}",
+                            "chunks" => ["/assets/Component#{i}.js"] }]
+      end
+    )
+    pipeline = RailsRsc::RenderPipeline.new(manifest)
+    erb_typical = "<div>\n#{(1..20).map { |i| "<Component#{i} index={#{i}} />" }.join("\n")}\n</div>"
+
+    ctx = Object.new
+    binding_ctx = ctx.instance_eval { binding }
+
+    Benchmark.ips do |x|
+      x.config(time: 5, warmup: 2)
+      x.report("render 20 components") { pipeline.call(erb_typical, binding_ctx) }
+      x.compare!
+    end
+  end
+
+  desc "Run memory allocation benchmark; exits 1 if allocations exceed baseline × 1.20"
+  task :memory do
+    require "memory_profiler"
+    require "rails_rsc"
+
+    manifest = RailsRsc::ClientManifest.from_hash(
+      (1..20).to_h do |i|
+        ["Component#{i}", { "id" => "/assets/Component#{i}.js",
+                            "name" => "Component#{i}",
+                            "chunks" => ["/assets/Component#{i}.js"] }]
+      end
+    )
+    pipeline = RailsRsc::RenderPipeline.new(manifest)
+    erb_typical = "<div>\n#{(1..20).map { |i| "<Component#{i} index={#{i}} />" }.join("\n")}\n</div>"
+    ctx = Object.new
+    binding_ctx = ctx.instance_eval { binding }
+
+    baseline_path = File.expand_path("../../spec/benchmarks/baseline.json", __dir__)
+    report = MemoryProfiler.report { pipeline.call(erb_typical, binding_ctx) }
+    current = report.total_allocated
+
+    if File.exist?(baseline_path)
+      baseline = JSON.parse(File.read(baseline_path))
+      limit = (baseline["typical_allocations"] * 1.20).ceil
+      puts "Memory allocations: #{current} (baseline: #{baseline['typical_allocations']}, limit: #{limit})"
+
+      if current > limit
+        warn "[rails_rsc] FAIL: allocations #{current} exceed baseline limit #{limit}"
+        exit 1
+      else
+        puts "[rails_rsc] PASS: allocations within 120% of baseline"
+      end
+    else
+      baseline_data = { "typical_allocations" => current, "heavy_allocations" => nil }
+      File.write(baseline_path, JSON.generate(baseline_data))
+      puts "[rails_rsc] Baseline established: #{current} allocations. Re-run to compare."
+    end
+  end
+end

data/lib/tasks/rsc.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :rsc do
+  desc "Check rails_rsc installation and configuration (FR27)"
+  task doctor: :environment do
+    require "rails_rsc/doctor"
+    exit 1 unless RailsRsc::Doctor.run
+  end
+end

data/sig/ruact.rbs

@@ -0,0 +1,4 @@
+module Ruact
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/spec/benchmarks/baseline.json

@@ -0,0 +1 @@
+{"typical_allocations":1623,"heavy_allocations":7764}

data/spec/benchmarks/render_pipeline_benchmark_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "rspec-benchmark"
+require "memory_profiler"
+require "json"
+
+BENCHMARK_BASELINE_FILE = File.expand_path("baseline.json", __dir__)
+
+RSpec.describe "RenderPipeline benchmark" do
+  include RSpec::Benchmark::Matchers
+
+  let(:baseline_file) { BENCHMARK_BASELINE_FILE }
+
+  let(:manifest) do
+    entries = (1..20).to_h do |i|
+      ["Component#{i}", {
+        "id" => "/assets/Component#{i}.js",
+        "name" => "Component#{i}",
+        "chunks" => ["/assets/Component#{i}.js"]
+      }]
+    end
+    Ruact::ClientManifest.from_hash(entries)
+  end
+
+  let(:pipeline) { Ruact::RenderPipeline.new(manifest) }
+
+  def make_erb(count)
+    components = (1..count).map { |i| "<Component#{i} index={#{i}} />" }.join("\n")
+    "<div>\n#{components}\n</div>"
+  end
+
+  def render_erb(erb_source, active_pipeline = pipeline)
+    ctx = Object.new
+    active_pipeline.call(erb_source, ctx.instance_eval { binding })
+  end
+
+  describe "typical view (20 components)" do
+    let(:erb_typical) { make_erb(20) }
+
+    it "allocates fewer than the baseline × 1.20 objects" do
+      report = MemoryProfiler.report { render_erb(erb_typical) }
+      allocations = report.total_allocated
+
+      if File.exist?(baseline_file)
+        baseline = JSON.parse(File.read(baseline_file))
+        limit = (baseline["typical_allocations"] * 1.20).ceil
+        expect(allocations).to be <= limit,
+                               "Typical view allocations #{allocations} exceed baseline limit #{limit} " \
+                               "(baseline: #{baseline['typical_allocations']})"
+      else
+        # First run — establish baseline
+        File.write(baseline_file, JSON.generate("typical_allocations" => allocations,
+                                                "heavy_allocations" => nil))
+      end
+    end
+  end
+
+  describe "heavy view (100 components)" do
+    let(:manifest_heavy) do
+      entries = (1..100).to_h do |i|
+        ["Component#{i}", {
+          "id" => "/assets/Component#{i}.js",
+          "name" => "Component#{i}",
+          "chunks" => ["/assets/Component#{i}.js"]
+        }]
+      end
+      Ruact::ClientManifest.from_hash(entries)
+    end
+
+    let(:pipeline_heavy) { Ruact::RenderPipeline.new(manifest_heavy) }
+    let(:erb_heavy)      { make_erb(100) }
+
+    it "allocates fewer than the baseline × 1.20 objects" do
+      report = MemoryProfiler.report { render_erb(erb_heavy, pipeline_heavy) }
+      allocations = report.total_allocated
+
+      if File.exist?(baseline_file)
+        data = JSON.parse(File.read(baseline_file))
+        if data["heavy_allocations"]
+          limit = (data["heavy_allocations"] * 1.20).ceil
+          expect(allocations).to be <= limit,
+                                 "Heavy view allocations #{allocations} exceed baseline limit #{limit} " \
+                                 "(baseline: #{data['heavy_allocations']})"
+        else
+          data["heavy_allocations"] = allocations
+          File.write(baseline_file, JSON.generate(data))
+        end
+      end
+    end
+  end
+end

data/spec/fixtures/flight/README.md

@@ -0,0 +1,88 @@
+# Flight Wire Format Fixtures
+
+This directory contains fixture files used to test the Flight wire format serializer. Each `.txt` file contains the exact byte output that `Ruact::Flight::Renderer.render` is expected to produce for a given Ruby input.
+
+---
+
+## Wire Format Reference
+
+The React Flight wire protocol encodes a component tree as a series of newline-terminated rows:
+
+```
+<hex-id>:<payload>\n         # model row — a JSON value at position <hex-id>
+<hex-id>:I<json-array>\n     # import row — registers a client module: [moduleId, exportName, chunks]
+<hex-id>:E<json-error>\n     # error row — encodes a serialized error object
+```
+
+- **Row `0`** is always the root — the main React element tree returned to the client.
+- **Import rows (`I` rows)** always appear *before* the model rows that reference them.
+- Hex IDs start at `0` for the root and increment (`1`, `2`, `a`, `b`, …) for each additional row.
+
+### Worked Example — `client_reference.txt`
+
+Ruby input:
+```ruby
+manifest = Ruact::ClientManifest.new({"LikeButton" => {moduleId: "/LikeButton.jsx", chunks: ["/LikeButton.jsx"]}})
+ref = manifest.reference_for("LikeButton")
+Ruact::Flight::Renderer.render(ref, manifest)
+```
+
+Expected output (`client_reference.txt`):
+```
+1:I["/LikeButton.jsx","LikeButton",["/LikeButton.jsx"]]
+0:["$","$L1",null,{}]
+```
+
+- Row `1` is the import row — it tells React where to find `LikeButton`.
+- Row `0` is the root element — `["$","$L1",null,{}]` is a React element whose type is `$L1` (a reference to import row 1), with `null` key and empty props `{}`.
+
+---
+
+## How `match_flight_fixture` Works
+
+The custom RSpec matcher is defined in `spec/support/matchers/flight_fixture_matcher.rb`:
+
+```ruby
+expect(output).to match_flight_fixture("nil")
+```
+
+This reads `spec/fixtures/flight/nil.txt` and performs an **exact string comparison** against `output`. There is no normalisation — whitespace, newlines, and ordering must match exactly.
+
+### Failure output
+
+When a fixture does not match, the failure message shows both the expected (fixture file content) and actual (serializer output) as inspected strings, making it easy to spot differences in whitespace or character escaping.
+
+---
+
+## Fixture File Inventory
+
+| File | What it tests |
+|------|---------------|
+| `nil.txt` | Ruby `nil` serializes to the JSON `null` literal in row 0 |
+| `boolean_true.txt` | Ruby `true` serializes to the JSON `true` literal |
+| `boolean_false.txt` | Ruby `false` serializes to the JSON `false` literal |
+| `number_integer.txt` | Ruby integer (e.g. `42`) serializes to a bare JSON number |
+| `number_float.txt` | Ruby float (e.g. `3.14`) serializes to a bare JSON float |
+| `string_basic.txt` | Plain Ruby string serializes to a JSON double-quoted string |
+| `string_dollar_escape.txt` | Strings starting with `$` are escaped to `$$…` to avoid collision with Flight's `$L` reference syntax |
+| `array.txt` | Ruby array serializes to a JSON array in row 0 |
+| `hash.txt` | Ruby hash serializes to a JSON object in row 0 |
+| `client_reference.txt` | A `ClientReference` (no props) produces an import row (`I`) + root element referencing `$L1` |
+| `client_component_with_props.txt` | A `ClientReference` with props passes them as the fourth element of the root array |
+| `react_element_no_props.txt` | A `ReactElement` with no props produces `["$","<tag>",null,{}]` in row 0 |
+| `as_json_object.txt` | An object responding to `as_json` is serialized via that method; if it resolves to a `ClientReference`, import + root rows are emitted |
+| `serializable_object.txt` | An object including `Ruact::Serializable` and declaring `rsc_props` serializes only the declared props |
+| `redirect_row.txt` | A redirect instruction serializes to a JSON object with `redirectUrl` and `redirectType` keys in row 0 |
+
+---
+
+## Adding a New Fixture
+
+See the [Fixture-First Workflow](../../../CONTRIBUTING.md#fixture-first-workflow-adding-a-new-serializable-type) section in `CONTRIBUTING.md` for the full four-step process.
+
+Quick reference:
+
+1. Create `spec/fixtures/flight/<type_name>.txt` with the expected wire bytes.
+2. Write a failing spec using `match_flight_fixture("<type_name>")`.
+3. Implement the type handler in `flight/serializer.rb`.
+4. Run `bundle exec rspec` — the new spec must pass, full suite must have no regressions.

data/spec/fixtures/flight/array.txt

@@ -0,0 +1 @@
+0:[1,"a",true,null]

data/spec/fixtures/flight/as_json_object.txt

@@ -0,0 +1,2 @@
+1:I["/PostCard.jsx","PostCard",["/PostCard.jsx"]]
+0:["$","$L1",null,{"post":{"id":1,"title":"Hello","author":"Alice","likesCount":5}}]

data/spec/fixtures/flight/boolean_false.txt

@@ -0,0 +1 @@
+0:false

data/spec/fixtures/flight/boolean_true.txt

@@ -0,0 +1 @@
+0:true

data/spec/fixtures/flight/client_component_with_props.txt

@@ -0,0 +1,2 @@
+1:I["/CounterButton.jsx","CounterButton",["/CounterButton.jsx"]]
+0:["$","$L1",null,{"initialCount":0,"label":"Click me","disabled":false}]

data/spec/fixtures/flight/client_reference.txt

@@ -0,0 +1,2 @@
+1:I["/LikeButton.jsx","LikeButton",["/LikeButton.jsx"]]
+0:["$","$L1",null,{}]

data/spec/fixtures/flight/hash.txt

@@ -0,0 +1 @@
+0:{"debug":true,"count":5,"label":"x"}

data/spec/fixtures/flight/nil.txt

@@ -0,0 +1 @@
+0:null

data/spec/fixtures/flight/number_float.txt

@@ -0,0 +1 @@
+0:3.14

data/spec/fixtures/flight/number_integer.txt

@@ -0,0 +1 @@
+0:42

data/spec/fixtures/flight/react_element_no_props.txt

@@ -0,0 +1 @@
+0:["$","div",null,{}]

data/spec/fixtures/flight/redirect_row.txt

@@ -0,0 +1 @@
+0:{"redirectUrl":"/posts/1","redirectType":"push"}

data/spec/fixtures/flight/serializable_object.txt

@@ -0,0 +1,2 @@
+1:I["/PostCard.jsx","PostCard",["/PostCard.jsx"]]
+0:["$","$L1",null,{"post":{"id":1,"title":"Hello"}}]

data/spec/fixtures/flight/string_basic.txt

@@ -0,0 +1 @@
+0:"hello"

data/spec/fixtures/flight/string_dollar_escape.txt

@@ -0,0 +1 @@
+0:"$$danger"

data/spec/ruact/client_manifest_spec.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tempfile"
+
+module Ruact
+  RSpec.describe ClientManifest do
+    let(:manifest_data) do
+      {
+        "LikeButton" => {
+          "id" => "/LikeButton.jsx",
+          "name" => "LikeButton",
+          "chunks" => ["/LikeButton.jsx"]
+        }
+      }
+    end
+
+    let(:dual_manifest_data) do
+      {
+        "LikeButton" => {
+          "id" => "/LikeButton.jsx",
+          "name" => "LikeButton",
+          "chunks" => ["/LikeButton.jsx"]
+        },
+        "posts/_like_button" => {
+          "id" => "/posts/_like_button.jsx",
+          "name" => "default",
+          "chunks" => ["/posts/_like_button.jsx"]
+        }
+      }
+    end
+
+    describe "#include?" do
+      let(:manifest) { described_class.from_hash(manifest_data) }
+
+      it "returns true for a key present in the manifest" do
+        expect(manifest.include?("LikeButton")).to be true
+      end
+
+      it "returns false for a key absent from the manifest" do
+        expect(manifest.include?("posts/_like_button")).to be false
+      end
+    end
+
+    describe "#reference_for with controller_path:" do
+      let(:shared_only_manifest) { described_class.from_hash(manifest_data) }
+      let(:dual_manifest)        { described_class.from_hash(dual_manifest_data) }
+
+      it "uses shared key when no controller_path given (AC#1)" do
+        ref = shared_only_manifest.reference_for("LikeButton")
+        expect(ref.module_id).to eq("/LikeButton.jsx")
+      end
+
+      it "uses co-located key when it exists in the manifest (AC#2)" do
+        ref = dual_manifest.reference_for("LikeButton", controller_path: "posts")
+        expect(ref.module_id).to eq("/posts/_like_button.jsx")
+      end
+
+      it "co-located takes precedence over shared when both exist (AC#3)" do
+        ref = dual_manifest.reference_for("LikeButton", controller_path: "posts")
+        expect(ref.module_id).to eq("/posts/_like_button.jsx")
+        expect(ref.module_id).not_to eq("/LikeButton.jsx")
+      end
+
+      it "falls back to shared when co-located key absent (AC#4)" do
+        ref = dual_manifest.reference_for("LikeButton", controller_path: "articles")
+        expect(ref.module_id).to eq("/LikeButton.jsx")
+      end
+
+      it "looks in comments/ first, finds none, uses shared (AC#5)" do
+        ref = dual_manifest.reference_for("LikeButton", controller_path: "comments")
+        expect(ref.module_id).to eq("/LikeButton.jsx")
+      end
+
+      it "returns the same object for repeated calls (dedup by object_id)" do
+        ref1 = dual_manifest.reference_for("LikeButton", controller_path: "posts")
+        ref2 = dual_manifest.reference_for("LikeButton", controller_path: "posts")
+        expect(ref1).to equal(ref2)
+      end
+
+      it "shared and co-located references are different objects" do
+        shared = dual_manifest.reference_for("LikeButton")
+        co_loc = dual_manifest.reference_for("LikeButton", controller_path: "posts")
+        expect(shared).not_to equal(co_loc)
+      end
+    end
+
+    describe ".load" do
+      let(:loaded_manifest) do
+        Tempfile.create(["manifest", ".json"]) do |f|
+          f.write(manifest_data.to_json)
+          f.flush
+          described_class.load(f.path)
+        end
+      end
+
+      it "returns a frozen manifest (AC#5)" do
+        expect(loaded_manifest).to be_frozen
+      end
+
+      it "allows reference_for on a frozen manifest without raising (AC#5)" do
+        expect { loaded_manifest.reference_for("LikeButton") }.not_to raise_error
+      end
+
+      it "resolves the correct ClientReference from a frozen manifest (AC#5)" do
+        ref = loaded_manifest.reference_for("LikeButton")
+        expect(ref).to be_a(Flight::ClientReference)
+        expect(ref.module_id).to eq("/LikeButton.jsx")
+      end
+
+      it "raises ManifestError for unknown component with actionable message (AC#1)" do
+        expect { loaded_manifest.reference_for("Unknown") }
+          .to raise_error(Ruact::ManifestError, /Unknown/)
+        expect { loaded_manifest.reference_for("Unknown") }
+          .to raise_error(Ruact::ManifestError, /Did you run the Vite build\?/)
+      end
+    end
+
+    describe ".from_hash" do
+      it "returns a mutable manifest (not frozen)" do
+        manifest = described_class.from_hash(manifest_data)
+        expect(manifest).not_to be_frozen
+      end
+    end
+  end
+end