rails_tool_views 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba277c8c403681504a1c5c2d154df3c7814952735ca5a10ba6981f7c50109a2d
+  data.tar.gz: a6ebf8a7b47065ffaf8585d5f57b2aff864d181fe0e7deb0085c26500b640ef4
+SHA512:
+  metadata.gz: 276b0f741dc507376c153e900a0b20468e64cf55f66073be587eb4a0d4705bc0d8a4b2d75b5531382e80011a0bf193510acb143fbe2e6864028881422509e461
+  data.tar.gz: e216675b6918e72cdbaf75a4404e7729bac2186260cbc06a500a8130c7cacaa1312d2e436bcbe085b159534a60adc6c1898673319fd718b456fab32ddd9a8f38

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [0.1.0] - 2026-10-18
+
+First public release. Earlier version labels below describe unpublished development milestones.
+
+- Register trusted Rails Partials and ViewComponents with closed schemas and explicit policies.
+- Persist and restore scoped Surfaces; execute authorized actions with revisions, transactions and durable replay receipts.
+- Render JSON/Turbo responses, accessible action forms and bounded validation feedback.
+- Add optional RubyLLM presentation and durable host-managed continuation without a core AI dependency.
+- Install the engine into Rails 7.2 and 8.1 on Ruby 3.3 or later; one `rails_tool_views` identity throughout.
+- Publish versioned guides and an API reference on GitHub Pages; release gems through GitHub OIDC.
+- Require patched CGI, ERB, Resolv, URI and Zlib gems so Ruby 3.3 default gems cannot silently satisfy the runtime dependencies. Test the Rails 7.2 line on patched 7.2.3.2.
+- MySQL, live-provider behavior, independent security review and external adoption remain unverified.
+
+## 0.3.0.pre.v3 — single identity, 2026-10-18 (unpublished)
+
+Breaking for 0.2 development hosts; see the Upgrading guide and ADR 006.
+
+- Removed: the `ToolViews` constant, the `toolviews`, `tool_views`, `tool_views/core` and `tool_views/adapters/ruby_llm` entrypoints, the `tool_views:install` generator, the `tool_views_*` view helpers and the `:tool_views` route-proxy fallback.
+- Changed: tables and custom indexes use the `rails_tool_views_` prefix; the interaction/execution index has an explicit 44-byte name so it fits PostgreSQL. The install migration is `CreateRailsToolViews` and the initializer `config/initializers/rails_tool_views.rb`.
+- Changed: I18n keys move to `rails_tool_views.*`, notifications to `*.rails_tool_views`, the `Rails.error` source to `rails_tool_views`, Surface DOM ids to `rails_tool_views_surface_<id>`, CSS classes to `rails-tool-views-*`, the Stimulus asset to `rails_tool_views_controller.js` (`railsToolViewsController`, identifier `rails-tool-views`) and delivery keys to `rails_tool_views:interaction:<id>`.
+- Unchanged: component contracts and digests, Surface IDs, revisions, serialized data, error codes and replay behavior.
+
+## Unreleased — audit hardening, 2026-10-17
+
+Fixed: the bundled migration created the five-column presentation unique index with unbounded `varchar` columns, so `CREATE TABLE` failed on MySQL/InnoDB under utf8mb4 (5 x 255 x 4 = 5100 bytes against a 3072-byte limit). Identifiers are now bounded to 150 bytes, so the widest index needs 3000 bytes. Changed: stored actor, tenant, context, adapter, call and idempotency references are byte-capped in `RailsToolViews::Data.identifier`; a longer value is rejected (`INVALID_SCOPE`, `INVALID_CONTEXT`, `INVALID_CORRELATION`, `INVALID_IDEMPOTENCY_KEY`) instead of overflowing a column. Descriptions and versions keep the wider 255-byte cap. Fixed: a non-binary database collation could resolve another actor's or tenant's Surface, another correlation's presentation, or another idempotency key's action receipt; every lookup now confirms a byte-exact match before it stands in for the request. Added regression tests for index-key width, the identifier cap, and collation-safe identity matching. No data migration: existing rows are unchanged and the runtime bound is enforced in code.
+
+## Unreleased — audit hardening and component authoring, 2026-10-13
+
+Fixed: nested schemas that were untyped, empty or arrays without `items` registered successfully and accepted arbitrary JSON inside a closed object; they are now rejected with `INVALID_SCHEMA`. Fixed: a native form for an action without arguments was rejected with `INVALID_ARGUMENTS` because it posts no `arguments` field. Changed: log redaction is scoped to the Engine's controller and models; installing the gem no longer adds `props`, `state`, `payload`, `result`, `arguments` and `values` to the host's `filter_parameters`, which had redacted matching host parameters and columns. Changed: renderer and continuation-adapter exceptions are reported to `Rails.error`, logged, and emitted as `surface.render_failed` / `agent_failed` events instead of being swallowed; `surface.rendered` fires only for a successful render. Added: `message:` on `ToolViews::Error` and `ValidationError`, I18n lookup under `tool_views.errors.*`, and overridable Engine copy under `tool_views.surface.*`. Changed: the status line no longer interprets a `selected` state key; handlers set `state["message"]`. Removed from core: the reference host's `ALREADY_SUBMITTED`, `ALREADY_ACCEPTED` and `REVIEW_REQUIRED` wording, now in its own locale file. No database change.
+
+Added: `tool_views_action_form`, `tool_views_action_button` and `tool_views_action_fields` view helpers. Fixed: Rails' own `form.submit` and `form.button` were rejected as `UNKNOWN_FIELD`; `commit` and `button` are now accepted and ignored. Added: a ViewComponent whose initializer names `surface:`, `state:` or `error:` receives them and can be interactive. Added: `config.parent_controller` and `config.delivery_lease`. Changed: without Turbo, a committed HTML action redirects back to the same-host embedding page instead of the Engine's bare Surface fragment. Changed: a database deadlock, serialization failure or lock timeout returns `CONFLICT` instead of an unhandled error. Verified locally on PostgreSQL 17 (`gemfiles/postgres.gemfile`, `DATABASE_URL`); CI job added, not yet run.
+
+## 0.2.0.pre.v1 — 2026-10-11 (unpublished)
+
+Host-owned customer form, scoped support workflows and versioned result review reference demos (UC-02..05). Add bounded validation feedback with retained form values, authorized HTML error rendering, host ApplicationController inheritance and general action announcements. Demo services independently enforce role/tenant/domain versions, human review before a local outbox, immutable accepted artifacts, authorized export and durable continuation receipts. No new gem database tables or core RubyLLM dependency. Local matrix, packaged install, privacy, recovery and browser evidence: docs/evidence/V1_VALIDATION.md. Manual review and release gates remain open.
+
+## 0.1.0.pre.v0 — 2026-10-10 (unpublished)
+
+Strict registry and trusted Partial/ViewComponent rendering; scoped ActiveRecord Surfaces; atomic authorized actions with revision/replay receipts; JSON/Turbo controller and optional Stimulus focus/loading support; optional RubyLLM present_ui and structured continuation; installer and offline ChoiceCard demo. Local integration/security/concurrency/package/browser verification is recorded in docs/evidence/VALIDATION.md. Release and adoption gates remain open.
+
+## Unreleased — first host integration fixes (2026-10-17)
+
+- Fix: without Turbo and without a same-host referrer, a committed HTML action redirected through a hard-coded `tool_views` route proxy. Under the installer's `rails_tool_views` mount it raised `NameError` (500). It now uses the Engine's own route helper and keeps any mount path and name.
+- Add: `rails_tool_views_component_name` / `tool_views_component_name`. The Surface's accessible name is looked up under `tool_views.components.<key>` on every render and falls back to the registered description.
+- Docs: renderers and parent-controller filters run inside the Engine's controller and call host routes through `main_app`.
+- No database change.
+
+## Unreleased — RailsToolViews identity (2026-10-16)
+
+- Rename the package to `rails_tool_views` and the canonical namespace to `RailsToolViews`.
+- Preserve legacy Ruby requires/constants/helpers/mounts, database and wire identifiers.
+- Add independent packaged-host and pre-rename persisted-data compatibility verification. No RubyGems release.

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,90 @@
+# RailsToolViews
+
+**Turn trusted Rails views into persistent, interactive tools.**
+
+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.
+
+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.
+
+[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"
+```
+
+```sh
+bundle install
+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) %>
+```
+
+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.
+
+## 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
+
+```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
+```
+
+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.
+
+## Project status and attribution
+
+Released under the [MIT license](LICENSE.txt).
+
+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).

data/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+The 0.1.x release line receives security fixes. This project has not received independent security review. Report suspected vulnerabilities through [GitHub private vulnerability reporting](https://github.com/yorzi/rails_tool_views/security/advisories/new). Do not post secrets, customer data, raw payloads or exploit instructions in a public issue. The maintainer reviews reports on a best-effort basis; no response-time guarantee is offered.
+
+The host must resolve actor and tenant from authenticated server state, provide deny-by-default component/action policies, authorize domain records independently of props, keep CSRF enabled and project data before persistence. RailsToolViews rejects unregistered renderers/actions, extra parameters, client policy text, forged sources/targets, stale revisions and mismatched replays. The only extra parameters tolerated are `commit` and `button`, which Rails' submit helpers post; their values are never read. The non-Turbo redirect after a committed action follows `Referer` only to the same host. Native escaping depends on trusted host templates. Registration rejects any nested schema that is untyped, empty, open or an array without `items`, so a closed props or arguments object cannot be reopened from the inside. Engine-scoped request and SQL bind redaction and metadata-only notifications reduce logging exposure without altering host logs; host SQL/SDK logging and retention still need review.
+
+The gem stores approved display props/state and structured interaction values. It does not store transcripts, API credentials or raw business-record dumps by itself. Hosts control export/deletion and must not place sensitive data into these fields. Database handlers share Surface's transaction; external calls require host idempotency/outbox. Agent deliveries use a lease and stable delivery key, with explicit retry; a host must deduplicate across uncertain remote outcomes.
+
+Supported transports are JSON and Turbo. ActionCable is absent. No executable model-generated HTML, JS, Ruby, arbitrary remote schema resolution or URL fetch is supported. Security coverage maps SEC-01..18 in the acceptance matrix; channel-specific checks remain N/A while broadcasting is disabled.
+
+Mounted controllers inherit the host's ApplicationController; review inherited authentication filters and helpers. ValidationError returns bounded approved field feedback, so handlers must avoid returning private values. Engine request logs mask every field except routing metadata, and Engine models redact their JSON columns in SQL binds and `#inspect`; custom host attributes/SDK logs require separate review. Renderer and adapter exceptions are host exceptions: they are passed to `Rails.error` and logged with class and message, so host code must not put secrets in exception messages. V1 query/resolver/dispatcher independently authorize current role, tenant and associations, and compare host versions across Surfaces. The synthetic identity selector and local reply outbox are reference fixtures, not production authentication or external delivery.

data/app/assets/javascripts/rails_tool_views_controller.js

@@ -0,0 +1,41 @@
+// Host imports and registers this factory with its own Stimulus application.
+// No provider, generated code, or browser-owned policy participates in actions.
+export default function railsToolViewsController(Controller) {
+  return class extends Controller {
+    static targets = ["status", "error"];
+    // The server-rendered Surface supplies translated copy; these are fallbacks.
+    static values = {
+      revision: Number,
+      saving: { type: String, default: "Saving changes…" },
+      failed: { type: String, default: "Changes could not be saved. Review the message and try again." }
+    };
+    connect() {
+      this.start = () => {
+        this.element.setAttribute("aria-busy", "true");
+        if (this.hasStatusTarget) this.statusTarget.textContent = this.savingValue;
+      };
+      this.end = (event) => {
+        this.element.removeAttribute("aria-busy");
+        if (!event.detail.success && this.hasStatusTarget) this.statusTarget.textContent = this.failedValue;
+      };
+      this.beforeStream = (event) => {
+        const stream = event.target;
+        if (stream.getAttribute("target") !== this.element.id) return;
+        const incoming = stream.querySelector("template")?.content.firstElementChild;
+        const revision = Number(incoming?.getAttribute("data-rails-tool-views-revision-value"));
+        if (revision && revision < this.revisionValue) event.preventDefault();
+      };
+      this.element.ownerDocument.addEventListener("turbo:before-stream-render", this.beforeStream);
+      this.element.addEventListener("turbo:submit-start", this.start);
+      this.element.addEventListener("turbo:submit-end", this.end);
+      // Replacement happens after a committed result; move focus to its announcement.
+      if (this.hasErrorTarget) this.errorTarget.focus({ preventScroll: true });
+      else if (this.revisionValue > 1 && this.hasStatusTarget) this.statusTarget.focus({ preventScroll: true });
+    }
+    disconnect() {
+      this.element.ownerDocument.removeEventListener("turbo:before-stream-render", this.beforeStream);
+      this.element.removeEventListener("turbo:submit-start", this.start);
+      this.element.removeEventListener("turbo:submit-end", this.end);
+    }
+  };
+}

data/app/controllers/rails_tool_views/surfaces_controller.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # Preserve the host's authentication methods, filters and view helpers.
+  class SurfacesController < RailsToolViews.parent_controller
+    # Request logs for these routes keep routing metadata only. Everything else,
+    # including unknown injected fields, is masked here rather than in the host's
+    # global filter list, which would also redact the host's own parameters.
+    LOGGED_PARAMETERS = %w[controller action id interaction_id format action_name base_revision idempotency_key source_component target].freeze
+    UNLOGGED_PARAMETER = /\A(?!(?:#{LOGGED_PARAMETERS.join('|')})\z)/
+    # Rails' own form and submit helpers post these names; their values are never read.
+    FORM_FURNITURE = %w[authenticity_token commit button].freeze
+
+    protect_from_forgery with: :exception
+    wrap_parameters false
+    before_action :limit_payload
+    helper RailsToolViews::SurfacesHelper
+    rescue_from RailsToolViews::Error, with: :reject_request
+    rescue_from ActionController::InvalidAuthenticityToken do
+      reject_request(Error.new("INVALID_CSRF", status: 403))
+    end
+
+    def show
+      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) }
+      end
+    end
+
+    def act
+      reject_unknown_fields(%w[action action_name arguments base_revision idempotency_key source_component target])
+      result = RailsToolViews.dispatch(params[:id], scope: current_scope, action: input["action"] || input["action_name"],
+        # A native form for an action without arguments cannot post an empty object.
+        arguments: input.fetch("arguments", {}),
+        base_revision: parse_revision(input["base_revision"]), idempotency_key: input["idempotency_key"],
+        source_component: input["source_component"], target: input["target"])
+      if result[:interaction_id] && RailsToolViews.configuration.agent_adapter && RailsToolViews.configuration.auto_deliver
+        RailsToolViews.deliver(result[:interaction_id], scope: current_scope)
+      end
+      respond_with_surface(result)
+    end
+
+    def retry_agent
+      reject_unknown_fields(%w[])
+      surface = RailsToolViews.restore(params[:id], scope: current_scope)
+      interaction = surface.agent_interactions.find_by(id: params[:interaction_id])
+      raise Error.new("NOT_FOUND", status: 404) unless interaction
+      RailsToolViews.deliver(interaction.id, scope: current_scope, retry_failed: true)
+      respond_with_surface(status: "completed", surface_id: surface.id, revision: surface.revision, interaction_id: interaction.id)
+    end
+
+    private
+    # Runs before Rails reads the filtered parameters for its request log.
+    def process_action(*)
+      request.set_header("action_dispatch.parameter_filter", Array(request.get_header("action_dispatch.parameter_filter")) + [UNLOGGED_PARAMETER])
+      super
+    end
+    def current_scope
+      @current_scope ||= RailsToolViews.configuration.scope_resolver&.call(self)
+      raise Error.new("NOT_ALLOWED", status: 403) unless @current_scope.is_a?(Scope)
+      @current_scope
+    end
+    def limit_payload
+      raise Error.new("PAYLOAD_TOO_LARGE", status: 413) if request.content_length.to_i > RailsToolViews.configuration.max_payload_bytes || request.raw_post.to_s.bytesize > RailsToolViews.configuration.max_payload_bytes
+    end
+    def reject_unknown_fields(allowed)
+      extra = input.keys - allowed - FORM_FURNITURE
+      raise Error.new("UNKNOWN_FIELD") unless extra.empty?
+      raise Error.new("UNKNOWN_FIELD") if input.key?("action") && input.key?("action_name")
+    end
+    def input
+      @input ||= Data.bounded(request.request_parameters)
+    end
+    def parse_revision(value)
+      return value if value.is_a?(Integer)
+      raise Error.new("INVALID_REVISION") unless value.is_a?(String) && value.match?(/\A[1-9][0-9]{0,9}\z/)
+      value.to_i
+    end
+    def respond_with_surface(result)
+      surface = RailsToolViews.restore(result[:surface_id], scope: current_scope)
+      interaction = result[:interaction_id] && surface.agent_interactions.find_by(id: result[:interaction_id])
+      response = result.merge(current_revision: surface.revision)
+      response[:agent_status] = interaction.status if interaction
+      response[:status] = "pending" if interaction && %w[pending delivering].include?(interaction.status)
+      status = response[:status] == "pending" ? 202 : 200
+      respond_to do |format|
+        format.json { render json: response, status: status }
+        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 }
+      end
+    end
+    def reject_request(error)
+      respond_to do |format|
+        format.json { render json: error.to_h, status: error.status }
+        format.turbo_stream do
+          # Failed authorization never renders props, and supplied targets never reach Turbo.
+          begin
+            surface = RailsToolViews.restore(params[:id], scope: current_scope)
+            html = RailsToolViews.render(surface, view_context: view_context, scope: current_scope, error: error)
+            render turbo_stream: turbo_stream.replace(surface.dom_id, html), status: error.status
+          rescue RailsToolViews::Error
+            render plain: error.message, status: error.status
+          end
+        end
+        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
+          rescue RailsToolViews::Error
+            render partial: "rails_tool_views/surfaces/error", locals: { error: error }, status: error.status
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/rails_tool_views/surfaces_helper.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # Rails view helpers for authorized rendering and action forms.
+  module SurfacesHelper
+    # Engine-owned copy. Translate or reword any of it under rails_tool_views.surface.<key>.
+    TEXT = {
+      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.",
+      agent_failed: "Your changes were saved, but the AI follow-up could not complete.",
+      agent_unavailable: "AI follow-up unavailable.", agent_retry: "Retry AI follow-up"
+    }.freeze
+
+    # Renders the Surface with a fresh scope and optional field feedback.
+    def rails_tool_views_surface(surface, scope:, error: nil)
+      RailsToolViews.render(surface, view_context: self, scope: scope, error: error)
+    end
+
+    def rails_tool_views_text(key, **values)
+      t(key, scope: %i[rails_tool_views surface], default: TEXT.fetch(key), **values)
+    end
+
+    # The accessible name of a registered component: the translation under
+    # rails_tool_views.components.<key>, or its registered description. Looked up
+    # per render, so it follows the request's locale.
+    def rails_tool_views_component_name(key)
+      t(key.to_s, scope: %i[rails_tool_views components], default: RailsToolViews.registry.fetch(key).description)
+    end
+
+    # Form for one registered action of this Surface. Fields built from the
+    # yielded builder are named +arguments[...]+, ids are unique per Surface, and
+    # the action, revision, replay key and source fields are filled in.
+    def rails_tool_views_action_form(surface, action, **options, &block)
+      fields = rails_tool_views_action_fields(surface, action)
+      form_with(url: rails_tool_views_routes.surface_actions_path(surface), method: :post, scope: :arguments, namespace: surface.dom_id, **options) do |form|
+        safe_join([fields, (capture(form, &block) if block)])
+      end
+    end
+
+    # One-button form for an action whose arguments, if any, are fixed.
+    def rails_tool_views_action_button(surface, action, label, arguments: {}, form: {}, **button)
+      rails_tool_views_action_form(surface, action, **form) do |builder|
+        safe_join(arguments.map { |name, value| builder.hidden_field(name, value: value, id: nil) } << builder.button(label, name: nil, **button))
+      end
+    end
+
+    # The routing fields alone, for a form the host builds itself.
+    def rails_tool_views_action_fields(surface, action)
+      key = action.to_s
+      unless RailsToolViews.registry.fetch(surface.component_key).actions.key?(key)
+        raise ArgumentError, "#{surface.component_key} does not register the action #{key.inspect}"
+      end
+      safe_join({ action_name: key, base_revision: surface.revision, idempotency_key: SecureRandom.uuid, source_component: surface.component_key }
+        .map { |name, value| hidden_field_tag(name, value, id: nil) })
+    end
+
+    def rails_tool_views_body(surface, definition, error: nil) # :nodoc:
+      html = if definition.partial
+        render(partial: definition.partial, locals: { props: surface.props, state: surface.state, surface: surface, error: error })
+      else
+        context = { surface: surface, state: surface.state, error: error }.slice(*definition.context)
+        render(definition.component.new(**surface.props.symbolize_keys, **context))
+      end
+      RailsToolViews.notify("surface.rendered", surface_id: surface.id, component: definition.key, revision: surface.revision)
+      html
+    rescue StandardError => failure
+      # A host renderer may reject deliberately; anything else is a host bug to report.
+      rejection = [failure, failure.cause].find { |candidate| candidate.is_a?(RailsToolViews::Error) }
+      RailsToolViews.report(failure, "surface.render_failed", surface_id: surface.id, component: definition.key) unless rejection
+      render(partial: "rails_tool_views/surfaces/error", formats: [:html], locals: { error: rejection || RailsToolViews::Error.new("RENDER_FAILED", status: 422) })
+    end
+
+    def rails_tool_views_routes # :nodoc:
+      view = respond_to?(:rails_tool_views) || respond_to?(:main_app) ? self : helpers
+      view.respond_to?(:rails_tool_views) ? view.rails_tool_views : view.main_app.rails_tool_views
+    end
+  end
+end

data/app/models/rails_tool_views/action_execution.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # A committed action receipt used to replay requests without repeating handlers.
+  class ActionExecution < ActiveRecord::Base
+    self.table_name = "rails_tool_views_action_executions"
+    belongs_to :surface
+    has_one :agent_interaction, dependent: :destroy
+    self.filter_attributes += %i[result]
+    attribute :result, RedactedJson.new
+  end
+end

data/app/models/rails_tool_views/agent_interaction.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # A durable continuation request delivered after its action commits.
+  class AgentInteraction < ActiveRecord::Base
+    self.table_name = "rails_tool_views_agent_interactions"
+    belongs_to :surface
+    belongs_to :action_execution
+    self.filter_attributes += %i[payload]
+    attribute :payload, RedactedJson.new
+    # Returns the stable host deduplication key across delivery retries.
+    def delivery_key
+      "rails_tool_views:interaction:#{id}"
+    end
+  end
+end

data/app/models/rails_tool_views/presentation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # A durable acknowledgment correlating one scoped tool call with a Surface.
+  class Presentation < ActiveRecord::Base
+    self.table_name = "rails_tool_views_presentations"
+    belongs_to :surface
+    self.filter_attributes += %i[result]
+    attribute :result, RedactedJson.new
+  end
+end

data/app/models/rails_tool_views/redacted_json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # JSON column type whose database bind hides itself from SQL logs. Rails
+  # filters binds by attribute name alone, so listing `state` or `result` in the
+  # host-wide filter would also redact every host column that shares the name.
+  class RedactedJson < ActiveRecord::Type::Json
+    class Bind < String
+      def inspect
+        "[FILTERED]"
+      end
+      def as_json(*)
+        "[FILTERED]"
+      end
+    end
+    def serialize(value)
+      json = super
+      json && Bind.new(json)
+    end
+  end
+end

data/app/models/rails_tool_views/surface.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module RailsToolViews
+  # A persisted UI snapshot whose read and action access is checked by RailsToolViews.
+  class Surface < ActiveRecord::Base
+    self.table_name = "rails_tool_views_surfaces"
+    self.filter_attributes += %i[props state]
+    attribute :props, RedactedJson.new, default: -> { {} }
+    attribute :state, RedactedJson.new, default: -> { {} }
+    has_many :presentations, dependent: :destroy
+    has_many :action_executions, dependent: :destroy
+    has_many :agent_interactions, dependent: :destroy
+    before_create { self.id ||= SecureRandom.uuid }
+    validates :actor_ref, :tenant_ref, :component_key, :component_digest, presence: true
+    # Returns the stable browser target identifier.
+    def dom_id
+      "rails_tool_views_surface_#{id}"
+    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 }
+    end
+  end
+end

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

@@ -0,0 +1 @@
+<div class="rails-tool-views-error" role="alert" tabindex="-1" data-error-code="<%= error.code %>"><%= error.message %></div>

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

@@ -0,0 +1,19 @@
+<section id="<%= surface.dom_id %>" class="rails-tool-views-surface" data-controller="rails-tool-views" data-rails-tool-views-revision-value="<%= surface.revision %>" data-rails-tool-views-saving-value="<%= rails_tool_views_text(:saving) %>" data-rails-tool-views-failed-value="<%= rails_tool_views_text(:save_failed) %>" aria-label="<%= rails_tool_views_component_name(definition.key) %>" aria-describedby="<%= surface.dom_id %>_status">
+  <%= rails_tool_views_body(surface, definition, error: error) %>
+  <% if error %>
+    <p id="<%= surface.dom_id %>_error" role="alert" tabindex="-1" data-rails-tool-views-target="error"><%= error.message %></p>
+  <% end %>
+  <p id="<%= surface.dom_id %>_status" role="status" aria-live="polite" tabindex="-1" data-rails-tool-views-target="status">
+    <%= surface.state["message"].is_a?(String) ? surface.state["message"] : rails_tool_views_text(surface.revision > 1 ? :saved : :ready) %>
+  </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>
+    <% 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>
+      <% end %>
+    <% end %>
+  <% end %>
+  <p class="rails-tool-views-revision"><%= rails_tool_views_text(:revision, revision: surface.revision) %></p>
+</section>

data/config/routes.rb

@@ -0,0 +1,5 @@
+RailsToolViews::Engine.routes.draw do
+  get "surfaces/:id", to: "surfaces#show", as: :surface
+  post "surfaces/:id/actions", to: "surfaces#act", as: :surface_actions
+  post "surfaces/:id/continuations/:interaction_id", to: "surfaces#retry_agent", as: :surface_continuation
+end

data/db/migrate/20261010000000_create_rails_tool_views.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+class CreateRailsToolViews < ActiveRecord::Migration[7.2]
+  # Identifier columns are bounded to 150 bytes in RailsToolViews::Data, and the
+  # value is stored in a byte-limited column. This keeps every index key within
+  # utf8mb4's 3072-byte limit on MySQL/InnoDB: the widest index is the five
+  # presentation columns below (5 * 150 * 4 = 3000 bytes).
+  def change
+    create_table :rails_tool_views_surfaces, id: :string do |t|
+      t.string :actor_ref, null: false, limit: 150
+      t.string :tenant_ref, null: false, limit: 150
+      t.string :context_ref, limit: 150
+      t.string :component_key, null: false
+      t.string :component_digest, null: false
+      t.integer :contract_version, default: 1, null: false
+      t.json :props, null: false
+      t.json :state, null: false
+      t.integer :revision, default: 1, null: false
+      t.integer :lock_version, default: 0, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref]
+    create_table :rails_tool_views_presentations do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.string :actor_ref, null: false, limit: 150
+      t.string :tenant_ref, null: false, limit: 150
+      t.string :adapter, null: false, limit: 150
+      t.string :call_id, null: false, limit: 150
+      t.string :context_ref, null: false, limit: 150
+      t.string :request_digest, null: false
+      t.json :result, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_presentations, [:tenant_ref, :actor_ref, :adapter, :call_id, :context_ref], unique: true, name: "index_rails_tool_views_call_scope"
+    create_table :rails_tool_views_action_executions do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.string :actor_ref, null: false, limit: 150
+      t.string :action_key, null: false
+      t.string :idempotency_key, null: false, limit: 150
+      t.string :request_digest, null: false
+      t.integer :base_revision, null: false
+      t.json :result, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_action_executions, [:surface_id, :idempotency_key], unique: true, name: "index_rails_tool_views_action_replay"
+    create_table :rails_tool_views_agent_interactions do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.references :action_execution, foreign_key: { to_table: :rails_tool_views_action_executions }, null: false, index: { unique: true, name: "index_rails_tool_views_interaction_execution" }
+      t.json :payload, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :error_code
+      t.datetime :claimed_at
+      t.integer :attempts, null: false, default: 0
+      t.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+require "rails/generators"
+require "rails/generators/migration"
+module RailsToolViews
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        [Time.now.utc.strftime("%Y%m%d%H%M%S"), format("%014d", next_migration_number)].max
+      end
+      def install
+        migration_template "create_rails_tool_views.rb", "db/migrate/create_rails_tool_views.rb"
+        template "rails_tool_views.rb", "config/initializers/rails_tool_views.rb"
+        route 'mount RailsToolViews::Engine => "/rails_tool_views", as: :rails_tool_views'
+      end
+    end
+  end
+end