rails_tool_views 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba277c8c403681504a1c5c2d154df3c7814952735ca5a10ba6981f7c50109a2d
-  data.tar.gz: a6ebf8a7b47065ffaf8585d5f57b2aff864d181fe0e7deb0085c26500b640ef4
+  metadata.gz: 5f0b45e8093744ab3053cb621e1b8118ef6c618b98f907e8e88b9b16f5b36fba
+  data.tar.gz: '05959be24f98969c883260f0b06cef6815d812393bf7c250d0d1dea1cc552e7b'
 SHA512:
-  metadata.gz: 276b0f741dc507376c153e900a0b20468e64cf55f66073be587eb4a0d4705bc0d8a4b2d75b5531382e80011a0bf193510acb143fbe2e6864028881422509e461
-  data.tar.gz: e216675b6918e72cdbaf75a4404e7729bac2186260cbc06a500a8130c7cacaa1312d2e436bcbe085b159534a60adc6c1898673319fd718b456fab32ddd9a8f38
+  metadata.gz: 57ab0c782013453cc510f47402fcdae2b934a06fe69760b45411466b543c851d7b8b84e653bcef7824f3267f97319783e712754b7c321b9bd844826645f94afe
+  data.tar.gz: 2d741cf1b44e389bb3cc7a00bcf1de0da70ef3377077950fed1c4a166d9a62d7ac3ae339550779616b2c414ed23b8612531b2d2fda01f10e462cbc40d7ba6b5b

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.3.0] - 2026-10-19
+
+- Opt-in scoped `purge_closed` preview/apply with deadlines, bounded batches, atomic receipt cleanup and durable correlation tombstones. Host business records stay intact.
+
+- Add explicit host-authorized `close` and `abandon`, with read-only closed rendering, preserved exact action replay and first-termination retention deadlines.
+- Add lifecycle snapshot metadata and an additive migration. Stop old workers before upgrading; rollback refuses once a Surface was closed.
+- Coordinate delivery claims and lifecycle changes through the Surface lock while keeping callbacks outside transactions. Quarantine ambiguous lease takeovers and legacy multiple-attempt histories from cleanup.
+
+## [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,9 @@ 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",
+      closed_title: "View closed.", abandoned_title: "View abandoned.", closed_help: "Saved actions are read-only. Start a new view to continue.",
+      agent_abandoned: "AI follow-up abandoned by the application.",
       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.",
@@ -55,6 +58,7 @@ module RailsToolViews
     end
 
     def rails_tool_views_body(surface, definition, error: nil) # :nodoc:
+      return render(partial: "rails_tool_views/surfaces/closed", formats: [:html], locals: { surface: surface }) if surface.closed?
       html = if definition.partial
         render(partial: definition.partial, locals: { props: surface.props, state: surface.state, surface: surface, error: error })
       else

data/app/models/rails_tool_views/agent_interaction.rb

@@ -6,6 +6,8 @@ module RailsToolViews
     belongs_to :surface
     belongs_to :action_execution
     self.filter_attributes += %i[payload]
+    # Rails 7.2 cannot infer a SQLite boolean default written by Rails 8.1.
+    attribute :delivery_uncertain, :boolean, default: false
     attribute :payload, RedactedJson.new
     # Returns the stable host deduplication key across delivery retries.
     def delivery_key

data/app/models/rails_tool_views/surface.rb

@@ -15,9 +15,25 @@ module RailsToolViews
     def dom_id
       "rails_tool_views_surface_#{id}"
     end
+    # True once the host closes or abandons the view. Closed views cannot reopen.
+    def closed?
+      closed_at.present?
+    end
+    # True when payload cleanup has retained only the durable tombstone.
+    def purged?
+      purged_at.present?
+    end
+    # Returns the lifecycle independently of domain record or delivery status.
+    def lifecycle_status
+      return "purged" if purged?
+      return "abandoned" if abandoned_at
+      closed? ? "closed" : "active"
+    end
     # Returns the UI projection; it is not a permission grant.
     def snapshot
-      { id: id, component: component_key, component_digest: component_digest, props: props, state: state, revision: revision }
+      { id: id, component: component_key, component_digest: component_digest, props: props, state: state, revision: revision,
+        lifecycle: { status: lifecycle_status, closed_at: closed_at&.iso8601(6),
+          retain_until: retain_until&.iso8601(6), purged_at: purged_at&.iso8601(6) } }
     end
   end
 end

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/_closed.html.erb

@@ -0,0 +1,2 @@
+<h2><%= rails_tool_views_text(surface.abandoned_at ? :abandoned_title : :closed_title) %></h2>
+<p><%= rails_tool_views_text(:closed_help) %></p>

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

@@ -8,7 +8,7 @@
   </p>
   <% interaction = surface.agent_interactions.order(:id).last %>
   <% if interaction && interaction.status != "skipped" %>
-    <p role="status"><%= rails_tool_views_text({ "pending" => :agent_pending, "delivering" => :agent_pending, "completed" => :agent_completed, "failed" => :agent_failed }.fetch(interaction.status, :agent_unavailable)) %></p>
+    <p role="status"><%= rails_tool_views_text({ "pending" => :agent_pending, "delivering" => :agent_pending, "completed" => :agent_completed, "failed" => :agent_failed, "abandoned" => :agent_abandoned }.fetch(interaction.status, :agent_unavailable)) %></p>
     <% if interaction.status == "failed" %>
       <%= form_with url: rails_tool_views_routes.surface_continuation_path(surface, interaction_id: interaction.id), method: :post do %>
         <button type="submit"><%= rails_tool_views_text(:agent_retry) %></button>

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/db/migrate/20261019000000_add_rails_tool_views_lifecycle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+class AddRailsToolViewsLifecycle < ActiveRecord::Migration[7.2]
+  def up
+    add_column :rails_tool_views_surfaces, :closed_at, :datetime
+    add_column :rails_tool_views_surfaces, :abandoned_at, :datetime
+    add_column :rails_tool_views_surfaces, :retain_until, :datetime
+    add_column :rails_tool_views_surfaces, :purged_at, :datetime
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref, :closed_at], name: "index_rails_tool_views_retention_scope"
+    add_column :rails_tool_views_agent_interactions, :delivery_uncertain, :boolean, default: false, null: false
+    # Old rows do not distinguish explicit failed retries from lease takeovers.
+    # Preserve uncertainty instead of assuming an old callback has stopped.
+    execute "UPDATE rails_tool_views_agent_interactions SET delivery_uncertain = #{connection.quote(true)} WHERE attempts > 1 OR status = 'delivering'"
+  end
+
+  def down
+    if select_value("SELECT COUNT(*) FROM rails_tool_views_surfaces WHERE closed_at IS NOT NULL").to_i.positive?
+      raise ActiveRecord::IrreversibleMigration, "Closed or purged Surfaces cannot be safely reopened by an older runtime. Restore a pre-upgrade backup instead."
+    end
+    remove_column :rails_tool_views_agent_interactions, :delivery_uncertain
+    remove_index :rails_tool_views_surfaces, name: "index_rails_tool_views_retention_scope"
+    %i[closed_at abandoned_at retain_until purged_at].each { |column| remove_column :rails_tool_views_surfaces, column }
+  end
+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/install_generator.rb

@@ -12,6 +12,7 @@ module RailsToolViews
       end
       def install
         migration_template "create_rails_tool_views.rb", "db/migrate/create_rails_tool_views.rb"
+        migration_template "add_rails_tool_views_lifecycle.rb", "db/migrate/add_rails_tool_views_lifecycle.rb"
         template "rails_tool_views.rb", "config/initializers/rails_tool_views.rb"
         route 'mount RailsToolViews::Engine => "/rails_tool_views", as: :rails_tool_views'
       end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+class AddRailsToolViewsLifecycle < ActiveRecord::Migration[7.2]
+  def up
+    add_column :rails_tool_views_surfaces, :closed_at, :datetime
+    add_column :rails_tool_views_surfaces, :abandoned_at, :datetime
+    add_column :rails_tool_views_surfaces, :retain_until, :datetime
+    add_column :rails_tool_views_surfaces, :purged_at, :datetime
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref, :closed_at], name: "index_rails_tool_views_retention_scope"
+    add_column :rails_tool_views_agent_interactions, :delivery_uncertain, :boolean, default: false, null: false
+    # Old rows do not distinguish explicit failed retries from lease takeovers.
+    # Preserve uncertainty instead of assuming an old callback has stopped.
+    execute "UPDATE rails_tool_views_agent_interactions SET delivery_uncertain = #{connection.quote(true)} WHERE attempts > 1 OR status = 'delivering'"
+  end
+
+  def down
+    if select_value("SELECT COUNT(*) FROM rails_tool_views_surfaces WHERE closed_at IS NOT NULL").to_i.positive?
+      raise ActiveRecord::IrreversibleMigration, "Closed or purged Surfaces cannot be safely reopened by an older runtime. Restore a pre-upgrade backup instead."
+    end
+    remove_column :rails_tool_views_agent_interactions, :delivery_uncertain
+    remove_index :rails_tool_views_surfaces, name: "index_rails_tool_views_retention_scope"
+    %i[closed_at abandoned_at retain_until purged_at].each { |column| remove_column :rails_tool_views_surfaces, column }
+  end
+end

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/core.rb

@@ -13,6 +13,11 @@ module RailsToolViews
     MESSAGES = {
       "NOT_FOUND" => "This view is unavailable.", "NOT_ALLOWED" => "You do not have permission to use this view.",
       "CONFLICT" => "This view changed. Refresh to continue.", "INVALID_ARGUMENTS" => "Check the submitted values and try again.",
+      "SURFACE_CLOSED" => "This view is closed. Its saved actions cannot be changed.",
+      "SURFACE_PURGED" => "This view has been cleaned up and cannot be restored.",
+      "LIFECYCLE_BUSY" => "This view has unfinished or uncertain delivery. Resolve it before closing.",
+      "INVALID_RETENTION_REQUEST" => "Choose an explicit past cutoff and a batch size from 1 to 1000.",
+      "INVALID_RETENTION_WINDOW" => "Choose a future retention deadline or keep this view indefinitely.",
       "VALIDATION_FAILED" => "Check the highlighted fields and try again.",
       "INCOMPATIBLE_COMPONENT" => "This view's contract changed. Ask the application owner to migrate or recreate it.",
       "RENDER_FAILED" => "This view cannot be rendered. Your saved state is preserved.",
@@ -249,7 +254,7 @@ module RailsToolViews
   # Process-local host hooks, request limits, and delivery settings.
   class Configuration
     attr_accessor :scope_resolver, :agent_adapter, :max_payload_bytes, :max_depth, :max_catalog_components, :max_actions_per_minute, :auto_deliver,
-      :parent_controller, :delivery_lease
+      :parent_controller, :delivery_lease, :retention_policy
     # Initializes conservative request limits with no host identity or agent adapter.
     def initialize
       @max_payload_bytes, @max_depth, @max_catalog_components, @max_actions_per_minute = 32_768, 16, 20, 60

data/lib/rails_tool_views/lifecycle.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+module RailsToolViews
+  class << self
+    # Closes a view after host authorization. Outstanding continuation work blocks
+    # closure. nil retain_until keeps data indefinitely; the first closure wins.
+    def close(id, scope:, retain_until: nil)
+      finish_surface(id, scope: scope, retain_until: retain_until, abandon: false)
+    end
+
+    # Explicitly abandons pending/failed continuation work before closing a view.
+    # In-flight or historically uncertain delivery is never abandoned implicitly.
+    def abandon(id, scope:, retain_until: nil)
+      finish_surface(id, scope: scope, retain_until: retain_until, abandon: true)
+    end
+
+    # Scrubs eligible closed payloads in one bounded batch, preserving replay
+    # tombstones. Requires an explicit scope, cutoff and host retention policy.
+    # Defaults to a read-only preview. Each applied Surface commits atomically.
+    def purge_closed(scope:, closed_before:, batch_size: 100, dry_run: true)
+      check_scope!(scope)
+      valid_time = closed_before.is_a?(Time) || closed_before.is_a?(ActiveSupport::TimeWithZone)
+      unless valid_time && closed_before <= Time.current && batch_size.is_a?(Integer) && batch_size.between?(1, 1000) && [true, false].any? { |v| dry_run.equal?(v) }
+        raise Error.new("INVALID_RETENTION_REQUEST")
+      end
+      policy = configuration.retention_policy
+      raise Error.new("NOT_ALLOWED", status: 403) unless policy.respond_to?(:call)
+      now = Time.current
+      candidates = Surface.where(actor_ref: scope.actor, tenant_ref: scope.tenant, purged_at: nil)
+        .where("closed_at < ? AND retain_until <= ?", closed_before, now).order(:closed_at, :id).limit(batch_size).pluck(:id)
+      counts = { examined: 0, eligible: 0, purged: 0, protected: 0, dry_run: dry_run }
+      candidates.each do |id|
+        surface = Surface.find_by(id: id)
+        next unless surface
+        surface.with_lock do
+          counts[:examined] += 1
+          eligible = exact_match?(surface, actor_ref: scope.actor, tenant_ref: scope.tenant) &&
+            !surface.purged? && surface.closed? && surface.closed_at < closed_before &&
+            surface.retain_until && surface.retain_until <= now
+          if eligible
+            request = access(scope, :purge, surface: surface, props: surface.props, context_ref: surface.context_ref)
+            eligible = policy.call(request) == true && !protected_interactions?(surface, abandon: false)
+          end
+          unless eligible
+            counts[:protected] += 1
+            next
+          end
+          counts[:eligible] += 1
+          next if dry_run
+          # The Surface lock excludes action commits, delivery claims and other
+          # cleanup workers. Only known terminal children are removed together.
+          surface.agent_interactions.delete_all
+          surface.action_executions.delete_all
+          surface.update!(props: {}, state: {}, context_ref: nil, purged_at: now)
+          counts[:purged] += 1
+        end
+      end
+      counts
+    end
+
+    private
+    def finish_surface(id, scope:, retain_until:, abandon:)
+      validate_retention_deadline!(retain_until, future: false)
+      surface = restore(id, scope: scope)
+      surface.with_lock do
+        ensure_not_purged!(surface)
+        component = compatible_component!(surface)
+        component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        component.authorize!(access(scope, abandon ? :abandon : :close, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        next if surface.closed?
+        validate_retention_deadline!(retain_until, future: true)
+        interactions = surface.agent_interactions
+        raise Error.new("LIFECYCLE_BUSY", status: 409) if protected_interactions?(surface, abandon: abandon)
+        if abandon
+          interactions.where(status: %w[pending failed]).update_all(status: "abandoned", claimed_at: nil, error_code: nil, updated_at: Time.current)
+        end
+        now = Time.current
+        surface.update!(closed_at: now, abandoned_at: abandon ? now : nil, retain_until: retain_until, revision: surface.revision + 1)
+      end
+      surface
+    end
+    def protected_interactions?(surface, abandon:)
+      interactions = surface.agent_interactions
+      allowed = abandon ? %w[completed skipped pending failed abandoned] : %w[completed skipped abandoned]
+      interactions.where(delivery_uncertain: true).exists? || interactions.where.not(status: allowed).exists?
+    end
+    def validate_retention_deadline!(deadline, future:)
+      return if deadline.nil?
+      valid_type = deadline.is_a?(Time) || deadline.is_a?(ActiveSupport::TimeWithZone)
+      raise Error.new("INVALID_RETENTION_WINDOW") unless valid_type && (!future || deadline > Time.current)
+    end
+  end
+end

data/lib/rails_tool_views/runtime.rb

@@ -44,6 +44,7 @@ module RailsToolViews
       # match may stand in for this scope's Surface, or a lookup could disclose
       # another actor's or tenant's record.
       raise Error.new("NOT_FOUND", status: 404) unless surface && exact_match?(surface, id: id.to_s, actor_ref: scope.actor, tenant_ref: scope.tenant)
+      ensure_not_purged!(surface)
       component = compatible_component!(surface)
       component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
       surface
@@ -62,6 +63,7 @@ module RailsToolViews
       request_digest = Data.digest(action: definition.key, arguments: arguments, base_revision: base_revision)
       result = nil
       surface.with_lock do
+        ensure_not_purged!(surface)
         compatible_component!(surface).authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
         request = access(scope, :action, surface: surface, props: surface.props, action: definition.key,
           arguments: arguments, context_ref: surface.context_ref)
@@ -74,6 +76,7 @@ module RailsToolViews
           result = prior.result.symbolize_keys
           next
         end
+        raise Error.new("SURFACE_CLOSED", status: 410) if surface.closed?
         raise Error.new("CONFLICT", status: 409) unless surface.revision == base_revision
         if surface.action_executions.where("created_at >= ?", 1.minute.ago).count >= configuration.max_actions_per_minute
           raise Error.new("RATE_LIMITED", status: 429)
@@ -114,25 +117,35 @@ module RailsToolViews
       interaction = AgentInteraction.find_by(id: id)
       raise Error.new("NOT_FOUND", status: 404) unless interaction
       surface = restore(interaction.surface_id, scope: scope)
-      definition = compatible_component!(surface).actions.fetch(interaction.payload.fetch("action")) { raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) }
-      arguments = definition.schema.validate!(interaction.payload.fetch("values"), code: "INVALID_ARGUMENTS")
-      request = access(scope, :action, surface: surface, props: surface.props, action: definition.key, arguments: arguments, context_ref: surface.context_ref)
-      raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
       claimed = false
-      interaction.with_lock do
-        if %w[completed skipped].include?(interaction.status)
-          next
-        end
-        if interaction.status == "delivering" && interaction.claimed_at && interaction.claimed_at > Time.current - configuration.delivery_lease
-          next
-        end
-        next if interaction.status == "failed" && !retry_failed
-        if adapter.nil?
-          interaction.update!(status: "skipped")
-          next
+      # Coordinate the claim with close/abandon/purge, using the same lock order
+      # as actions. Never hold a database transaction during the adapter call.
+      surface.with_lock do
+        ensure_not_purged!(surface)
+        component = compatible_component!(surface)
+        component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        interaction.with_lock do
+          definition = component.actions.fetch(interaction.payload.fetch("action")) { raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) }
+          arguments = definition.schema.validate!(interaction.payload.fetch("values"), code: "INVALID_ARGUMENTS")
+          request = access(scope, :action, surface: surface, props: surface.props, action: definition.key, arguments: arguments, context_ref: surface.context_ref)
+          raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
+          next if %w[completed skipped abandoned].include?(interaction.status)
+          raise Error.new("SURFACE_CLOSED", status: 410) if surface.closed?
+          if interaction.status == "delivering" && interaction.claimed_at && interaction.claimed_at > Time.current - configuration.delivery_lease
+            next
+          end
+          next if interaction.status == "failed" && !retry_failed
+          # Reclaiming a lease does not prove that the previous callback ended.
+          # This durable flag cannot be cleared by a stale worker's completion.
+          uncertain = interaction.delivery_uncertain? || interaction.status == "delivering"
+          if adapter.nil?
+            interaction.update!(status: "skipped", claimed_at: nil, delivery_uncertain: uncertain)
+            next
+          end
+          interaction.update!(status: "delivering", claimed_at: Time.current, attempts: interaction.attempts + 1,
+            error_code: nil, delivery_uncertain: uncertain)
+          claimed = true
         end
-        interaction.update!(status: "delivering", claimed_at: Time.current, attempts: interaction.attempts + 1, error_code: nil)
-        claimed = true
       end
       return interaction.reload unless claimed
       begin
@@ -190,6 +203,9 @@ module RailsToolViews
     end
 
     private
+    def ensure_not_purged!(surface)
+      raise Error.new("SURFACE_PURGED", status: 410) if surface.purged?
+    end
     def check_scope!(scope)
       raise Error.new("INVALID_SCOPE", status: 403) unless scope.is_a?(Scope)
     end

data/lib/rails_tool_views/version.rb

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

data/lib/rails_tool_views.rb

@@ -3,4 +3,5 @@ require_relative "rails_tool_views/core"
 require "rails"
 require "rails/engine"
 require_relative "rails_tool_views/runtime"
+require_relative "rails_tool_views/lifecycle"
 require_relative "rails_tool_views/engine"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_tool_views
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -178,17 +178,27 @@ 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/_closed.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
+- db/migrate/20261019000000_add_rails_tool_views_lifecycle.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/add_rails_tool_views_lifecycle.rb
 - lib/generators/rails_tool_views/install/templates/create_rails_tool_views.rb
 - lib/generators/rails_tool_views/install/templates/rails_tool_views.rb
 - lib/rails_tool_views.rb
 - lib/rails_tool_views/adapters/ruby_llm.rb
 - lib/rails_tool_views/core.rb
 - lib/rails_tool_views/engine.rb
+- lib/rails_tool_views/lifecycle.rb
 - lib/rails_tool_views/runtime.rb
 - lib/rails_tool_views/version.rb
 homepage: https://github.com/yorzi/rails_tool_views