ruact 0.0.10 → 0.0.12

data/spec/benchmarks/baseline.json

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

data/spec/benchmarks/render_pipeline_benchmark_spec.rb

@@ -1,92 +0,0 @@
-# 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.render({ erb: erb_source, binding: ctx.instance_eval { binding } }, mode: :string)
-  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

@@ -1,136 +0,0 @@
-# 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 to assert on Flight output
-
-Three RSpec matcher modes live in `spec/support/matchers/flight_fixture_matcher.rb`. Pick the mode that names what you actually care about — defaulting to `match_flight_structure` for new specs avoids the cosmetic-change brittleness that bit Phase 1 (a `JSON.generate` tweak broke 30+ specs at once).
-
-| Mode | When to use | What it tolerates | Failure shape |
-|---|---|---|---|
-| `match_flight_fixture(name)` | The wire format itself is the contract — bytes-for-bytes guard. Use for serializer escape rules, ordering invariants, or any test where "the output looks exactly like this" is the assertion. | Nothing — exact `==` against the fixture file. | Inspected expected vs. actual strings (whitespace and escapes visible). |
-| `match_flight_structure(expected)` | The parsed semantics are the contract — change-tolerant. Use for round-tripping tests, scaffolding, end-to-end render tests, and any case where JSON key reordering or whitespace tweaks should not break the spec. | JSON key insertion order inside payload hashes; whitespace inside JSON; relative ordering among `:import` rows (which Flight treats as an unordered set). Cross-class row order (imports → models → deferred → errors) is **preserved** because the wire protocol depends on it. | Row-indexed diff naming the differing field path (e.g. `Row 0 (model) differs at .payload[0]:`). |
-| `include_flight_row(predicate)` | A specific shape must appear regardless of order or siblings. Use for concurrency tests, partial assertions in multi-row outputs, or "this row exists somewhere" checks. | Sibling rows; ordering. Predicate is subset-matched (only the keys you list are compared). | Predicate inspect + a list of every parsed row with id/class/payload preview. |
-
-### Worked examples
-
-Each example is a complete RSpec assertion you can paste into a spec file (above `RSpec.describe` blocks where the matchers are autoloaded by `spec_helper`).
-
-**`match_flight_fixture` — wire-format contract guard:**
-```ruby
-serialized = "0:\"$$danger\"\n"
-expect(serialized).to match_flight_fixture("string_dollar_escape")
-# Asserts byte-for-byte against `string_dollar_escape.txt` — proves the `$` → `$$` escape rule.
-```
-
-**`match_flight_structure` — parsed-semantics assertion:**
-```ruby
-wire = %(1:I["/LikeButton.jsx","LikeButton",["/LikeButton.jsx"]]\n) +
-       %(0:["$","$L1",null,{"postId":42}]\n)
-
-expect(wire).to match_flight_structure([
-  { id: 1, class: :import, payload: ["/LikeButton.jsx", "LikeButton", ["/LikeButton.jsx"]] },
-  { id: 0, class: :model,  payload: ["$", "$L1", nil, { "postId" => 42 }] }
-])
-# Passes even if `JSON.generate` re-orders props later — what matters is that postId=42 round-trips.
-```
-
-**`include_flight_row` — ordering-independent presence check:**
-```ruby
-wire = %(0:["$","CounterButton",null,{"initialCount":0}]\n)
-
-expect(wire).to include_flight_row(
-  class: :model,
-  payload: hash_including("initialCount" => 0)
-)
-# Used in concurrency specs where multiple threads emit interleaved rows; only the row's shape matters.
-```
-
-### ❌ Avoid / ✅ Prefer
-
-```ruby
-❌ expect(output).to include('"postId":42')   # cosmetic-change brittle
-✅ expect(output).to include_flight_row(class: :model, payload: hash_including("postId" => 42))
-```
-
-A future `JSON.generate` change that emits keys in different insertion order (`{"label":"x","postId":42}` instead of `{"postId":42,"label":"x"}`) breaks the literal substring match. The structural form parses the row and compares hashes by key-set, so it survives the cosmetic change.
-
-### When a fixture spec fails after a serializer change
-
-If `match_flight_fixture` fails after touching `Ruact::Flight::Serializer`, that's by design — the wire format **is** the contract for those fixtures. Either the change is intentional (update the fixture file and the CHANGELOG) or it isn't (revert). Don't switch the spec to `match_flight_structure` to "make it green"; that hides the regression that fixture mode is designed to catch.
-
----
-
-## 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 |
-| `bigint.txt` | Ruby integer above `MAX_SAFE_INTEGER` (`2**53`) serializes to `"$n<decimal>"` so the JS client can rebuild a `BigInt` |
-| `nan.txt` | `Float::NAN` serializes to `"$NaN"` (JSON has no NaN literal; Flight uses the `$`-prefix sentinel) |
-| `infinity.txt` | `Float::INFINITY` serializes to `"$Infinity"` |
-| `negative_infinity.txt` | `-Float::INFINITY` serializes to `"$-Infinity"` |
-| `undefined.txt` | The `:undefined` symbol sentinel serializes to `"$undefined"` so the JS client decodes it as `undefined` (JSON has no undefined literal) |
-| `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 `ruact_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

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

data/spec/fixtures/flight/as_json_object.txt

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

data/spec/fixtures/flight/bigint.txt

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

data/spec/fixtures/flight/boolean_false.txt

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

data/spec/fixtures/flight/boolean_true.txt

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

data/spec/fixtures/flight/client_component_with_props.txt

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

data/spec/fixtures/flight/client_reference.txt

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

data/spec/fixtures/flight/hash.txt

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

data/spec/fixtures/flight/infinity.txt

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

data/spec/fixtures/flight/nan.txt

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

data/spec/fixtures/flight/negative_infinity.txt

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

data/spec/fixtures/flight/nil.txt

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

data/spec/fixtures/flight/number_float.txt

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

data/spec/fixtures/flight/number_integer.txt

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

data/spec/fixtures/flight/react_element_no_props.txt

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

data/spec/fixtures/flight/redirect_row.txt

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

data/spec/fixtures/flight/serializable_object.txt

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

data/spec/fixtures/flight/string_basic.txt

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

data/spec/fixtures/flight/string_dollar_escape.txt

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

data/spec/fixtures/flight/undefined.txt

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

data/spec/fixtures/readme/children-error.html.erb

@@ -1,3 +0,0 @@
-<h1><%= @greeting %></h1>
-
-<LikeButton likes={@likes}>Like</LikeButton>

data/spec/fixtures/readme/children-error.txt

@@ -1 +0,0 @@
-ruact: <LikeButton> at app/views/home/index.html.erb:3 children are not supported — pass content as a prop, e.g. `<LikeButton content={...} />`.

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

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

data/spec/fixtures/story_7_9_views/controller_request_spec_support/errors_demo/new.html.erb

@@ -1,3 +0,0 @@
-<div>
-  <DemoButton label={"new-post"} errors={ruact_errors} />
-</div>

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

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

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

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

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

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

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

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

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

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

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

@@ -1,16 +0,0 @@
-<%# 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

@@ -1,24 +0,0 @@
-<%# 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>

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

@@ -1,15 +0,0 @@
-<%# A layout that calls `ruact_js_assets` but never got the React root div.
-    The payload and the bootstrap both ship, so an assets-only readiness check
-    accepts it — and the browser boots React with nothing to mount into,
-    producing a silently blank page. %>
-<!DOCTYPE html>
-<html>
-  <head>
-    <link rel="stylesheet" href="/host-app.css" />
-    <title>Host App Title</title>
-  </head>
-  <body>
-    <%= yield %>
-    <%= ruact_js_assets %>
-  </body>
-</html>

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

@@ -1,17 +0,0 @@
-<%# A MIGRATED host layout: the app owns the document. The stylesheet link is
-    the whole point — it is the thing ruact's built-in shell has no slot for,
-    so a spec asserting it appears in the response is asserting that the host
-    app's CSS actually reaches a ruact page. %>
-<!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>
-    <%= ruact_js_assets %>
-  </body>
-</html>

data/spec/readme_demo_message_spec.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-require "pathname"
-
-# Story 5.2 — the anti-rot gate for the README's write→verify demo.
-#
-# ⚠️  THE README DEMO SHOWS THIS MESSAGE. If this spec goes red, the recording
-#     at https://ruact.dev/readme-write-verify.gif is now showing a message the
-#     gem no longer produces — RE-RECORD IT.
-#     Sources: design-artifacts/E-Assets/readme-write-verify/ in the planning
-#     repository (`./build-app.sh && ./record.sh && ./assemble.sh`).
-#
-# The fixture is PRODUCED BY THE GEM, never transcribed. It was written by
-# running the preprocessor over the committed `.html.erb` beside it:
-#
-#   ruby -Ilib -rruact -e 'begin
-#     Ruact::ErbPreprocessor.transform(
-#       File.read("spec/fixtures/readme/children-error.html.erb"),
-#       identifier: "app/views/home/index.html.erb")
-#   rescue Ruact::ChildrenNotSupportedError => e
-#     File.write("spec/fixtures/readme/children-error.txt", e.message + "\n")
-#   end'
-#
-# The identifier is the guide's own template path, so the fixture is verbatim
-# the line the recording shows (modulo the absolute prefix Rails prepends in a
-# real app). The monorepo owns the other half of this gate: the same failure
-# reached through a real Rails render, in
-# docs/examples/getting-started/harness/spec/requests/getting_started_spec.rb.
-# That one cannot live here — the gem repository is public and reads nothing
-# from the private planning repository — which is exactly why this spec exists:
-# the published artifact stays verifiable in its own repository.
-RSpec.describe "the README demo's error message", :story_5_2 do
-  let(:root) { Pathname.new(File.expand_path("..", __dir__)) }
-  let(:fixtures) { root.join("spec/fixtures/readme") }
-  let(:source) { fixtures.join("children-error.html.erb").read }
-  let(:expected) { fixtures.join("children-error.txt").read.strip }
-
-  # The exact call the recording's third beat makes, one layer down: a template
-  # whose PascalCase tag has children, compiled with the guide's template path.
-  def message
-    Ruact::ErbPreprocessor.transform(source, identifier: "app/views/home/index.html.erb")
-    raise "expected Ruact::ChildrenNotSupportedError, none was raised"
-  rescue Ruact::ChildrenNotSupportedError => e
-    e.message
-  end
-
-  it "is byte-for-byte what the gem produces today" do
-    expect(message).to eq(expected),
-                       "the loud-children message changed. The README demo at " \
-                       "https://ruact.dev/readme-write-verify.gif shows the old one — " \
-                       "regenerate the fixture, then RE-RECORD the demo."
-  end
-
-  it "names the component, the file:line and the fix — the three things the demo is about" do
-    expect(expected).to include("<LikeButton>")
-    expect(expected).to include("app/views/home/index.html.erb:3")
-    expect(expected).to include("<LikeButton content={...} />")
-  end
-
-  it "is the message the README's demo is claimed to show" do
-    readme = root.join("README.md").read
-
-    expect(readme).to include("https://ruact.dev/readme-write-verify.gif")
-    expect(readme).to include("Ruact::ChildrenNotSupportedError")
-  end
-end