testimonials 0.7.9 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 746c0b7bc1421a8aadfbbbd7e9d41cb4aabc81ff0c6afa60669e4d9c06e963b0
-  data.tar.gz: 3914ba53cef25fcb6f541e6b4176e1d6135205cb37cdcc05b289125d456f1bbb
+  metadata.gz: 1472a2172dce3259de44e1af6de8a7c6466d0589a6afeb037900cb154b08e5b9
+  data.tar.gz: a928753201311457628c7e38adf8164227d329d5bb753395a267c916dbdeaa08
 SHA512:
-  metadata.gz: 55f8694212e3f1395481121efd0f67c8474e9422173ba63e9b05cf66f40320b340301a1be39537cfbeb8ce17292b289d4f73247b2a05742e52f79b1bad6d47ae
-  data.tar.gz: 1a57a1aa934adc3d3b92199d922effc5ec36d66dc9138f819b1b153f754431c5e5bd7bea4f21e65fe51bb725d732e648acf7f389f8168ac277f174e220130b19
+  metadata.gz: 0c312e4bdff8a87463bbcbdd842a4bbe711ac2557ead095ce86f70918f70eba937ec08f00a6477c969ed1bcbfa1f6ca654c31c414c040b40fa64852f14a250d8
+  data.tar.gz: 272c88fc2b1bad4baf46849be45c2b5b9c6e2ce969cd2f0285c7cd04121e805e716026c17d4c9b8312792e85a5b35f3ad8c6d43de6876774f412c99cfe479cbf

data/AGENTS.md

@@ -0,0 +1,210 @@
+# AGENTS.md
+
+Instructions for coding agents. Two audiences:
+
+- **[Installing testimonials into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add testimonials, reviews, or NPS.
+- **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
+
+Requirements: Ruby >= 3.2, Rails >= 7.1. Active Storage only for video and avatar uploads.
+
+If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show testimonials)/AGENTS.md"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Decide two things first — they are install-time flags
+
+Both features can be added later, but skipping them now means smaller schema and less code reaching the database. Ask the user only if the answer isn't already obvious from their request.
+
+| Question | If no |
+| --- | --- |
+| Do they want NPS (the 0–10 "how likely are you to recommend" survey)? | `--skip-nps` |
+| Should the widget ever **open itself** — `testimonial_prompt!` at a success moment — rather than only on a click? | `--skip-prompt-events` |
+
+Default to a full install when unsure. "Just let users leave reviews from a button in the menu" is the common case for `--skip-prompt-events`.
+
+### 2. Install
+
+```bash
+bundle add testimonials
+bin/rails generate testimonials:install    # + any --skip-* flags from step 1
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/testimonials.rb`, one migration, and `mount_testimonials at: "/testimonials"` into `config/routes.rb`. Read the initializer it wrote — every option is documented there in comments, and it is the source of truth over any summary of it, including this file.
+
+Every `config.…` line below belongs inside the `Testimonials.configure do |config|` block in that initializer. Uncomment and edit in place rather than appending a second `configure` block.
+
+### 3. Wire the three things the generator cannot
+
+**a. The widget tag.** Nothing renders until this is on the page:
+
+```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
+<%= testimonials_tag %>
+```
+
+The helper is injected into ActionView by the engine — no include, no import, no asset pipeline entry. It renders nothing until the widget is opened, and it must be present on any page where the widget can open.
+
+**b. `authorize_admin` — do this before deploying.** The dashboard at `/testimonials` defaults to **development only**. It fails closed, so shipping without this is not an open door — it is a 403 telling you to set it.
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+**c. Attribution**, if the app has users. Optional, but without it every submission is a guest.
+
+```ruby
+config.current_user = ->(request) { request.env["warden"]&.user }   # Devise/Warden
+config.user_display = ->(user) { { name: user.name, email: user.email } }
+```
+
+> **Every gate receives the raw `request`, not a controller.** `current_user`, `authorize_admin`, `enabled` and `tenant` are lambdas over `ActionDispatch::Request`. Writing `->(request) { current_user }` is the single most common mistake here — that method does not exist in this scope. Resolve the user *from the request*: Warden env, a signed cookie, `Current.user` if the app sets it in a middleware/`before_action` that has already run.
+
+Rails 8 built-in auth:
+
+```ruby
+config.current_user = lambda do |request|
+  token = request.cookies["session_token"]
+  Session.find_signed(token)&.user if token
+end
+```
+
+### 4. Verify
+
+```bash
+bin/rails routes | grep testimonials     # engine mounted
+bin/rails testimonials:seed_demo         # optional sample data, idempotent
+```
+
+Then, in the running app: load any page and confirm `data-testimonials-config` appears in the HTML source, and that `/testimonials` renders the dashboard in development. The widget stays invisible until opened — an empty-looking page is correct.
+
+### Opening the widget
+
+| Way | Code | Throttled? |
+| --- | --- | --- |
+| Your own button | `<%= testimonials_button %>`, or any element with `data-testimonial-prompt` (`="nps"` for NPS) | No |
+| JavaScript | `window.Testimonials.open()` / `window.Testimonials.openNps()` | No |
+| From a controller, at a success moment | `testimonial_prompt!` / `testimonial_prompt!(:nps)` | Yes |
+
+`testimonial_prompt!` is available in every controller (the engine includes it). It sets a flash and the widget auto-opens on the next rendered page **if** the throttle allows — already submitted, recently dismissed, or prompted `max_prompts` times means it stays shut. Call it liberally; that is the design.
+
+```ruby
+def create
+  # ...
+  testimonial_prompt! if current_user.invoices.count == 10
+  redirect_to invoices_path
+end
+```
+
+**On a `--skip-prompt-events` install `testimonial_prompt!` is a no-op** — with no history there is nothing to throttle with, and a prompt nothing can throttle would reopen on every page. Use an explicit opener instead, or add the ledger (see below).
+
+### Rendering what was collected
+
+The gem ships **no display UI** on purpose, and its own views are for the dashboard and the public pages only. Render approved testimonials with the host app's own markup:
+
+```ruby
+Testimonials::Testimonial.publishable.featured_first.limit(6)   # approved + publicly consented
+Testimonials::Testimonial.publishable.for_tenant(key)           # multi-tenant
+Testimonials::NpsResponse.score                                 # −100..100
+```
+
+`examples/` in the gem has copy-paste starting points: `wall_of_love.html.erb`, `testimonial_card.html.erb`, `badge.html.erb`, `json_ld.html.erb` (schema.org), `static_site.md`. Prefer adapting one over inventing a layout.
+
+There is also a read API — `GET /testimonials/api/testimonials` (filters: `featured=1`, `min_rating=4`, `kind=video`, `limit=12`) and `GET /testimonials/api/stats`. Admin-only unless `config.public_api = true`. Emails and author ids are never serialized.
+
+### Adding a skipped feature later
+
+Order matters: **migrate first, then flip the flag.** The flag is what the code checks, so setting it before the table exists is the one broken state.
+
+```bash
+bin/rails generate testimonials:nps            # then db:migrate, then config.nps = true
+bin/rails generate testimonials:prompt_events  # then db:migrate, then config.prompt_events = true
+```
+
+Both land on exactly the schema a full install produces, tenant column and indexes included.
+
+### Multi-tenancy
+
+One resolver returning an **opaque key** — GlobalID, id, subdomain, slug. The gem never takes a foreign key into host models:
+
+```ruby
+config.tenant = ->(request) { Current.organization&.to_gid&.to_s }
+```
+
+Optional sugar on a host model (`has_testimonials` is available on every Active Record class already):
+
+```ruby
+class Organization < ApplicationRecord
+  has_testimonials   # keyed by to_gid.to_s — must match config.tenant
+end
+organization.testimonials.approved
+```
+
+`bin/rails generate testimonials:tenant` exists **only** to add the `tenant` column to installs made before it existed. A fresh install already has it, and running that generator will fail on a duplicate column. Do not run it as part of a new install.
+
+### Do not
+
+- **Do not hand-write the migration or the initializer.** Use the generators; the templates track the schema.
+- **Do not copy `widget.js` into `app/javascript`, or add a `<script>` tag for it.** `testimonials_tag` renders both tags itself, and the engine serves the code at `/testimonials/widget.js` with a content fingerprint. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
+- **Do not edit views inside the gem.** To put the dashboard inside an existing admin, set `config.base_controller_class = "Admin::BaseController"` (it inherits that controller's layout, helpers, authentication and request context) or, for the shell alone, `config.admin_layout = "admin/application"`. The dashboard's stylesheet and script are declared by its views, so both work with nothing else wired up.
+- **Do not check whether a table exists to decide if a feature is on.** `Testimonials.config.nps` and `Testimonials.config.prompt_events` are the source of truth, deliberately — nothing in the gem introspects the schema at runtime.
+- **Do not set config outside the initializer.** `rate_limit` in particular is read once when the controller class loads; assigning config in a controller or per-request is a global mutation across the process.
+- **Do not add `testimonials_tag` more than once per page,** and do not put it in a partial that some pages skip while still calling `testimonial_prompt!` — the prompt is consumed from the flash by whatever renders next.
+
+### Configuration worth knowing
+
+Everything is optional; a fresh install works with zero config. Full list with comments is in the generated initializer.
+
+| Option | Default | Note |
+| --- | --- | --- |
+| `authorize_admin` | development only | **Set before deploying.** |
+| `current_user`, `user_display`, `tenant`, `enabled` | no-ops | Lambdas over the raw request. |
+| `nps` | `true` | `false` = no prompt, no public NPS page, no dashboard tab, no `nps_score`. |
+| `prompt_events` | `true` | `false` = no prompt history, and therefore no auto-prompts at all. |
+| `base_controller_class` | `ActionController::Base` | Controller the DASHBOARD inherits. Public endpoints never do, so an admin base controller here cannot gate the widget. |
+| `reprompt_after`, `max_prompts` | `90.days`, `3` | Throttle for auto-prompts only. |
+| `video`, `avatars` | `true` | Need Active Storage; they self-disable when it isn't loaded. |
+| `public_collection` | `true` | `/testimonials/new` and `/testimonials/nps/new`. Shareable links. |
+| `public_api` | `false` | Serves the read API without auth, CORS `*`. |
+| `on_submit`, `on_detractor` | no-ops | Run inline after save — keep fast or enqueue a job. |
+| `mount_path` | `"/testimonials"` | Must match `mount_testimonials at:` in routes. |
+| `rate_limit` | `{ to: 5, within: 60 }` | Rails 7.2+; ignored on 7.1. `nil` disables. |
+
+Turbo Drive and nonce-based CSP work out of the box; the widget config rides in a `type="application/json"` block (data, not code) and the code is a same-origin `src` script. 26 locales ship with the gem, including localized guiding questions.
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| `/testimonials` returns 403 "Set Testimonials.config.authorize_admin to grant access" | Exactly what it says: still at the development-only default. |
+| Widget never appears | `testimonials_tag` missing from the rendered layout, or `config.enabled` returning false. |
+| `testimonial_prompt!` never opens anything | `config.prompt_events` is false, or the user is throttled (submitted / dismissed recently / hit `max_prompts`). |
+| `no such table: testimonials_nps_responses` (or `..._prompt_events`) | A flag was flipped to `true` before running the matching generator and `db:migrate`. |
+| `/testimonials/nps_responses` 404s | `config.nps` is false. The rows are still there; flip it back to read them. |
+| Video recording missing | Active Storage not installed, or `config.video = false`. |
+| `NameError` for a host helper in the dashboard | `isolate_namespace` scopes `helper` to the engine. Use `config.base_controller_class` so the dashboard inherits your helpers, rather than `admin_layout` alone. |
+| `NotNullViolation` attaching a video on a uuid-keyed app | The tables were generated bigint. Set `config.generators` `primary_key_type` before installing, or migrate the tables to uuid. |
+| `undefined local variable current_user` in the initializer | A gate lambda treated its argument as a controller. It is a `request`. |
+
+---
+
+## Working on the gem itself
+
+```bash
+bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rubocop             # must be clean
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
+```
+
+Layout: `app/` controllers, models, dashboard views · `lib/testimonials/` config, widget JS/CSS, seeds, engine · `lib/generators/testimonials/` install, nps, prompt_events, tenant · `config/locales/` 26 locales · `test/` minitest, `test/dummy` the host app · `examples/` display snippets for hosts.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Optional features are guarded by a config flag, never by schema introspection.** `--skip-nps` and `--skip-prompt-events` leave tables out; nothing may ask the database whether a table exists, and nothing may touch the database at boot. Guard at the entry points (one `before_action`, one model class method) so the flag is checked once, not at six call sites.
+- **Every install shape gets a test that drops the table for real** (`test/integration/skip_nps_test.rb`, `skip_prompt_events_test.rb`), so a slipped guard raises `no such table` instead of passing quietly. Generator tests pin each migration and initializer shape and check the ERB still compiles as Ruby.
+- **The widget is plain ES5-style JS in `lib/testimonials/widget.js`**, served by the engine, no build step, no framework. It reads its config from a JSON block on every `turbo:load`.
+- **Display stays headless.** New display UI belongs in `examples/`, not in `app/views`.
+- Every user-facing change bumps `lib/testimonials/version.rb` and adds a `CHANGELOG.md` entry that says what it costs, not only what it adds.
+- Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.8.0
+
+- **`config.admin_layout` now works on its own.** The dashboard's stylesheet and
+  script were declared in the gem's layout, so replacing that layout dropped
+  both: the dashboard rendered unstyled with its delete confirmations and
+  auto-submitting filter dead. They move into the views (a shared
+  `testimonials/shared/_dashboard` partial), so every layout gets them with
+  nothing asked of the host.
+- **The dashboard stylesheet no longer claims selectors it does not own.** It
+  styled bare `body`, `a`, `table` and `*`, and its `.card`, `.badge`, `.tabs`
+  and `.container` are names Bootstrap and daisyUI use too, so a host that did
+  load it had its sidebar and topbar restyled. Component rules now nest inside a
+  `.tml-dashboard` wrapper the views render, every custom property is `--tml-`
+  prefixed, and `.container`/`.nav` became `.tml-page`/`.tml-nav`. The
+  full-viewport rules stay keyed to the `tm-index`/`tm-nps-index`/`tm-show` body
+  classes that only the gem's own layout sets, so inside a host admin the
+  dashboard scrolls with the host's page instead of fighting it for the
+  viewport. Two tests fail the build if a selector or property escapes again.
+- **Added `config.base_controller_class`.** Name the controller your own admin
+  inherits from and the dashboard adopts its layout, helpers, authentication and
+  request context — the things `admin_layout` cannot give you, and which hosts
+  were hand-wiring as a shim layout plus a concern to populate `Current`. Same
+  hook pgbus, avo and mission_control-jobs use. Default is unchanged.
+  Layout precedence with it: a host base controller keeps its own layout, unless the host also named an `admin_layout` explicitly.
+- **Migrations follow the host's `primary_key_type`,** the same
+  `Rails.configuration.generators` lookup Rails' own Active Storage, Action Text
+  and Action Mailbox migrations do. A uuid-keyed app has a uuid
+  `active_storage_attachments.record_id`, so bigint tables here could never hold
+  a video or avatar — `attach` raised `NotNullViolation`. A host that set
+  nothing gets no `id:` option and an identical migration to before.
+- **Dropped the `id: /\d+/` route constraints,** which were what forced the
+  tables to be bigint in the first place: uuid tables would have 404d show,
+  update, destroy and all three media routes. The constraint was never
+  load-bearing, since every fixed-name route is declared before the flat
+  `/:id` routes.
+- **`create` moved to `Testimonials::SubmissionsController`** and `POST` to the
+  mount path routes there. One controller used to serve both the widget's write
+  endpoint and the triage actions, which meant `base_controller_class` would
+  have put staff authentication in front of every member leaving a review. If
+  you referenced `Testimonials::TestimonialsController#create`, that is the
+  breaking change in this release; the URL is unchanged.
+- The shared request context (`current_author`, `current_tenant`,
+  `tenant_scope`, the gates) is now a `Testimonials::RequestContext` concern,
+  since the engine has two controller roots.
+
+## 0.7.10
+
+- The prompt-history ledger is now optional too. `bin/rails generate
+  testimonials:install --skip-prompt-events` leaves out the
+  `testimonials_prompt_events` table and writes `config.prompt_events = false`,
+  for apps that open the widget from their own button. `bin/rails generate
+  testimonials:prompt_events` adds the table later, like `testimonials:nps`.
+- With the flag off **nothing auto-opens**: `testimonial_prompt!` is a no-op,
+  because the history exists only to throttle auto-prompts and a prompt nothing
+  can throttle would reopen on every page. Explicit opens
+  (`data-testimonial-prompt`, `window.Testimonials.open()`), both public pages,
+  the dashboard and every submission path work unchanged.
+- `POST /testimonials/events` is refused when the flag is off, and the widget
+  stops posting shown/dismissed at all (`promptEvents.enabled` in its config).
+- `testimonials:seed_demo` skips the demo prompt history when the ledger is
+  off, and the `testimonials:tenant` migration skips either optional table when
+  it isn't there.
+- Adds `AGENTS.md`: install and integration instructions written for coding
+  agents, covering the request-shaped config lambdas, both skip flags, and the
+  mistakes agents actually make. It ships inside the gem, so
+  `cat "$(bundle show testimonials)/AGENTS.md"` works from a host app —
+  `examples/` now ships for the same reason.
+
 ## 0.7.9
 
 - NPS is now optional at install time. `bin/rails generate testimonials:install

data/README.md

@@ -33,14 +33,23 @@ bin/rails db:migrate
 The generator writes the initializer, the migration, and mounts the engine at
 `/testimonials`. Nothing renders until the widget is opened.
 
-Don't want NPS? Install without it — no table, no dashboard tab, no prompt:
+Two parts are optional at install time, and skipping either leaves out its
+table:
 
 ```bash
-bin/rails generate testimonials:install --skip-nps
+bin/rails generate testimonials:install --skip-nps            # no NPS at all
+bin/rails generate testimonials:install --skip-prompt-events  # no auto-prompts
 ```
 
-Changed your mind later: `bin/rails generate testimonials:nps`, migrate, and
-set `config.nps = true`.
+`--skip-nps` drops the 0–10 survey: no table, no dashboard tab, no prompt.
+`--skip-prompt-events` drops the prompt history — for apps that open the widget
+from their own button and never call `testimonial_prompt!`, since that history
+exists only to throttle auto-prompts. See
+[Prompting users](#prompting-users) for what changes.
+
+Changed your mind later: `bin/rails generate testimonials:nps` or
+`bin/rails generate testimonials:prompt_events`, migrate, and set the matching
+flag (`config.nps`, `config.prompt_events`) to `true`.
 
 Optional demo data:
 
@@ -59,6 +68,11 @@ refreshes those records instead of duplicating them.
 
 Ruby >= 3.2 · Rails >= 7.1 · Active Storage only if you want video/avatar uploads.
 
+Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
+steps in the order an agent needs them, plus the gates it tends to get wrong
+and the things it should not do. It ships inside the gem, so
+`cat "$(bundle show testimonials)/AGENTS.md"` works from any app that bundles it.
+
 ## What you get
 
 |                 |                                                                         |
@@ -132,6 +146,15 @@ The widget auto-opens on the next rendered page **if** the throttle allows:
 `data-testimonial-prompt` (or `="nps"`), or `window.Testimonials.open()` /
 `window.Testimonials.openNps()`.
 
+That history lives in `testimonials_prompt_events`, one row per shown,
+dismissed or submitted, and it is optional. `config.prompt_events = false` —
+what `--skip-prompt-events` writes at install — keeps no history at all, and so
+**nothing auto-opens**: `testimonial_prompt!` becomes a no-op, because a prompt
+nothing can throttle would reopen on every page. Explicit opens, the public
+pages, and everything above them are untouched, so an app that opens the widget
+from its own button loses nothing. Want auto-prompts back:
+`bin/rails generate testimonials:prompt_events`, migrate, flip the flag.
+
 ## Configure
 
 Everything is optional — a fresh install works with zero config. In
@@ -140,6 +163,8 @@ Everything is optional — a fresh install works with zero config. In
 | Option | Default | What it does |
 | --- | --- | --- |
 | `authorize_admin` | development only | **Who can read the dashboard.** Override before deploying |
+| `base_controller_class` | `ActionController::Base` | The controller the dashboard inherits — name your admin's and it adopts its layout, helpers and auth |
+| `admin_layout` | the gem's own | Just the shell, if you don't want the whole controller |
 | `app_name` | Rails app name | Shown as "Enjoying %{app}?" and in the questions |
 | `enabled` | everyone | Who gets the widget. `false` hides it and rejects posts |
 | `current_user` | `nil` | Attribute a submission to a user. Receives the request |
@@ -155,6 +180,7 @@ Everything is optional — a fresh install works with zero config. In
 | `storage_service` | app default | Active Storage service for uploads (a `storage.yml` key) |
 | `reprompt_after` | `90.days` | Cooldown after a dismissal |
 | `max_prompts` | `3` | Lifetime auto-prompt cap per user |
+| `prompt_events` | `true` | The prompt history the throttle reads. `false` = no history, no auto-prompts |
 | `public_collection` | `true` | The shareable `/testimonials/new` and `/testimonials/nps/new` pages |
 | `public_api` | `false` | Serve the read API without auth (CORS `*`) |
 | `nps` | `true` | The 0–10 NPS flow |

data/app/controllers/concerns/testimonials/request_context.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Who is asking, which tenant they are in, and the gates that answer both.
+  #
+  # A concern rather than inherited behaviour because the engine has two
+  # controller roots: the public endpoints hang off ActionController::Base, and
+  # the dashboard hangs off whatever the host set as `base_controller_class`.
+  # Both need everything here.
+  module RequestContext
+    extend ActiveSupport::Concern
+
+    private
+
+    def testimonials_admin_layout
+      Testimonials.config.admin_layout
+    end
+
+    def current_author
+      return @current_author if defined?(@current_author)
+
+      @current_author = Testimonials.config.current_user.call(request)
+    end
+
+    def current_author_id
+      current_author.respond_to?(:id) ? current_author.id : nil
+    end
+
+    # The tenant for this request (nil = the single global collection). Every
+    # read and write in the engine scopes to it, so a resolved-tenant admin
+    # only ever sees and writes their own tenant's records.
+    def current_tenant
+      return @current_tenant if defined?(@current_tenant)
+
+      @current_tenant = Testimonials.tenant(request)
+    end
+
+    # Every dashboard query and the create endpoint's one-per-user lookup start
+    # here, so neither can reach across tenants.
+    def tenant_scope
+      Testimonial.for_tenant(current_tenant)
+    end
+
+    def require_enabled
+      head :forbidden unless Testimonials.enabled?(request)
+    end
+
+    def render_rate_limited
+      message = I18n.t('testimonials.error_rate_limited',
+                       default: 'Too many submissions. Please wait a moment and try again.')
+      render json: { errors: [message] }, status: :too_many_requests
+    end
+
+    # Server-side gate for the dashboard. Default: development only.
+    def require_admin
+      return if Testimonials.admin?(request)
+
+      render plain: 'Forbidden. Set Testimonials.config.authorize_admin to grant access.',
+             status: :forbidden
+    end
+
+    # Guests get a permanent random token so the throttle ledger can
+    # remember them across visits. Signed-in users are keyed by author_id
+    # instead and never receive the cookie.
+    def ensure_visitor_token
+      return if current_author
+
+      cookies[:testimonials_vid].presence || begin
+        token = SecureRandom.base58(24)
+        cookies.permanent[:testimonials_vid] = { value: token, httponly: true, same_site: :lax }
+        token
+      end
+    end
+  end
+end

data/app/controllers/testimonials/application_controller.rb

@@ -1,63 +1,17 @@
 # frozen_string_literal: true
 
 module Testimonials
+  # Root of the engine's PUBLIC surface: widget.js, the submission endpoints,
+  # the prompt-event ledger, the public collection pages, media, and the read
+  # API. These stay on a plain ActionController::Base deliberately — a member
+  # posting a testimonial must not be routed through a host's admin controller,
+  # which would demand a staff session for the widget.
+  #
+  # The dashboard's root is DashboardController, and that is where
+  # `config.base_controller_class` applies.
   class ApplicationController < ActionController::Base
-    protect_from_forgery with: :exception
-
-    private
-
-    def testimonials_admin_layout
-      Testimonials.config.admin_layout
-    end
-
-    def current_author
-      return @current_author if defined?(@current_author)
-
-      @current_author = Testimonials.config.current_user.call(request)
-    end
-
-    def current_author_id
-      current_author.respond_to?(:id) ? current_author.id : nil
-    end
-
-    # The tenant for this request (nil = the single global collection). Every
-    # read and write in the engine scopes to it, so a resolved-tenant admin
-    # only ever sees and writes their own tenant's records.
-    def current_tenant
-      return @current_tenant if defined?(@current_tenant)
+    include RequestContext
 
-      @current_tenant = Testimonials.tenant(request)
-    end
-
-    def require_enabled
-      head :forbidden unless Testimonials.enabled?(request)
-    end
-
-    def render_rate_limited
-      message = I18n.t('testimonials.error_rate_limited',
-                       default: 'Too many submissions. Please wait a moment and try again.')
-      render json: { errors: [message] }, status: :too_many_requests
-    end
-
-    # Server-side gate for the dashboard. Default: development only.
-    def require_admin
-      return if Testimonials.admin?(request)
-
-      render plain: 'Forbidden. Set Testimonials.config.authorize_admin to grant access.',
-             status: :forbidden
-    end
-
-    # Guests get a permanent random token so the throttle ledger can
-    # remember them across visits. Signed-in users are keyed by author_id
-    # instead and never receive the cookie.
-    def ensure_visitor_token
-      return if current_author
-
-      cookies[:testimonials_vid].presence || begin
-        token = SecureRandom.base58(24)
-        cookies.permanent[:testimonials_vid] = { value: token, httponly: true, same_site: :lax }
-        token
-      end
-    end
+    protect_from_forgery with: :exception
   end
 end

data/app/controllers/testimonials/dashboard_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Root of the STAFF surface: the testimonial queue and the NPS pages.
+  #
+  # Inherits from `config.base_controller_class` — by default a plain
+  # ActionController::Base, which is why `authorize_admin` exists. Point it at
+  # the controller your own admin already inherits from and the dashboard picks
+  # up that stack wholesale: your layout, your helpers, your authentication,
+  # and whatever request context your before_actions establish (a `Current`
+  # attribute the layout reads, say). `config.admin_layout` only ever solved
+  # the first of those.
+  #
+  # Only the dashboard hangs off it. The widget's endpoints stay on
+  # ApplicationController, so wiring an admin base controller here can never
+  # demand a staff session from a member leaving a review.
+  class DashboardController < Testimonials.base_controller
+    include RequestContext
+
+    # A host base controller brings its own layout, and declaring one here would
+    # override it — the dashboard would render in the gem's standalone shell
+    # inside an app that just told us where its admin lives. So the gem only
+    # claims the layout when it owns the decision: no host base controller, or a
+    # host that named an `admin_layout` explicitly.
+    layout :testimonials_admin_layout unless superclass != ActionController::Base &&
+                                             Testimonials.config.admin_layout ==
+                                             Configuration::DEFAULT_ADMIN_LAYOUT
+
+    before_action :require_admin
+
+    # `authorize_admin` is a gate of last resort, and it is the only one when
+    # the host supplied no base controller. When they did, its default is
+    # development-only, so a host whose base controller already authenticates
+    # staff should widen or replace it.
+    #
+    # CSRF likewise: a host base controller has configured it already, and
+    # declaring it twice would run the check twice.
+    protect_from_forgery with: :exception if superclass == ActionController::Base
+  end
+end

data/app/controllers/testimonials/events_controller.rb

@@ -10,6 +10,9 @@ module Testimonials
     CLIENT_ACTIONS = %w[shown dismissed].freeze
 
     before_action :require_enabled
+    # An install run with --skip-prompt-events has no ledger to write to, and
+    # the widget it serves knows not to post here in the first place.
+    before_action :require_prompt_events
 
     def create
       kind = params[:kind].to_s
@@ -21,5 +24,11 @@ module Testimonials
                           author_id: current_author_id, visitor_token: ensure_visitor_token)
       head :no_content
     end
+
+    private
+
+    def require_prompt_events
+      head :forbidden unless Testimonials.config.prompt_events
+    end
   end
 end

data/app/controllers/testimonials/nps_responses_controller.rb

@@ -2,12 +2,9 @@
 
 module Testimonials
   # The NPS side of the dashboard: overall score plus the response list.
-  class NpsResponsesController < ApplicationController
+  class NpsResponsesController < DashboardController
     PER_PAGE = 50
 
-    layout :testimonials_admin_layout
-
-    before_action :require_admin
     # An install run with --skip-nps has no table behind these pages, and the
     # nav already hides the tab whenever config.nps is off.
     before_action :require_nps