ruact 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1722a96137257e2263f7aee2e2315c4a197f634fad94096da555de6d7a50af9
-  data.tar.gz: 34d485a11f2b0cf893770bddbf4c48fa757d908f0f24e0c64e03d2f612bd351f
+  metadata.gz: eb5572218264cb747d7e6d89f990946c3eb05b4614469f4d96fd69158aece888
+  data.tar.gz: efe3a28deef2028b9470d0d1edbe5770d7289f668b72d842c0a4f4cab8aef47c
 SHA512:
-  metadata.gz: 770a14ec78795d73afed6bc044f2616167e5cd4a6b173489ad9c8e8c1df893534b54e77f5515e59a3fecbd54a4d2763eaaa3a920cbf40fc7594922e7e831a912
-  data.tar.gz: 41fc153c5d7470df08b7ca02b2c2da2a2ae0c74c717186119ed2eaa4504b903da1cfab43754a21f738b40541afc4ed98534f05fdcf4e3ba3c317f963b351b27b
+  metadata.gz: 6fd494f658f9e5121f0f2beed2965c6d58926f8c4ec1f4d6b0b3db714d903c9a3a4ecc1492c32e5e3f61dc6bad10ea716e2a9795884cd5319bcc039af4c5dc3b
+  data.tar.gz: bd6ac4fcf1042364845221187cb85d64dd3f299bc6873d1a9d7cd796cbf1ec13e95b07692ef55c5dd4c1e861ad9180639d97c5df19e7d2cc2eb4a0d777972fb1

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.10] - 2026-08-25
+
+### Changed
+
+- **`README.md` — the gem's public face is no longer `bundle gem` boilerplate.** The file GitHub renders on `github.com/luizcg/ruact`, the file `spec.files` packages *inside* the built `.gem`, and the destination of `source_code_uri` still said *"TODO: Delete this and the text below"*, told the reader to `bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG`, and pointed contributors at `https://github.com/[USERNAME]/ruact`. It is now a first-contact README for v0.0.9: the four-command greenfield quick start (the same sequence the site's landing puts on the clipboard), the ERB-tag/`"use client"` pair, `include Ruact::Server` with its generated typed accessor, a list where every bullet names a shipped artifact, a compatibility table sourced from the CI matrix rather than from optimism, and links out to `ruact.dev` instead of second copies of the guides.
+
+  It also carries the **AI-tools section deferred here from the docs work** — the one-requirement rule (`"use client"` at the top; a PascalCase *named* export is the thing to check rather than add), the four-step walkthrough, and a pointer to the canonical page — plus one line naming the shipped agent context: the `AGENTS.md` `rails generate ruact:install` writes, `ruact.dev/llms.txt`, and the experimental `-- --json` output of `ruact:doctor` / `ruact:routes`.
+
+  Two gates now watch it, because nothing did before: `spec/readme_spec.rb` runs inside this repo's own `rspec` job (no boilerplate literals, every relative link resolves on disk, no `path:` gem source a reader could copy, and the quick-start block pinned literally), and the monorepo's command-spine check treats `README.md` as a declared artifact of the one canonical greenfield sequence.
+
+### Added
+
+- **A demo at the top of `README.md` — the write→verify loop, recorded rather than described.** The README could argue the mechanism in prose and code but could not show what happens when the boundary is used wrong, which is the part a reader of *"React rendered from Rails templates"* actually doubts. The recording is one loop: an ERB template with `<LikeButton likes={@likes} />` beside the `"use client"` component it resolves to; the component rendering in a browser, its count changing on click; children put inside the tag — the JSX habit — and the next request stopping **server-side, while the template is being processed, before anything reaches the browser**, with `Ruact::ChildrenNotSupportedError` naming the component, the template file and line, and the fix; then the children removed and the page rendering again. Every frame is a capture of the gem running; the loud error is the one shipped in 0.0.9.
+
+  It is referenced by absolute URL and **nothing binary is committed here** — so neither `gem install ruact` nor a clone of this repository carries a multi-megabyte file, permanently, for a picture. Two things keep it from aging into a lie: the URL belongs to the site's URL contract, and `spec/readme_demo_message_spec.rb` pins the message the recording shows against a fixture the gem itself produced. If the wording changes, that spec goes red and names the recording as the thing to redo.
+
+- **`LICENSE.txt`** — the gemspec has declared `spec.license = "MIT"` since the first commit while the repository contained no licence file, so both GitHub and the packaged gem shipped a promise with nothing behind it.
+- **`spec.description` and `metadata["documentation_uri"]` in the gemspec** — RubyGems rendered the one-line `summary` as the whole description and fell through to rubydoc.info for documentation.
+
+### Fixed
+
+- **`SECURITY.md` named a version that has never existed.** Its supported-versions table listed `0.1.x`; the released gem is `0.0.9`. Corrected to `0.0.x`.
+
 ## [0.0.9] - 2026-08-12
 
 ### Added
@@ -224,7 +247,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.9...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.10...HEAD
+[0.0.10]: https://github.com/luizcg/ruact/releases/tag/v0.0.10
 [0.0.9]: https://github.com/luizcg/ruact/releases/tag/v0.0.9
 [0.0.8]: https://github.com/luizcg/ruact/releases/tag/v0.0.8
 [0.0.7]: https://github.com/luizcg/ruact/releases/tag/v0.0.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,37 +1,143 @@
-# Ruact
+# ruact
 
-[![codecov](https://codecov.io/gh/luizcg/ruact/branch/main/graph/badge.svg?flag=gem)](https://codecov.io/gh/luizcg/ruact)
+**Real React, right in your Rails views.** Write a PascalCase tag in ERB, pass `@post` as a prop, and a React component renders — no hand-written JSON layer, no Node process in production.
 
-TODO: Delete this and the text below, and describe your gem
+[![CI](https://github.com/luizcg/ruact/actions/workflows/ci.yml/badge.svg)](https://github.com/luizcg/ruact/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/ruact.svg)](https://badge.fury.io/rb/ruact) [![codecov](https://codecov.io/gh/luizcg/ruact/branch/main/graph/badge.svg?flag=gem)](https://codecov.io/gh/luizcg/ruact)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruact`. To experiment with that code, run `bin/console` for an interactive prompt.
+<!-- Packaging (Story 5.2): the demo is a documentation asset, published with the site
+     rather than committed here — so neither `gem install ruact` nor a clone of this
+     repository carries a multi-megabyte file, permanently, for a picture. The URL belongs
+     to the site's URL contract and cannot quietly start 404ing, the capture sources are
+     scripted and live with the project's other capture harnesses, and the message the demo
+     shows is pinned here by `spec/readme_demo_message_spec.rb`. -->
+<img src="https://ruact.dev/readme-write-verify.gif" width="800"
+     alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
 
-## Installation
+## Quick start
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+# 1. A throwaway app to try it in
+rails new myapp --skip-javascript && cd myapp
 
-Install the gem and add to the application's Gemfile by executing:
+# 2. Add the gem
+bundle add ruact
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+# 3. Write the config, the layout wiring and an AGENTS.md — then run npm install
+rails generate ruact:install
+
+# 4. Rails + Vite, one command
+bin/dev
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+That is the whole install. The [Getting Started guide](https://ruact.dev/docs/getting-started) picks it up from here — first component, first scaffold, `ruact:doctor`. Already have an app? Start at step 2, then read [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — ruact renders one action at a time and leaves the rest of your views alone.
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## How it works
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<PostCard post={@post} author={@author} />
+```
+
+```tsx
+// app/javascript/components/PostCard.tsx
+"use client"
+
+import { useState } from "react"
+
+export function PostCard({ post, author }) {
+  const [liked, setLiked] = useState(false)
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>by {author.name}</p>
+      <button onClick={() => setLiked(!liked)}>
+        {liked ? "Liked" : "Like"}
+      </button>
+    </article>
+  )
+}
+```
+
+Rails serializes `@post` and `@author` as Ruby values, sends the component tree as a [Flight](https://ruact.dev/docs/concepts/flight-wire-format) payload, and React hydrates it in the browser. No JSON ceremony, no duplicate routes, no Node.js in production.
+
+## Call Rails from React
+
+Add one line to a controller and its routed non-GET actions become callable from React at their real routes:
+
+```ruby
+class PostsController < ApplicationController
+  include Ruact::Server   # ← the only new line
+
+  def create
+    @post = Post.create!(post_params)
+    redirect_to @post
+  end
+  # ...
+end
+```
+
+```tsx
+import { createPost } from "@/.ruact/server-functions";
+
+await createPost({ post: { title: "Hi", body: "…" } });
 ```
 
-## Usage
+The verb decides — there is no per-action DSL and no second endpoint. The export name is derived from the route (`posts#create` → `createPost`), and ruact's Vite plugin regenerates the module whenever your routes change. What the call *resolves* is decided by the action you already wrote: this one redirects, so ruact follows the redirect and the call resolves `null`; an action that assigns `@post` instead resolves `{ post: … }`, through the same `ruact_props` allowlist as everything else. Reading works the same way: a `Ruact::Query` class mounted with `ruact_queries` draws one named `GET` route per public method, and React reads it with `useQuery`. Both are documented in [Server functions & queries](https://ruact.dev/docs/api/server-actions).
+
+## What you get
+
+Every item below is shipped in this gem at v0.0.9:
+
+- **ERB as server components** — `include Ruact::Controller`, then write PascalCase tags in your existing views. [Docs](https://ruact.dev/docs/concepts/erb-as-server-components)
+- **`"use client"`** — the one directive that marks a file as client-side. The bundled Vite plugin scans for it and writes the manifest. [Docs](https://ruact.dev/docs/concepts/use-client)
+- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a typed module generated from your route table. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Props are an allowlist** — `include Ruact::Serializable` + `ruact_props :id, :title`; other columns never cross. [Docs](https://ruact.dev/docs/api/serializable)
+- **Validation errors round-trip** — `ruact_errors(record)` hands React `{ title: ["can't be blank"] }` without a serializer. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
+- **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
+- **A CRUD generator** — `rails generate ruact:scaffold Post title:string body:text` delegates the model, migration and route to Rails' own `resource` generator, then adds the ruact layer. Plain semantic HTML by default; `--shadcn` opts into the Tailwind/shadcn path. It does not run migrations — `rails db:migrate` is still yours. [Docs](https://ruact.dev/docs/api/scaffold)
+- **`bin/rails ruact:doctor`** — eight checks over the manifest, Vite, the layout and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
+- **One runtime dependency** — `nokogiri`. Rails itself is not a declared dependency of this gem.
+
+## AI tools and coding agents
+
+**The only line you have to add to an AI-generated React component is `"use client"` at the top of the file.** One thing to check rather than add: the component needs a PascalCase *named* export, because that name is the tag you write in ERB.
 
-TODO: Write usage instructions here
+1. Generate the component with whatever AI tool you already use.
+2. Save it as `app/javascript/components/MyComponent.tsx`.
+3. Add `"use client"` at the top if it is not already there.
+4. Call `<MyComponent />` from ERB.
 
-## Development
+That is the whole adaptation, and it holds for any tool that outputs standard React components — nothing here is pinned to one vendor. The worked example, the traps and the real error messages are on [AI Tools & Agents](https://ruact.dev/docs/guides/ai-tools).
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+For agents driving the app rather than writing one component: `rails generate ruact:install` writes an `AGENTS.md` into your app, [ruact.dev/llms.txt](https://ruact.dev/llms.txt) serves the same context to tools that fetch from the web, and `bin/rails ruact:doctor -- --json` / `bin/rails ruact:routes -- --json` emit machine-readable output (experimental — `schema_version: 0`, and the `--` separator is required).
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Compatibility
+
+| | Version | Where that comes from |
+|---|---|---|
+| Ruby | >= 3.2 | the gemspec's `required_ruby_version` |
+| Rails | tested against 7.0, 7.1, 7.2 and 8.0 | every commit runs the full CI matrix; the gemspec sets no Rails bound |
+| React | 19.x | the `package.json` the install generator writes |
+| Node.js | >= 20 | the build only — ruact runs no Node process in production |
+
+## Documentation
+
+Everything lives at [ruact.dev](https://ruact.dev):
+
+- [Getting Started](https://ruact.dev/docs/getting-started) — from `rails new` to a rendered component
+- [Why ruact?](https://ruact.dev/docs/why-ruact) — where it sits next to Hotwire and Inertia
+- [Server functions & queries](https://ruact.dev/docs/api/server-actions) — the full request/response contract
+- [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — adopting it one action at a time
+- [Testing](https://ruact.dev/docs/guides/testing) — render assertions on the server side
+- [Changelog](CHANGELOG.md) — also published at [ruact.dev/docs/changelog](https://ruact.dev/docs/changelog)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruact.
+Bug reports and pull requests are welcome at [github.com/luizcg/ruact/issues](https://github.com/luizcg/ruact/issues).
+
+Release process: [RELEASING.md](RELEASING.md). Security policy and private reporting: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/SECURITY.md

@@ -6,7 +6,7 @@ Only the latest patch release of the current minor version is actively maintaine
 
 | Version | Supported |
 |---------|-----------|
-| 0.1.x   | ✅ Yes    |
+| 0.0.x   | ✅ Yes    |
 
 Once a new minor version is released, the previous minor version receives security fixes for **90 days** after the new release, then it is no longer supported.
 

data/lib/ruact/version.rb

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

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

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

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

@@ -0,0 +1 @@
+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/readme_demo_message_spec.rb

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

data/spec/readme_spec.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "nokogiri"
+require "pathname"
+
+# Story 5.14 — the README gate that lives INSIDE this repository.
+#
+# `README.md` is not an ordinary readme: GitHub renders it on the gem's own
+# repository page, `source_code_uri` points at it, and `spec.files` packages it
+# *inside* the built `.gem`. Until this story it was still `bundle gem`
+# boilerplate ("TODO: Delete this and the text below"), and that boilerplate had
+# already shipped to RubyGems.
+#
+# The planning monorepo has a command-spine gate
+# (`docs/examples/getting-started/scripts/check-commands.mjs`) that reads this
+# file through the `gem/` submodule and checks its quick start against ONE
+# canonical greenfield sequence — the SPINE, which is the single source of
+# truth. But a merge in THIS repository fires nothing over there, so a
+# README-only PR here would stay unchecked until somebody bumped the submodule
+# pointer.
+#
+# Hence the deliberate duplication below: `expected_quick_start` is a literal
+# copy of the quick-start block, owned by this spec, and the monorepo gate
+# verifies that literal against the canonical SPINE. The dependency runs one way
+# only — this spec reads nothing outside the gem repository, because a public
+# artifact that cannot be verified in its own repository is not verifiable.
+RSpec.describe "README.md", :story_5_14 do
+  subject(:readme) { root.join("README.md").read }
+
+  let(:root) { Pathname.new(File.expand_path("..", __dir__)) }
+
+  # Every literal `bundle gem` leaves behind. Each one was present before this
+  # story; any of them coming back means the scaffolding was re-pasted.
+  let(:boilerplate) do
+    [
+      "TODO:",
+      "UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG",
+      "[USERNAME]",
+      "Welcome to your new gem",
+      "Put your Ruby code in the file",
+      "bin/console",
+      "bundle exec rake release"
+    ]
+  end
+
+  # Harness-only gem sources. They exist so the monorepo's playgrounds can test
+  # the working tree; a reader who copies one installs nothing.
+  let(:path_gem_sources) do
+    [
+      /(^|\s)gem\s+["']ruact["']\s*,\s*path:/,
+      /--path(\s|=)/
+    ]
+  end
+
+  # The quick-start block, byte for byte. Changing it here without changing the
+  # monorepo SPINE (or the other way round) turns the monorepo gate red.
+  let(:expected_quick_start) do
+    <<~BASH
+      # 1. A throwaway app to try it in
+      rails new myapp --skip-javascript && cd myapp
+
+      # 2. Add the gem
+      bundle add ruact
+
+      # 3. Write the config, the layout wiring and an AGENTS.md — then run npm install
+      rails generate ruact:install
+
+      # 4. Rails + Vite, one command
+      bin/dev
+    BASH
+  end
+
+  # `[text](target)` and `![alt](target)`, inline-title form allowed.
+  def markdown_link_targets(markdown)
+    markdown.scan(/\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/).flatten
+  end
+
+  # Story 5.2 — the demo reference, pinned BYTE FOR BYTE.
+  #
+  # The first version of this gate hand-rolled HTML and CommonMark recognition
+  # out of regexes, and review corrected it in three consecutive rounds:
+  # `\bsrc=` matched `data-src=`, a literal `>` inside an attribute ended the
+  # tag early, fences were only recognised at column 0, then unterminated
+  # fences were not recognised at all, then unquoted attribute values were
+  # invisible. Those are not five bugs. Neither HTML nor CommonMark is a
+  # regular language, so that list has no end, and a gate whose coverage is
+  # "whatever the regex happens to know this week" is not a gate.
+  #
+  # Replaced by three statements that are TOTAL:
+  #
+  #   1. the reference is pinned literally — the same move `expected_quick_start`
+  #      above already makes for the quick start;
+  #   2. the file is allowed EXACTLY ONE raw `<img>`, counted at the byte level;
+  #      and
+  #   3. the parsed document holds exactly one LIVE `<img>` element, equal to
+  #      the pinned one attribute for attribute.
+  #
+  # (1) and (2) together say something the old scanner could only approximate:
+  # every raw image reference in this README is the pinned one. A second `<img>`
+  # anywhere — including inside a fenced example, terminated or not — turns
+  # this red and has to be gated deliberately rather than slipping through a
+  # blind spot. (3) says the thing bytes cannot: that it renders. The pinned
+  # block wrapped in an HTML comment satisfies (1) and (2) and shows nothing.
+  #
+  # Attributes are then read with Nokogiri, already a runtime dependency of this
+  # gem (see the gemspec), so unquoted values, `>` inside a value and `data-src`
+  # are PARSED rather than pattern-matched. What that scope does and does not
+  # promise is written down in the monorepo's gate inventory,
+  # docs/examples/getting-started/README.md § "What is still outside both gates".
+  def expected_demo_img
+    <<~HTML
+      <img src="https://ruact.dev/readme-write-verify.gif" width="800"
+           alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
+    HTML
+  end
+
+  def demo_src
+    "https://ruact.dev/readme-write-verify.gif"
+  end
+
+  # Parsed from the pinned literal, exactly as `expected_quick_start` is the
+  # authority for the quick start: one example asserts the README contains
+  # these bytes, and the rest read meaning off them. The chain is
+  # README -> literal -> parser, and the first link is what makes it honest.
+  def demo_node
+    Nokogiri::HTML5.fragment(expected_demo_img).at_css("img")
+  end
+
+  # Byte-level and case-insensitive on purpose: no parser, no markdown, nothing
+  # to have a blind spot. `<IMG`, `<img\n`, an `<img` inside a fence — all count.
+  def raw_img_count(markdown)
+    markdown.scan(/<img\b/i).length
+  end
+
+  # …and the same parser turned on the README ITSELF, because the two byte-level
+  # facts above are about bytes, not about rendering: wrap the pinned block in
+  # an HTML comment and the literal is still present and the raw count is still
+  # one, while GitHub shows nothing at all (verified — `include`=true, raw=1,
+  # live nodes=0). Nokogiri is what decides whether a tag is an element or a
+  # comment, so it is what the "it renders" half of this gate has to ask.
+  def readme_img_nodes
+    Nokogiri::HTML5.fragment(readme).css("img")
+  end
+
+  # Absolute URLs, anchors and mailto: links are somebody else's problem; on-disk
+  # targets are ours.
+  def relative(targets)
+    targets.reject { |target| target.start_with?("http://", "https://", "#", "mailto:") }
+  end
+
+  def bash_blocks(markdown)
+    markdown.scan(/^```bash[ \t]*\n(.*?)^```/m).flatten
+  end
+
+  it "carries none of the `bundle gem` boilerplate" do
+    present = boilerplate.select { |literal| readme.include?(literal) }
+
+    expect(present).to be_empty,
+                       "README.md still carries bundler scaffolding: #{present.inspect}"
+  end
+
+  it "links only to files that exist in this repository" do
+    targets = relative(markdown_link_targets(readme) + [demo_node["src"]])
+    missing = targets.reject { |target| root.join(target.split("#").first.to_s).exist? }
+
+    expect(targets).not_to be_empty, "expected the README to link at least one repo-relative file"
+    expect(missing).to be_empty,
+                       "README.md links files that do not exist in the gem repository: #{missing.inspect}"
+  end
+
+  # Story 5.2 — the demo GIF is a documentation asset hosted with the site, so
+  # this repository stays free of binaries: no `.gem` download and no clone
+  # pays for it. The consequence is that the reference is an absolute URL, and
+  # an absolute URL cannot be resolved on disk here — the monorepo puts it in
+  # `website/scripts/verify-urls.mjs`'s PATHS, checked against the deployed
+  # site, so a dead image goes red there instead of rotting silently.
+  it "carries the write→verify demo reference, byte for byte" do
+    expect(readme).to include(expected_demo_img),
+                      "the demo reference in README.md drifted from the literal this spec pins. " \
+                      "Change both or neither — and if the recording itself changed, see " \
+                      "readme_demo_message_spec.rb."
+  end
+
+  # The other half of the pin: because there is exactly ONE raw `<img>` and the
+  # example above proves it is the pinned one, "the pinned literal is present"
+  # and "every raw image in this file is checked" are the same statement.
+  it "carries exactly one raw <img>, so the pin covers every raw image in the file" do
+    expect(raw_img_count(readme)).to eq(1),
+                                     "README.md has #{raw_img_count(readme)} raw <img> tags. This gate is " \
+                                     "written for exactly one — the demo, pinned literally. A second image " \
+                                     "must be gated deliberately, not left to a scanner's blind spots."
+  end
+
+  # And the demo is LIVE, not merely present. Bytes inside an HTML comment
+  # satisfy both statements above and render nothing; only a parser can tell
+  # the difference, so the README itself is parsed and the node it yields must
+  # be the pinned one, attribute for attribute.
+  it "renders the demo as a real element, not as bytes inside a comment" do
+    nodes = readme_img_nodes
+
+    expect(nodes.length).to eq(1),
+                            "README.md parses to #{nodes.length} live <img> element(s); the demo must be " \
+                            "exactly one, and must not be commented out."
+    expect(nodes.first.attributes.transform_values(&:value))
+      .to eq(demo_node.attributes.transform_values(&:value))
+  end
+
+  it "keeps the demo hosted with the site rather than committed here" do
+    expect(demo_node["src"]).to eq(demo_src)
+
+    # `git ls-files` and not a filesystem glob, because that is precisely what
+    # `spec.files` packages (ruact.gemspec) — untracked build output is not the
+    # question here, and coverage/ is full of it.
+    tracked = IO.popen(%w[git ls-files -z], chdir: root.to_s, err: IO::NULL) do |ls|
+      ls.readlines("\x0", chomp: true)
+    end
+    committed_media = tracked.grep(/\.(gif|mp4|webm|webp)\z/i)
+
+    expect(committed_media).to be_empty,
+                               "media committed under gem/ ships inside every `.gem` and stays in the " \
+                               "clone history forever: #{committed_media.inspect}"
+  end
+
+  # The alt text is the only thing a screen-reader user — or an agent reading
+  # the README as text — gets. "demo" is not a description.
+  it "describes the demo's arc in its alt text" do
+    # Nokogiri resolves the entities, so this reads what a screen reader reads:
+    # `&lt;LikeButton` is the tag the demo shows, not four literal characters.
+    alt = demo_node["alt"].to_s
+
+    expect(alt.split.length).to be > 40, "the demo's alt text does not describe the arc: #{alt.inspect}"
+    expect(alt).to include("Ruact::ChildrenNotSupportedError")
+    expect(alt).not_to match(/\bbuild\b/i),
+                       "the failure the demo shows happens server-side at render, not at build — " \
+                       "see Story 5.2 AC4"
+  end
+
+  # Story 5.2, learned the expensive way: YARD parses README.md as the docs'
+  # main file and read `{@likes}` in the demo's alt text as a link macro it
+  # could not resolve — and `--fail-on-warning` turned that into a red REQUIRED
+  # check, for a README edit, in a job whose output says nothing about READMEs.
+  # Braces belong in prose as `&#123;`/`&#125;`: GitHub renders them, YARD never
+  # sees them.
+  #
+  # SCOPE, deliberately: this checks the pinned demo block, not the whole file.
+  # Knowing which parts of a markdown document YARD linkifies means knowing
+  # where the fenced blocks are, and this gate no longer recognises fences —
+  # that is the trade this redesign makes. `yard --fail-on-warning` in this
+  # repository's own CI is the TOTAL gate; this example exists so the one line
+  # that actually tripped it fails locally, in the suite that owns the README,
+  # naming the cause.
+  it "keeps YARD link macros out of the demo block, which is what reddened the docs job" do
+    # `{@ivar}`, `{Class}`, `{Class::Nested}`, `{Class#method}`, `{Class.method}`
+    # — the shapes YARD resolves. It does not try to resolve anything with a
+    # space in it, which is why the prose's `{ post: … }` elsewhere is safe.
+    macros = expected_demo_img.scan(/\{(?:@\w+|[A-Z][\w:.#]*)\}/)
+
+    expect(macros).to be_empty,
+                      "the demo block contains #{macros.inspect}, which YARD tries to resolve as a " \
+                      "link and `yard --fail-on-warning` fails on. Use &#123; / &#125;."
+  end
+
+  it "shows no harness-only `path:` gem source a reader could copy" do
+    offenders = path_gem_sources.filter_map { |pattern| pattern.source if readme.match?(pattern) }
+
+    expect(offenders).to be_empty,
+                         "README.md shows a harness-only gem source (#{offenders.inspect}) — " \
+                         "a reader who copies it installs nothing"
+  end
+
+  it "pins the quick start to the canonical greenfield sequence" do
+    expect(bash_blocks(readme).first).to eq(expected_quick_start),
+                                         "the README quick start drifted. It is checked against the monorepo's " \
+                                         "canonical SPINE (docs/examples/getting-started/scripts/" \
+                                         "check-commands.mjs); change both or neither."
+  end
+
+  it "keeps the quick start in a ```bash fence, the only language the monorepo gate reads" do
+    expect(readme).to include("```bash\n#{expected_quick_start}```")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruact
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Luiz Garcia
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -24,7 +24,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.15'
-description:
+description: |
+  ruact renders React components straight from your ERB views: write a PascalCase
+  tag, pass a Ruby value as a prop, and React hydrates it in the browser over the
+  Flight wire format. Server functions and queries are drawn from your existing
+  route table, so there is no hand-written JSON layer to keep in sync and no Node
+  process in production.
 email:
 - luizcg@gmail.com
 executables: []
@@ -37,6 +42,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- LICENSE.txt
 - README.md
 - RELEASING.md
 - Rakefile
@@ -156,6 +162,8 @@ files:
 - spec/fixtures/flight/string_basic.txt
 - spec/fixtures/flight/string_dollar_escape.txt
 - spec/fixtures/flight/undefined.txt
+- spec/fixtures/readme/children-error.html.erb
+- spec/fixtures/readme/children-error.txt
 - spec/fixtures/story_7_9_views/controller_request_spec_support/demo/show.html.erb
 - spec/fixtures/story_7_9_views/controller_request_spec_support/errors_demo/new.html.erb
 - spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb
@@ -167,6 +175,8 @@ files:
 - spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb
 - spec/fixtures/story_7_9_views/layouts/rootless_host.html.erb
 - spec/fixtures/story_7_9_views/layouts/ruact_host.html.erb
+- spec/readme_demo_message_spec.rb
+- spec/readme_spec.rb
 - spec/ruact/client_manifest_spec.rb
 - spec/ruact/component_contract_spec.rb
 - spec/ruact/configuration_spec.rb
@@ -265,6 +275,7 @@ metadata:
   source_code_uri: https://github.com/luizcg/ruact
   changelog_uri: https://github.com/luizcg/ruact/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/luizcg/ruact/issues
+  documentation_uri: https://ruact.dev
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []