rails_tool_views 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba277c8c403681504a1c5c2d154df3c7814952735ca5a10ba6981f7c50109a2d
-  data.tar.gz: a6ebf8a7b47065ffaf8585d5f57b2aff864d181fe0e7deb0085c26500b640ef4
+  metadata.gz: f8d13afb04c0aa3830428d6bf43ad18936b5e5f676bdf80b8bed717fdb5dc5aa
+  data.tar.gz: 39be934d3e43b6f7380f89ce42faf3b67ea49f93eebec65fc551dbc3d944fbc4
 SHA512:
-  metadata.gz: 276b0f741dc507376c153e900a0b20468e64cf55f66073be587eb4a0d4705bc0d8a4b2d75b5531382e80011a0bf193510acb143fbe2e6864028881422509e461
-  data.tar.gz: e216675b6918e72cdbaf75a4404e7729bac2186260cbc06a500a8130c7cacaa1312d2e436bcbe085b159534a60adc6c1898673319fd718b456fab32ddd9a8f38
+  metadata.gz: b7b9b32baaf39558ba998750dd4a181f0be83594ba71a8e21c5407b784960249f17ec8f9d551ea3e863751abd8032f12b7a548a0d447f26bffe4538a0a3b3d43
+  data.tar.gz: 2f53bf0cd980e42ee9175115b64b908face277ae907efaafbf7c21a15b70f4c97476dd45093f8d32220041567308f1f6b90c7385d60d268cc0d1e6bf8041e865

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.2.0] - 2026-10-18
+
+- Add `rails_tool_views:component NAME` for a Partial, closed registration schemas and a Minitest scaffold. Component and action policies deny by default. Existing paths, unsafe names and symlink escapes are refused before writing.
+- Render complete Engine HTML read/error pages with accessible document structure, authorized correction fields and a saved-view reload link. Embedded helpers and JSON/Turbo retain their formats.
+- Fix redirects after correcting a non-Turbo error when the referrer is a POST-only Engine route.
+- Add real Chrome E2E tests, including JavaScript-disabled mobile correction, fixture screenshots and a browser CI job. Keep browser dependencies in a development-only bundle.
+- Exercise the installed gem and generated scaffold in a temporary Rails host, both with developer dependencies and an isolated network-resolved GEM_HOME.
+- No database migration or new runtime dependency.
+
 ## [0.1.0] - 2026-10-18
 
 First public release. Earlier version labels below describe unpublished development milestones.

data/README.md

@@ -1,90 +1,34 @@
 # RailsToolViews
 
-**Turn trusted Rails views into persistent, interactive tools.**
+Turn trusted Rails Partials and ViewComponents into persistent, interactive tools. Your Rails application owns authentication, permissions and business data. RubyLLM integration is optional.
 
-Register an existing Partial or ViewComponent, present it with validated data, and let users act through authorized Rails handlers. Each view keeps its state across refreshes. Your application owns authentication, tenant boundaries and business records.
+[Documentation](https://rails-tool-views.wangyaodi.com) · [Getting started](https://rails-tool-views.wangyaodi.com/getting-started/) · [API](https://rails-tool-views.wangyaodi.com/api/) · [Roadmap](ROADMAP.md)
 
-The core runs without an AI provider. An optional RubyLLM adapter lets agents present registered components and continue after a user action. RailsToolViews does not generate executable UI code.
+## Install
 
-[Documentation](https://rails-tool-views.wangyaodi.com) · [RubyGems](https://rubygems.org/gems/rails_tool_views) · [API reference](https://rails-tool-views.wangyaodi.com/api/)
-
-Version **0.1.0** is the first public release.
-
-## Try the workbench
-
-Requires Ruby 3.3+ and Bundler. From this checkout:
-
-```sh
-bundle install
-bin/demo
-```
-
-Open **http://127.0.0.1:3100**. Stop with `Ctrl-C` when finished.
-
-| Workflow | What to try |
-| --- | --- |
-| Component playground | Present a Partial, chat card or ViewComponent. Save a choice and refresh to restore it. |
-| Customer intake | Submit an invalid email, correct it and create a customer with field-level feedback. |
-| Support workspace | Find a ticket, inspect its account, review a draft reply and confirm the local outbox. |
-| Content review | Edit, regenerate, accept a version and download its text export. |
-
-Switch synthetic identities to explore two tenants and two roles. Fixtures run locally, with no provider calls or external messages. The identity switch is a testing aid, not production authentication. See the [demo walkthrough](docs/site/_getting_started/demo.md) for test scenarios and continuation failure/retry.
-
-## Add it to a Rails application
-
-Add the gem:
-
-```ruby
-# Gemfile
-gem "rails_tool_views", "~> 0.1.0"
-```
+Requires Ruby 3.3 or later and a patched Rails release.
 
 ```sh
-bundle install
+bundle add rails_tool_views
 bin/rails generate rails_tool_views:install
 bin/rails db:migrate
 ```
 
-Follow [Getting Started](docs/site/_getting_started/getting-started.md) to configure authenticated scope resolution and register a component. Once registered, present and render it:
-
-```ruby
-scope = RailsToolViews::Scope.new(actor: current_user.id.to_s, tenant: current_account.id.to_s)
-surface = RailsToolViews.present(:choice_card, props: approved_props, scope: scope)
-```
-
-```erb
-<%= rails_tool_views_surface(surface, scope: scope) %>
-```
+Continue with [Getting Started](https://rails-tool-views.wangyaodi.com/getting-started/) to configure authenticated scope and register your first component. Component and action policies deny access until you configure them.
 
-Component and action policies deny by default. The host must authorize domain records and allowed values independently of proposed props. External side effects require host idempotency or an outbox. Read [Security](SECURITY.md) before integration.
+## Try the demo
 
-## Documentation
-
-Read the [searchable guides](https://rails-tool-views.wangyaodi.com). Preview locally with `docs/bin/serve.sh`; setup and build instructions are in [docs/README.md](docs/README.md).
-
-- [Getting Started](docs/site/_getting_started/getting-started.md): installation and a working first component.
-- [Configuration](docs/site/_getting_started/configuration.md): host identity and engine settings.
-- [Core guides](docs/site/_core_features): components, surfaces, actions and validation.
-- [Advanced guides](docs/site/_advanced): optional RubyLLM, continuation and production boundaries.
-- [API reference](docs/site/_reference/api-reference.md): generated Ruby API documentation.
-- [Upgrading](docs/site/_reference/upgrading.md): moving an unpublished development host to the first public version.
-
-The dummy host in [`test/dummy`](test/dummy) contains the complete runnable examples and is excluded from the gem runtime. OddlyDock is a planned reference host, not a dependency.
-
-## Development
+From this checkout:
 
 ```sh
-bundle exec rake test zeitwerk:check
-bundle exec ruby scripts/package_smoke.rb
-# Optional adapter tests:
-BUNDLE_GEMFILE=gemfiles/adapter.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/adapter.gemfile bundle exec rake test:adapter
+bundle install
+bin/demo
 ```
 
-Tests use offline responses and block TCP connections. Supported dependency bounds are in [the gemspec](rails_tool_views.gemspec); tested combinations and limitations are recorded in [validation evidence](docs/evidence). MySQL and live-provider behavior remain unverified. See [the release checklist](docs/operations/02_RELEASE_CHECKLIST.md) for remaining release gates.
+Open http://127.0.0.1:3100 and stop with Ctrl-C. The demo covers choices, customer forms, support and content review using offline fixtures. See the [walkthrough](https://rails-tool-views.wangyaodi.com/demo/).
 
-## Project status and attribution
+## Contribute
 
-Released under the [MIT license](LICENSE.txt).
+Read [Contributing](CONTRIBUTING.md) for development and documentation commands. Report vulnerabilities through the [private security channel](SECURITY.md).
 
-RailsToolViews is an unofficial community project. Rails marks belong to David Heinemeier Hansson, with exclusive licensing to the Rails Foundation. Framework names identify compatibility; neither the owner nor the Foundation endorses or is affiliated with this project. See the [Rails trademark policy](https://rubyonrails.org/trademarks).
+Released under the [MIT license](LICENSE.txt). RailsToolViews is an unofficial community project, without affiliation or endorsement. Rails marks belong to David Heinemeier Hansson and are exclusively licensed to the Rails Foundation; see the [trademark policy](https://rubyonrails.org/trademarks).

data/app/controllers/rails_tool_views/surfaces_controller.rb

@@ -23,7 +23,7 @@ module RailsToolViews
       surface = RailsToolViews.restore(params[:id], scope: current_scope)
       respond_to do |format|
         format.json { render json: surface.snapshot }
-        format.html { render html: RailsToolViews.render(surface, view_context: view_context, scope: current_scope) }
+        format.html { render_surface_page(surface) }
       end
     end
 
@@ -88,9 +88,29 @@ module RailsToolViews
         format.turbo_stream { render turbo_stream: turbo_stream.replace(surface.dom_id, RailsToolViews.render(surface, view_context: view_context, scope: current_scope)), status: status }
         # Without Turbo, return to the page that embeds the Surface; it re-renders saved state.
         # The Engine's own helper keeps whatever mount path and name the host chose.
-        format.html { redirect_back_or_to surface_path(surface), allow_other_host: false, status: :see_other }
+        format.html { redirect_after_action(surface) }
       end
     end
+    def redirect_after_action(surface)
+      # After correcting a full-page error, Referer can be a POST-only Engine
+      # route. Redirect to the readable Surface instead of GET /actions (404).
+      referrer_path = begin
+        URI.parse(request.referer.to_s).path.to_s
+      rescue URI::InvalidURIError
+        ""
+      end
+      if referrer_path.start_with?("#{surface_path(surface)}/")
+        redirect_to surface_path(surface), status: :see_other
+      else
+        redirect_back_or_to surface_path(surface), allow_other_host: false, status: :see_other
+      end
+    end
+    def render_surface_page(surface, error: nil)
+      html = surface && RailsToolViews.render(surface, view_context: view_context, scope: current_scope, error: error)
+      render template: "rails_tool_views/surfaces/page", layout: "rails_tool_views/application",
+        locals: { surface_html: html, reload_path: surface && surface_path(surface), error: error },
+        status: error ? error.status : :ok
+    end
     def reject_request(error)
       respond_to do |format|
         format.json { render json: error.to_h, status: error.status }
@@ -107,9 +127,9 @@ module RailsToolViews
         format.html do
           begin
             surface = RailsToolViews.restore(params[:id], scope: current_scope)
-            render html: RailsToolViews.render(surface, view_context: view_context, scope: current_scope, error: error), status: error.status
+            render_surface_page(surface, error: error)
           rescue RailsToolViews::Error
-            render partial: "rails_tool_views/surfaces/error", locals: { error: error }, status: error.status
+            render_surface_page(nil, error: error)
           end
         end
       end

data/app/helpers/rails_tool_views/surfaces_helper.rb

@@ -4,6 +4,7 @@ module RailsToolViews
   module SurfacesHelper
     # Engine-owned copy. Translate or reword any of it under rails_tool_views.surface.<key>.
     TEXT = {
+      page_title: "Interactive view", page_error_title: "Unable to complete this request", reload: "Reload saved view",
       ready: "View ready.", saved: "Changes saved.", revision: "Saved revision %{revision}",
       saving: "Saving changes…", save_failed: "Changes could not be saved. Review the message and try again.",
       agent_pending: "AI follow-up pending.", agent_completed: "AI follow-up completed.",

data/app/views/layouts/rails_tool_views/application.html.erb

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="<%= I18n.locale %>">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= rails_tool_views_text(error ? :page_error_title : :page_title) %></title>
+  <%= csrf_meta_tags %>
+  <style>
+    .rails-tool-views-page { box-sizing: border-box; max-width: 48rem; margin: 2rem auto; padding: 0 1rem; font: 1rem/1.6 system-ui, sans-serif; overflow-wrap: anywhere; }
+    .rails-tool-views-page * { box-sizing: border-box; }
+    .rails-tool-views-page input, .rails-tool-views-page textarea, .rails-tool-views-page select { max-width: 100%; font: inherit; }
+    .rails-tool-views-page label { display: block; }
+    .rails-tool-views-page fieldset { min-width: 0; }
+    .rails-tool-views-page button, .rails-tool-views-page input[type=submit] { padding: .5rem 1rem; font: inherit; cursor: pointer; }
+    .rails-tool-views-page [role=alert], .rails-tool-views-page [aria-invalid=true] { color: #a51d1d; }
+    .rails-tool-views-page :focus-visible { outline: 3px solid #215dc4; outline-offset: 3px; }
+  </style>
+</head>
+<body class="rails-tool-views-page">
+  <main aria-labelledby="rails-tool-views-page-title">
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/rails_tool_views/surfaces/page.html.erb

@@ -0,0 +1,9 @@
+<h1 id="rails-tool-views-page-title"><%= rails_tool_views_text(error ? :page_error_title : :page_title) %></h1>
+<% if surface_html %>
+  <%= surface_html %>
+<% elsif error %>
+  <%= render partial: "rails_tool_views/surfaces/error", locals: { error: error } %>
+<% end %>
+<% if error && reload_path %>
+  <p><%= link_to rails_tool_views_text(:reload), reload_path %></p>
+<% end %>

data/lib/generators/rails_tool_views/component/component_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+require "rails/generators"
+
+module RailsToolViews
+  module Generators
+    # Generates a trusted Partial definition with closed schemas and denied policies.
+    class ComponentGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      argument :name, type: :string, required: true, desc: "Flat snake_case component key"
+      desc "Generate a Partial, registration and Minitest scaffold. Policies deny access until configured."
+
+      # Preflights all destinations, then writes the registration, Partial and test.
+      def create_component
+        unless name.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+          raise Thor::Error, "Use a flat snake_case name of 1 to 64 characters, starting with a letter."
+        end
+        outputs = {
+          "registration.rb" => "config/rails_tool_views/components/#{name}.rb",
+          "partial.html.erb" => "app/views/rails_tool_views/components/_#{name}.html.erb",
+          "component_test.rb" => "test/rails_tool_views/components/#{name}_test.rb"
+        }
+        # Preflight every output before writing any file. Even --force must not
+        # destroy host code or follow a symlink outside the destination root.
+        root = File.realpath(destination_root)
+        outputs.each_value do |relative|
+          path = File.join(root, relative)
+          if File.exist?(path) || File.symlink?(path)
+            raise Thor::Error, "Destination exists: #{relative}. Resolve the conflict before generating."
+          end
+          parent = File.dirname(path)
+          parent = File.dirname(parent) until File.exist?(parent) || File.symlink?(parent)
+          begin
+            real = File.realpath(parent)
+          rescue Errno::ENOENT, Errno::ELOOP
+            raise Thor::Error, "Invalid destination parent: #{relative}"
+          end
+          unless File.directory?(real) && (real == root || real.start_with?(root + File::SEPARATOR))
+            raise Thor::Error, "Destination escapes the application: #{relative}"
+          end
+        end
+        outputs.each { |source, target| template(source, target) }
+        say "Load config/rails_tool_views/components/*.rb inside your shared to_prepare block after reset_registry!."
+        say "Replace BOTH denied policies with host authorization before presenting this component."
+      end
+    end
+  end
+end

data/lib/generators/rails_tool_views/component/templates/component_test.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+require "test_helper"
+
+class <%= name.camelize %>ComponentTest < ActiveSupport::TestCase
+  test "<%= name %> denies presentation until host policies are configured" do
+    error = assert_raises(RailsToolViews::Error) do
+      RailsToolViews.present(:<%= name %>, props: { title: "Review" },
+        scope: RailsToolViews::Scope.new(actor: "test-user", tenant: "test-tenant"))
+    end
+    assert_equal "NOT_ALLOWED", error.code
+  end
+
+  # Replace the denial test when you configure host policies. Add an allowed
+  # actor/tenant, a denied actor/tenant, action validation and persisted-state tests.
+end

data/lib/generators/rails_tool_views/component/templates/partial.html.erb

@@ -0,0 +1,6 @@
+<h2><%%= props.fetch("title") %></h2>
+<%%= rails_tool_views_action_form(surface, :set_value) do |form| %>
+  <%%= form.label :value, "Value" %>
+  <%%= form.text_field :value, value: state["value"], maxlength: 120 %>
+  <%%= form.submit "Save" %>
+<%% end %>

data/lib/generators/rails_tool_views/component/templates/registration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# Load from the host's shared to_prepare block. Do not reset the registry here.
+RailsToolViews.register(:<%= name %>,
+  description: "<%= name.humanize %>",
+  partial: "rails_tool_views/components/<%= name %>",
+  schema: {
+    type: "object", additionalProperties: false, required: ["title"],
+    properties: { title: { type: "string", maxLength: 120 } }
+  },
+  # Replace with host authorization using access.actor and access.tenant.
+  policy: ->(_access) { false },
+  actions: {
+    set_value: {
+      schema: {
+        type: "object", additionalProperties: false, required: ["value"],
+        properties: { value: { type: "string", maxLength: 120 } }
+      },
+      # Recheck host authorization and trusted allowed values on every action.
+      policy: ->(_access) { false },
+      handler: ->(access) {
+        RailsToolViews::Transition.new(state: { value: access.arguments.fetch("value") })
+      }
+    }
+  })

data/lib/generators/rails_tool_views/install/templates/rails_tool_views.rb

@@ -9,4 +9,5 @@ RailsToolViews.configure do |config|
   # config.parent_controller = "::ApplicationController"
 end
 # Register trusted components and explicit policies in Rails.application.config.to_prepare.
-# Read the gem README for a complete ChoiceCard definition and optional adapter.
+# Generate a safe scaffold: bin/rails generate rails_tool_views:component review_card
+# See https://rails-tool-views.wangyaodi.com/component-generator/ for registration and policies.

data/lib/rails_tool_views/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module RailsToolViews
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_tool_views
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Wang
@@ -178,10 +178,16 @@ files:
 - app/models/rails_tool_views/presentation.rb
 - app/models/rails_tool_views/redacted_json.rb
 - app/models/rails_tool_views/surface.rb
+- app/views/layouts/rails_tool_views/application.html.erb
 - app/views/rails_tool_views/surfaces/_error.html.erb
 - app/views/rails_tool_views/surfaces/_surface.html.erb
+- app/views/rails_tool_views/surfaces/page.html.erb
 - config/routes.rb
 - db/migrate/20261010000000_create_rails_tool_views.rb
+- lib/generators/rails_tool_views/component/component_generator.rb
+- lib/generators/rails_tool_views/component/templates/component_test.rb
+- lib/generators/rails_tool_views/component/templates/partial.html.erb
+- lib/generators/rails_tool_views/component/templates/registration.rb
 - lib/generators/rails_tool_views/install/install_generator.rb
 - lib/generators/rails_tool_views/install/templates/create_rails_tool_views.rb
 - lib/generators/rails_tool_views/install/templates/rails_tool_views.rb