RubyGems - ruact - Versions diffs - 0.0.7 → 0.0.9 - Mend

ruact 0.0.7 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -1
data/docs/internal/decisions/server-functions-api.md +55 -0
data/lib/generators/ruact/install/install_generator.rb +378 -6
data/lib/generators/ruact/install/templates/AGENTS.md.tt +159 -0
data/lib/generators/ruact/install/templates/Procfile.dev.tt +3 -0
data/lib/generators/ruact/install/templates/globals.css.tt +20 -0
data/lib/generators/ruact/install/templates/initializer.rb.tt +9 -0
data/lib/generators/ruact/install/templates/package.json.tt +7 -1
data/lib/generators/ruact/install/templates/tsconfig.json.tt +18 -0
data/lib/generators/ruact/scaffold/scaffold_shadcn_preflight.rb +10 -0
data/lib/ruact/configuration.rb +73 -0
data/lib/ruact/controller/document_rendering.rb +210 -0
data/lib/ruact/controller.rb +14 -46
data/lib/ruact/doctor.rb +102 -12
data/lib/ruact/erb_preprocessor.rb +113 -0
data/lib/ruact/errors.rb +16 -0
data/lib/ruact/layout_source.rb +59 -0
data/lib/ruact/manifest_resolver.rb +2 -2
data/lib/ruact/serializable.rb +98 -6
data/lib/ruact/server.rb +163 -0
data/lib/ruact/server_functions/introspection.rb +81 -0
data/lib/ruact/server_functions.rb +26 -4
data/lib/ruact/testing/component_query.rb +113 -0
data/lib/ruact/testing/flight_extractor.rb +221 -0
data/lib/ruact/testing/flight_structure_diff.rb +267 -0
data/lib/ruact/testing/flight_wire_parser.rb +138 -0
data/lib/ruact/testing.rb +90 -0
data/lib/ruact/version.rb +1 -1
data/lib/ruact/view_helper.rb +10 -1
data/lib/ruact.rb +1 -0
data/lib/tasks/ruact.rake +55 -2
data/spec/fixtures/story_7_9_views/controller_request_spec_support/exploding_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/ghost_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/rootless_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/controller_request_spec_support/unwired_layout_demo/show.html.erb +3 -0
data/spec/fixtures/story_7_9_views/layouts/bare_host.html.erb +16 -0
data/spec/fixtures/story_7_9_views/layouts/exploding_host.html.erb +24 -0
data/spec/fixtures/story_7_9_views/layouts/rootless_host.html.erb +15 -0
data/spec/fixtures/story_7_9_views/layouts/ruact_host.html.erb +17 -0
data/spec/ruact/controller_request_spec.rb +203 -0
data/spec/ruact/doctor_spec.rb +222 -6
data/spec/ruact/erb_preprocessor_spec.rb +145 -0
data/spec/ruact/install_generator_spec.rb +727 -70
data/spec/ruact/layout_source_spec.rb +108 -0
data/spec/ruact/manifest_resolver_spec.rb +15 -0
data/spec/ruact/scaffold_generator_spec.rb +14 -0
data/spec/ruact/serializable_spec.rb +126 -0
data/spec/ruact/server_bucket_request_spec.rb +291 -0
data/spec/ruact/server_functions/introspection_spec.rb +135 -0
data/spec/ruact/tasks_json_introspection_spec.rb +141 -0
data/spec/ruact/testing/have_ruact_component_spec.rb +170 -0
data/spec/ruact/testing/no_production_load_spec.rb +41 -0
data/spec/support/flight_wire_parser.rb +12 -126
data/spec/support/matchers/flight_fixture_matcher.rb +7 -258
data/vendor/javascript/ruact-server-functions-runtime/index.d.ts +25 -0
data/vendor/javascript/ruact-server-functions-runtime/index.js +104 -7
data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs +173 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts +25 -0
metadata +30 -4

data/spec/ruact/layout_source_spec.rb ADDED Viewed

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+require "spec_helper"
+require "ruact"
+# The single definition of "is this layout migrated?", shared by the runtime and
+# by `ruact:install`. Every example here is a shape that fooled an earlier,
+# looser check — a NAME where only a CALL counts, or a substring where only an
+# attribute counts.
+RSpec.describe Ruact::LayoutSource do
+  describe ".wired?" do
+    it "accepts a plain output tag" do
+      expect(described_class.wired?("<%= ruact_js_assets %>")).to be true
+    end
+    it "accepts the raw-output form and tight whitespace" do
+      expect(described_class.wired?("<%==ruact_js_assets%>")).to be true
+    end
+    it "accepts a call with an argument" do
+      expect(described_class.wired?("<%= ruact_js_assets(payload) %>")).to be true
+    end
+    # Round-1 finding: a mention in prose read as wired.
+    it "rejects a mention inside an ERB comment" do
+      expect(described_class.wired?("<%# remember to add ruact_js_assets here %>")).to be false
+    end
+    # Round-2 finding, and the sharper version of the same mistake: a genuinely
+    # COMMENTED-OUT call. ERB comments do not nest, so this emits nothing — but
+    # a regex looking only for `<%=` sees a call and reports the layout ready,
+    # which sends the runtime off to render an unmigrated layout.
+    it "rejects a commented-out call" do
+      expect(described_class.wired?("<%# <%= ruact_js_assets %> %>")).to be false
+    end
+    it "rejects a multi-line comment that wraps a call" do
+      source = <<~ERB
+        <%#
+          disabled for now:
+          <%= ruact_js_assets %>
+        %>
+      ERB
+      expect(described_class.wired?(source)).to be false
+    end
+    it "still sees a real call that follows a comment mentioning it" do
+      expect(described_class.wired?("<%# ruact_js_assets %>\n<%= ruact_js_assets %>")).to be true
+    end
+    # Round-3 finding: ERB's trim-mode comment (`<%-# ... -%>`) is a comment in
+    # Erubi too — verified by compiling it — but the stripper only knew `<%#`,
+    # so a call disabled this way read as wired.
+    it "rejects a call disabled with a trim-mode comment" do
+      expect(described_class.wired?("<%-# <%= ruact_js_assets %> -%>")).to be false
+    end
+    # Round-3 finding, the other direction: forbidding `%` before the name to
+    # avoid crossing tag boundaries also rejected legitimate calls. A false
+    # "unwired" is safer than a false "wired", but it is still a wrong answer —
+    # the app would silently keep ruact's CSS-less shell.
+    it "accepts a call whose expression contains a percent sign" do
+      expect(described_class.wired?(%(<%= raw("100%") + ruact_js_assets %>))).to be true
+      expect(described_class.wired?("<%= ruact_js_assets if 50 % 2 == 0 %>")).to be true
+    end
+    it "still refuses to match across a tag boundary" do
+      expect(described_class.wired?("<%= something %> then a bare ruact_js_assets mention")).to be false
+    end
+    it "rejects a layout that never names it" do
+      expect(described_class.wired?("<html><body><%= yield %></body></html>")).to be false
+    end
+  end
+  describe ".root?" do
+    it "accepts the emitted form" do
+      expect(described_class.root?(%(<div id="root"></div>))).to be true
+    end
+    it "accepts single quotes, extra attributes and unquoted values" do
+      expect(described_class.root?(%(<div id='root'></div>))).to be true
+      expect(described_class.root?(%(<div class="a" id="root" data-x="1"></div>))).to be true
+      expect(described_class.root?(%(<div id=root></div>))).to be true
+    end
+    # Round-2 finding: `data-id="root"` is not a mount point, and a document
+    # carrying one but no real root gives React nothing to mount into.
+    it "rejects a look-alike attribute" do
+      expect(described_class.root?(%(<body data-id="root"></body>))).to be false
+    end
+    it "rejects a different id that merely starts with root" do
+      expect(described_class.root?(%(<div id="rootish"></div>))).to be false
+    end
+  end
+  # The anchor `ruact:install` injects after.
+  describe "::ROOT_ELEMENT" do
+    it "anchors on a whole empty root div" do
+      expect(described_class::ROOT_ELEMENT).to match(%(<div id="root"></div>))
+    end
+    it "does not anchor on a look-alike attribute" do
+      expect(described_class::ROOT_ELEMENT).not_to match(%(<div data-id="root"></div>))
+    end
+  end
+end

data/spec/ruact/manifest_resolver_spec.rb CHANGED Viewed

@@ -107,6 +107,21 @@ module Ruact
         expect { described_class.resolve }.to raise_error(ManifestError, %r{Vite dev server.*bin/dev}m)
       end
+      # Story 15.0 (F8) — an error message is a prompt: agents (and humans)
+      # regex-match error text, so the ENGLISH wording and its stable tokens
+      # (`Vite dev server`, `react-client-manifest.json`, `bin/dev`) are pinned.
+      it "raises the ENGLISH message naming the dev-server URL, the manifest path and the bin/dev fix " \
+         "(Story 15.0)", :story_15_0 do
+        allow(Net::HTTP).to receive(:start).and_raise(Errno::ECONNREFUSED)
+        allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")
+        expect { described_class.resolve }.to raise_error(ManifestError) do |error|
+          expect(error.message).to include("[ruact] Vite dev server unreachable at http://localhost:5173")
+          expect(error.message).to include("no react-client-manifest.json found at /no/such/manifest.json")
+          expect(error.message).to include("run `bin/dev`")
+        end
+      end
       it "ignores a non-2xx dev-server response and falls back" do
         allow(Net::HTTP).to receive(:start).and_return(Net::HTTPNotFound.new("1.1", "404", "Not Found"))
         allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")

data/spec/ruact/scaffold_generator_spec.rb CHANGED Viewed

@@ -1136,6 +1136,20 @@ RSpec.describe Ruact::Generators::ScaffoldGenerator, :story_10_1 do # rubocop:di
         expect(minimal).to eq(%w[button input label badge table alert-dialog dropdown-menu])
       end
+      # `ruact:install --shadcn` runs before any resource exists, so it prints
+      # the SUPERSET constant instead of this per-resource list. If a template
+      # ever imports a primitive the constant does not carry, the printed
+      # `npx shadcn add` line would be short one component and the scaffold
+      # would fail its own pre-flight — so pin the relationship.
+      it "keeps the per-resource list a subset of the superset install prints" do
+        superset = described_class::ShadcnPreflight::ALL_SHADCN_COMPONENTS
+        richest  = build(%w[Post title:string body:text published:boolean author:references])
+                   .required_shadcn_components
+        expect(richest).to all(be_in(superset))
+        expect(superset).to match_array(richest)
+      end
       it "maps each component to its app/javascript/components/ui/<name>.tsx file" do
         gen = build(default_args)
         expect(gen.shadcn_component_file("table").to_s)

data/spec/ruact/serializable_spec.rb CHANGED Viewed

@@ -32,6 +32,132 @@ module Ruact
       end
     end
+    # Story 13.7 — `ruact_props` on ActiveRecord models.
+    #
+    # ActiveRecord defines its attribute reader methods LAZILY (on first
+    # instance access), so at the moment the `ruact_props :title` macro runs,
+    # `method_defined?(:title)` is `false` even for a real column. The eager
+    # boot check used to raise there, so an AR model that included
+    # `Ruact::Serializable` crashed at class-load. Story 13.7 makes the check
+    # HYBRID: POROs are still checked eagerly at class-load (byte-identical, see
+    # the block above), while for a lazy-attribute (AR) class the loud check is
+    # DEFERRED to the first `ruact_serialize` — where the DB is up and the reader
+    # exists. Loudness is preserved: a bogus prop still raises a clean
+    # `ArgumentError`, just at first render of that model instead of at boot.
+    #
+    # Zero suite-boot DB footprint: the connection + table are built INSIDE the
+    # example (direct connection DDL, NOT `Schema.define`, so we touch nothing
+    # global — no `schema_migrations` / `ar_internal_metadata`), and only a
+    # connection we ourselves opened is torn down.
+    describe "ActiveRecord models (Story 13.7)", :story_13_7 do
+      before do
+        require "active_record"
+        @already_connected =
+          ActiveRecord::Base.respond_to?(:connected?) && ActiveRecord::Base.connected?
+        ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:") unless @already_connected
+        ActiveRecord::Base.connection.create_table(:ruact_props_probe_posts, force: true) do |t|
+          t.string :title
+          t.string :secret
+        end
+      end
+      after do
+        if defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+          ActiveRecord::Base.connection.drop_table(:ruact_props_probe_posts, if_exists: true)
+        end
+        ActiveRecord::Base.remove_connection unless @already_connected
+      end
+      let(:ar_model) do
+        Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+          ruact_props :id, :title
+        end
+      end
+      it "loads without raising even though readers are lazy at class-load (AC#1)" do
+        expect { ar_model }.not_to raise_error
+      end
+      it "ruact_serialize returns only the declared allowlist (AC#1)" do
+        row = ar_model.create!(title: "Hello", secret: "top-secret")
+        expect(row.ruact_serialize).to eq({ "id" => row.id, "title" => "Hello" })
+        expect(row.ruact_serialize.keys).not_to include("secret")
+      end
+      it "defers the loud check to first serialize for a bogus prop (AC#2)" do
+        model = nil
+        # Declaring a bogus prop on an AR model does NOT raise at class-load —
+        # the reader might still be defined lazily, so the check is deferred.
+        expect do
+          model = Class.new(ActiveRecord::Base) do
+            self.table_name = "ruact_props_probe_posts"
+            include Ruact::Serializable
+            ruact_props :ttile # typo — neither a column nor a method
+          end
+        end.not_to raise_error
+        # …but it fails LOUDLY (same clean ArgumentError) on first serialize.
+        expect { model.new.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+      it "re-validates loudly when props are re-declared after a first serialize (AC#2)" do
+        model = Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+          ruact_props :id, :title
+        end
+        # First serialize succeeds and memoizes "validated"…
+        model.create!(title: "Hello").ruact_serialize
+        # …a re-declaration with a bogus prop must NOT be masked by the stale
+        # memo: the next serialize still raises the clean ArgumentError.
+        model.ruact_props :id, :ttile
+        expect { model.new.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+      it "re-validates an inherited declaration re-declared on the parent after a subclass serialize (AC#2)" do
+        parent = Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+          ruact_props :id, :title
+        end
+        child = Class.new(parent)
+        # The subclass serializes first, memoizing the inherited (valid) list…
+        parent.create!(title: "Hello")
+        child.first.ruact_serialize
+        # …then the PARENT re-declares with a bogus prop. The subclass must not
+        # keep serving its stale memo: its next serialize re-validates loudly.
+        parent.ruact_props :id, :ttile
+        expect { child.first.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+      it "dispatches through serialize_serializable under strict true AND false (AC#4)" do
+        row = ar_model.create!(title: "Hello", secret: "top-secret")
+        [true, false].each do |strict|
+          output = Ruact::Flight::Renderer.render(
+            row, Ruact::ClientManifest.from_hash({}), strict_serialization: strict
+          )
+          expect(output).to include("Hello")
+          expect(output).not_to include("top-secret")
+        end
+      end
+    end
     describe "ruact_serialize (AC#1)" do
       it "returns only declared props" do
         obj = serializable_class.new

data/spec/ruact/server_bucket_request_spec.rb CHANGED Viewed

@@ -138,6 +138,47 @@ module ServerBucketSpecSupport
       post.valid?
       ruact_errors(post)
     end
+    # Story 15.0 (F6) — the injection-BYPASS case the dev warning targets:
+    # registers errors, then renders explicitly on the same branch, so
+    # `default_render` never runs and the errors vanish from the JSON body.
+    def opt_out_render
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      render json: { "ok" => false }
+    end
+    # Story 15.0 (F6 guardrail a) — the documented-correct Bucket-1 pattern:
+    # register errors, render the form page again (the template binds the
+    # `ruact_errors` reader). Requested WITHOUT the function-call Accept.
+    def failed_with_page_render
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      render :new_form
+    end
+    # Story 15.0 (F6 guardrail b) — register errors, then redirect (the
+    # redirect-back round-trip). Correct on BOTH buckets, must never warn.
+    def failed_with_redirect
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      redirect_to "/posts/new"
+    end
+    # Story 15.0 (F6 guardrail d) — explicit render with an UNTOUCHED collector.
+    def untouched_explicit_render
+      render json: { "ok" => true }
+    end
+    # Story 15.5 (FR109) — a plain Rails action on a `Ruact::Server` controller:
+    # a GET that renders plain text, so it is neither a function call nor a ruact
+    # page render. The dev shape-log must stay SILENT on it (non-negotiated).
+    def plain_rails
+      render plain: "just rails"
+    end
   end
   # Review round 2 — an auth-style before_action that redirects on a Bucket-2
@@ -211,6 +252,15 @@ ControllerRequestSpecSupport.write_view(
   ERB
 )
+# Story 15.0 (F6 guardrail a) — the re-rendered form page for the documented
+# Bucket-1 `ruact_errors(record); render :new_form` pattern. No component tags
+# on purpose (the guardrail is about the warn predicate, not the pipeline).
+ControllerRequestSpecSupport.write_view(
+  "server_bucket_spec_support/bucket_server", "new_form", <<~ERB
+    <div>the form again</div>
+  ERB
+)
 if defined?(ControllerRequestSpecSupport) &&
    !ControllerRequestSpecSupport.instance_variable_get(:@__ruact_server_bucket_routes_appended)
   ControllerRequestSpecSupport.instance_variable_set(:@__ruact_server_bucket_routes_appended, true)
@@ -227,6 +277,15 @@ if defined?(ControllerRequestSpecSupport) &&
     post "/bucket/validated_create_invalid", to: "server_bucket_spec_support/bucket_server#validated_create_invalid"
     post "/bucket/validated_create_valid",   to: "server_bucket_spec_support/bucket_server#validated_create_valid"
     post "/bucket/stray_errors_ivar", to: "server_bucket_spec_support/bucket_server#stray_errors_ivar"
+    # Story 15.0 (F6) — the warning truth-table routes.
+    post "/bucket/opt_out_render", to: "server_bucket_spec_support/bucket_server#opt_out_render"
+    post "/bucket/failed_with_page_render",
+         to: "server_bucket_spec_support/bucket_server#failed_with_page_render"
+    post "/bucket/failed_with_redirect", to: "server_bucket_spec_support/bucket_server#failed_with_redirect"
+    post "/bucket/untouched_explicit_render",
+         to: "server_bucket_spec_support/bucket_server#untouched_explicit_render"
+    # Story 15.5 (FR109) — a plain Rails GET on a Server controller (non-negotiated).
+    get  "/bucket/plain_rails", to: "server_bucket_spec_support/bucket_server#plain_rails"
     post "/bucket/dual_redirecting", to: "server_bucket_spec_support/bucket_dual#redirecting"
     post "/bucket/protected", to: "server_bucket_spec_support/bucket_forgery#create_protected"
     get  "/bucket/csrf_token", to: "server_bucket_spec_support/bucket_forgery#csrf_token"
@@ -472,6 +531,124 @@ RSpec.describe "Story 9.2: Ruact::Server dual-bucket response negotiation", :sto
     # NON-raised 200 path above; the two contracts stay distinct.
   end
+  # Story 15.0 (F6) — the dev-mode injection opt-out warning truth table.
+  # Fires ONLY on: development + function-call request + touched collector +
+  # explicit host render. Silent on every documented-correct pattern.
+  describe "Story 15.0: dev-mode ruact_errors injection opt-out warning (F6)", :story_15_0 do
+    # The distinctive fragment of the F6 message (deliberately distinct from
+    # any other `[ruact]` log line, incl. the future 15.5 bucket log).
+    let(:warning_re) { /\[ruact\] .*called `ruact_errors` and then rendered explicitly/ }
+    let(:html_form_headers) do
+      { "CONTENT_TYPE" => "application/x-www-form-urlencoded", "HTTP_ACCEPT" => "text/html" }
+    end
+    before do
+      allow(Rails.logger).to receive(:warn)
+    end
+    # NOTE: the suite's default Rails.env is "development" (RAILS_ENV unset),
+    # so the dev examples stub it EXPLICITLY anyway (they must not depend on
+    # the suite default) and the non-dev example stubs a non-dev env.
+    def stub_env(name)
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new(name))
+    end
+    def stub_development_env
+      stub_env("development")
+    end
+    it "warns exactly once on an explicit render after ruact_errors on a function-call request" do
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+      expect(Rails.logger).to have_received(:warn).with(
+        a_string_matching(/\[ruact\] .*BucketServerController#opt_out_render.*ruact_errors.*NOT.*injected/m)
+      ).once
+    end
+    it "names the fix in the message (fall through, page-render binding, or redirect)" do
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+      expect(Rails.logger).to have_received(:warn).with(
+        a_string_matching(/fall.*through.*errors=\{ruact_errors\}.*redirect_to/m)
+      )
+    end
+    it "keeps the response byte-identical whether the warning fires or not (log-only)" do
+      stub_env("production")
+      post "/bucket/opt_out_render", "{}", json_headers
+      silent_status = last_response.status
+      silent_body   = last_response.body
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+      expect(Rails.logger).to have_received(:warn).with(a_string_matching(warning_re))
+      expect(last_response.status).to eq(silent_status)
+      expect(last_response.body).to eq(silent_body)
+      expect(JSON.parse(last_response.body)).to eq("ok" => false)
+    end
+    it "guardrail (a): silent on the documented Bucket-1 `ruact_errors(record); render :new` pattern" do
+      stub_development_env
+      post "/bucket/failed_with_page_render", "post[title]=", html_form_headers
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to include("the form again")
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "guardrail (b): silent on `ruact_errors(record); redirect_to` on a function-call request" do
+      stub_development_env
+      post "/bucket/failed_with_redirect", "{}", json_headers
+      expect(JSON.parse(last_response.body)).to eq("$redirect" => "/posts/new")
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "guardrail (b): silent on `ruact_errors(record); redirect_to` on a Bucket-1 request" do
+      stub_development_env
+      post "/bucket/failed_with_redirect", "post[title]=", html_form_headers
+      expect(last_response.status).to eq(302)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "guardrail (c): silent on the fall-through itself (errors were injected)" do
+      stub_development_env
+      post "/bucket/validated_create_invalid", "{}", json_headers
+      expect(JSON.parse(last_response.body).fetch("errors")).to eq("title" => ["Title can't be blank"])
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "guardrail (d): silent on an explicit render when the collector was never touched" do
+      stub_development_env
+      post "/bucket/untouched_explicit_render", "{}", json_headers
+      expect(JSON.parse(last_response.body)).to eq("ok" => true)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "never warns outside development (the bypass case in the test env stays silent)" do
+      stub_env("test")
+      post "/bucket/opt_out_render", "{}", json_headers
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+    it "never warns in production either" do
+      stub_env("production")
+      post "/bucket/opt_out_render", "{}", json_headers
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+  end
   # Story 10.0 (AC5) — the Server-path inherits the default_render graceful
   # degradation fix. A GET is never a function call, so Server#default_render
   # delegates to super → the fixed Controller#default_render.
@@ -491,4 +668,118 @@ RSpec.describe "Story 9.2: Ruact::Server dual-bucket response negotiation", :sto
       expect(last_response.headers["Content-Type"]).to include("text/x-component")
     end
   end
+  # Story 15.5 (FR109) — the dev-mode response-shape legibility log. One
+  # `[ruact]` line per ruact-NEGOTIATED request naming the chosen bucket + the
+  # deciding signal. Log-only (byte-identical), dev-gated, SILENT on
+  # non-negotiated (plain Rails) responses. Mirrors the F6 warning test shape.
+  describe "Story 15.5: dev-mode response-shape log (FR109)", :story_15_5 do
+    # The distinctive fragment of the 15.5 log — deliberately distinct from the
+    # F6 warning line (which matches `called \`ruact_errors\` and then rendered`).
+    let(:shape_log_re) { /\[ruact\] .* — .* → / }
+    let(:flight_headers)   { { "HTTP_ACCEPT" => "text/x-component" } }
+    let(:html_get_headers) { { "HTTP_ACCEPT" => "*/*" } }
+    before do
+      # The suite default env is development (RAILS_ENV unset); dev examples
+      # still stub it explicitly so they never depend on the suite default.
+      allow(Rails.logger).to receive(:info)
+    end
+    def stub_env(name)
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new(name))
+    end
+    def stub_development_env
+      stub_env("development")
+    end
+    it "logs the function-call JSON bucket once with the deciding signal (AC2)" do
+      stub_development_env
+      post "/bucket/with_ivars", "{}", json_headers
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::BucketServerController#with_ivars — " \
+        "Accept: application/json + POST → function-call JSON"
+      ).once
+    end
+    it "names the 204 (no ivars) sub-shape" do
+      stub_development_env
+      post "/bucket/empty", "{}", json_headers
+      expect(last_response.status).to eq(204)
+      expect(Rails.logger).to have_received(:info).with(
+        a_string_matching(%r{#empty_action — Accept: application/json \+ POST → function-call JSON \(204, no ivars\)})
+      ).once
+    end
+    it "names the $redirect sub-shape" do
+      stub_development_env
+      post "/bucket/redirecting", "{}", json_headers
+      expect(JSON.parse(last_response.body)).to eq("$redirect" => "/posts/1")
+      expect(Rails.logger).to have_received(:info).with(
+        a_string_matching(%r{#redirecting — Accept: application/json \+ POST → function-call \$redirect})
+      ).once
+    end
+    it "logs the Flight-page bucket on a text/x-component page render (AC2)" do
+      stub_development_env
+      get "/server-implicit/show", {}, flight_headers
+      expect(last_response.headers["Content-Type"]).to include("text/x-component")
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::ServerImplicitController#show — " \
+        "Accept: text/x-component → Flight page"
+      ).once
+    end
+    it "logs the HTML-shell bucket on an HTML-acceptable page GET (AC2)" do
+      stub_development_env
+      get "/server-implicit/show", {}, html_get_headers
+      expect(last_response.headers["Content-Type"]).to include("text/html")
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::ServerImplicitController#show — " \
+        "HTML-acceptable Accept, no Flight header → HTML shell"
+      ).once
+    end
+    it "is SILENT on a plain Rails action on the same controller (non-negotiated, AC2)" do
+      stub_development_env
+      get "/bucket/plain_rails"
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to eq("just rails")
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+    end
+    it "is SILENT outside development and byte-identical to the dev response (log-only, AC2)",
+       :aggregate_failures do
+      stub_env("production")
+      post "/bucket/with_ivars", "{}", json_headers
+      prod_status = last_response.status
+      prod_body   = last_response.body
+      prod_ctype  = last_response.headers["Content-Type"]
+      prod_vary   = last_response.headers["Vary"]
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+      stub_development_env
+      post "/bucket/with_ivars", "{}", json_headers
+      expect(Rails.logger).to have_received(:info).with(a_string_matching(shape_log_re))
+      expect(last_response.status).to eq(prod_status)
+      expect(last_response.body).to eq(prod_body)
+      expect(last_response.headers["Content-Type"]).to eq(prod_ctype)
+      expect(last_response.headers["Vary"]).to eq(prod_vary)
+    end
+    it "never logs in the test environment either" do
+      stub_env("test")
+      post "/bucket/with_ivars", "{}", json_headers
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+    end
+  end
 end