perchfall-rails 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a7e457a262b1fbd251ebbcb6f5cae6c73a8b9659fe5b8db4bf81610e5022a16
-  data.tar.gz: 1e2cdc985b3210d4c60e2beb6d5cfde567cbf88afcd18c13d67b1f7db1189013
+  metadata.gz: 43b1de1c9380bf8b7d9b87e2c9e921840da81511ed2432457131780f9a9b2c4b
+  data.tar.gz: 89091a050cbc5c9c666fcbfb68840679c1de88c7c76ea9c28b49cd8635ec574f
 SHA512:
-  metadata.gz: f756f27804e3f1cf8671ca03f1e08957b431a1498777e7f4be83fde2ec4da151e61d45af17005f9e292ace6486e9c2f4fb85b985c4cc66f2a0ea6b911cdbd6dc
-  data.tar.gz: 48fafc4e5f77435cd169721e13b318f4c78b790054078dfb6f87bca07cd2bcf1f7e4c62dcda1206649b1fe1a502d7981a4ea698dcb73a1c06bfdadc369369309
+  metadata.gz: d6ca9dc520fcd29169b2d47d996432fbcfe9f1c4b1d8ba36c53e265e56c99bfaf53aeff8e8554eb0d261c3637c643f6b8ab170f74eb61914a9b02e3ea0366318
+  data.tar.gz: eb3d8ccb62d55e3d853d56d88e00809f9d1fe3e58a979c24221460fa43928943ba4cbd241801f4caadd196802f0d81b21b09901c4dfe740be44548c93417b2a1

data/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-13
+
+### Added
+
+- **`config.after_persist`** — optional callable invoked once per persisted `Perchfall::Rails::SyntheticRun`. Fires on the happy path *and* `RunJob`'s error rescues; receives the persisted run as a single positional argument. Exceptions raised by the hook are rescued (both `StandardError` and `ScriptError`, so a host `NotImplementedError` can't supplant the engine's own error) and logged with the run id and a partial backtrace — they do not interrupt control flow or prevent ActiveJob retries. See [ADR 0006](docs/adr/0006-synthetic-run-after-persist-hook.md).
+- **`config.synthetic_run_extension`** — optional string naming a host module that the engine constantizes and includes into `Perchfall::Rails::SyntheticRun`. Use this to declare host-side associations, scopes, or callbacks (e.g. `belongs_to :user`) instead of reopening the class from a `config.to_prepare` block. Applied from the engine's own `config.to_prepare`, which fires after host initializers, after eager_load, and again on every code reload (dev). See [ADR 0007](docs/adr/0007-synthetic-run-extension.md).
+- **`synthetic_runs_scope` override hook on `SyntheticRunsController`** — hosts define the method on their `base_controller` to scope the index and show actions (e.g. `where(user: current_user)`). The engine dispatches into it via `respond_to?(:synthetic_runs_scope, true)`, so DSL-materialized methods (method_missing-based delegation) are detected and unrelated same-named methods elsewhere in the ancestry don't get mistaken for the seam. Authorization-by-scoping falls out of the design: `show` 404s for records outside the host's scope without a separate authorization layer. The seam validates the host's return value (raises a self-diagnosing error if nil or non-relation) and normalizes ordering (applies `recent` if the host's relation has no `order_values`), so "always validated, always ordered" applies to every consumer of the seam, not just `index`. See [ADR 0005](docs/adr/0005-synthetic-runs-controller-scope-hook.md).
+- **[ADR 0004](docs/adr/0004-engine-extension-pattern.md)** articulates the engine's host-extension model — "install-and-go defaults with named override seams" — and partially backfills 0.1.0's `base_controller` and 0.3.0's `overrides_stylesheet` under the same principle. Names four established seam shapes and what's explicitly out of bounds (`config.to_prepare` monkey-patches, `Module#prepend` from initializers, wholesale engine class replacement).
+- Install generator template now exposes all five configuration attributes, including the two new ones (`after_persist`, `synthetic_run_extension`). Generator test asserts every attribute appears in the template.
+
+### Breaking changes
+
+- `SyntheticRun::Persist.call` renamed to `Persist.from_report`, with a new companion `Persist.from_error` that `RunJob`'s rescues route through. Persistence is now consolidated in one place, which is what makes `after_persist` fire for error-path runs. The class-method API is undocumented and the engine's own `RunJob` is updated in this release, but any host calling `Persist.call` directly will see `NoMethodError` post-upgrade and must update to `Persist.from_report`.
+
+### Changed
+
+- `Perchfall::Rails::Configuration` attribute order alphabetized to keep future additions consistent.
+
+## [0.3.0] - 2026-05-16
+
+### Breaking changes
+
+- Engine no longer depends on Tailwind CSS or the consumer's design tokens. The dashboard now ships with its own self-contained stylesheet that works on any Rails app. Hosts using the previous Tailwind bridge file (`app/assets/builds/tailwind/perchfall_rails.css`) must remove the `@import` and the `@theme { --color-* }` token block. To customize colors, configure `Perchfall::Rails.configuration.overrides_stylesheet` and define `--perchfall-*` CSS custom properties. See the README "Theming" section for migration steps.
+
+### Added
+
+- `Perchfall::Rails::Configuration#overrides_stylesheet` — optional path to a host-provided stylesheet loaded after the engine's CSS, for theming via `--perchfall-*` CSS custom properties.
+- Dark mode via `prefers-color-scheme: dark` — engine stylesheet defines both light and dark token sets.
+- Hand-authored engine stylesheet at `app/assets/stylesheets/perchfall/rails/application.css` served through the host's asset pipeline (Propshaft or Sprockets).
+
+### Changed
+
+- Engine layout now loads its own stylesheet (`perchfall/rails/application`) instead of the host's `:app` bundle, isolating dashboard styles from host CSS. Hosts that need full chrome (admin nav, branding) can override the layout by placing their own `app/views/layouts/perchfall/rails/application.html.erb`.
+- All engine views use namespaced `.pf-*` utility classes instead of bare Tailwind utilities.
+
+### Fixed
+
+- `SyntheticRunsController` now declares `layout "perchfall/rails/application"` explicitly. Without this, Rails fell back to the host's `layouts/application` and dropped the engine layout entirely — no `<!DOCTYPE>`, no stylesheet link, no `.pf-root` wrapper.
+
+### Removed
+
+- `app/assets/tailwind/perchfall_rails/` bridge file. Tailwind is no longer a supported integration path.
+- `docs/tailwind-v3.md`.
+
 ## [0.2.2] - 2026-05-05
 
 ### Changed
@@ -51,7 +95,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tailwind CSS integration: semantic token names (`primary`, `muted`, `subtle`, `error`, `border-subtle`, `neutral-0/150/900`) in all views. Tailwind v4 hosts import `perchfall_rails/engine` to scan the engine's views automatically; Tailwind v3 hosts add the engine view path to their `content` configuration.
 - Runtime dependencies: `perchfall ~> 0.4`, `pagy ~> 43.0`, Rails `>= 8.0`.
 
-[Unreleased]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/beflagrant/perchfall-rails/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/beflagrant/perchfall-rails/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/beflagrant/perchfall-rails/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/beflagrant/perchfall-rails/compare/v0.1.0...v0.2.0

data/README.md

@@ -8,14 +8,15 @@ A mountable Rails engine that adds a synthetic monitoring dashboard and backgrou
 
 ## Why perchfall-rails
 
-[perchfall](https://github.com/beflagrant/perchfall) gives you a `Report` value object — what a real Chromium browser saw at a URL. It deliberately doesn't impose a database schema or a job queue; you bring your own.
+[perchfall](https://github.com/beflagrant/perchfall) gives you a `Report` value object — what a real Chromium browser saw at a URL. It deliberately does not impose a database schema or job queue; you bring your own.
 
-perchfall-rails is the batteries-included path for Rails apps:
+perchfall-rails ships the Rails pieces:
 
 - **Schema and persistence** — a `SyntheticRun` ActiveRecord model that stores every check, with denormalized error counts and the full report JSON for later inspection.
 - **Background job** — a `Perchfall::Rails::RunJob` ActiveJob subclass you can `perform_later` (including with `ignore:` rules), with sensible retry behavior.
 - **Dashboard** — paginated, filterable index of runs and a detail view that surfaces every network and console error.
 - **Auth-agnostic** — point `base_controller` at any controller in your app and inherit its authentication.
+- **Extensible** — host-facing seams let you add associations, scope the dashboard to the current user, and react to each persisted run without monkey-patching the engine. See [ADR 0004](docs/adr/0004-engine-extension-pattern.md).
 
 If you only need the Ruby API, use perchfall directly. If you want a Rails-idiomatic place for synthetic results to live, mount this.
 
@@ -23,119 +24,122 @@ If you only need the Ruby API, use perchfall directly. If you want a Rails-idiom
 
 - Ruby >= 3.3
 - Rails >= 8.0
-- Node.js >= 18 (required by perchfall for Playwright)
-- [pagy](https://github.com/ddnexus/pagy) ~> 43.0 (bundled as a dependency — no separate install needed)
+- Node.js >= 18 with the `playwright` npm package and a Chromium binary (installed via the engine's rake task — see below)
+- [pagy](https://github.com/ddnexus/pagy) ~> 43.0 (bundled as a dependency)
 
 ## Installation
 
-Add to your Gemfile:
+Add to your `Gemfile`:
 
 ```ruby
 gem "perchfall-rails"
 ```
 
-Then run:
+Install the gem, the initializer, the engine migrations, and Playwright:
 
 ```sh
 bundle install
-```
-
-### Node.js and Playwright
-
-The engine requires Node.js and the Playwright npm package with a Chromium browser binary. After bundling:
-
-```sh
+bin/rails generate perchfall:rails:install
+bin/rails perchfall_rails:install:migrations
+bin/rails db:migrate
 bin/rails perchfall_rails:install:playwright
 ```
 
-This runs `npm install playwright` and `npx playwright install chromium`. Verify the full environment with:
+Mount the engine in `config/routes.rb`:
 
-```sh
-bin/rails perchfall_rails:check
+```ruby
+mount Perchfall::Rails::Engine, at: "/perchfall"
 ```
 
-### Initializer
-
-Generate the configuration initializer:
+Verify the Node/Playwright/Chromium environment:
 
 ```sh
-bin/rails generate perchfall:rails:install
+bin/rails perchfall_rails:check
 ```
 
-This creates `config/initializers/perchfall_rails.rb` and prints the remaining setup steps.
+The dashboard is now available at `/perchfall/synthetic_runs`.
 
-### Migrations
+## Quick start
 
-Install and run the engine migrations:
+Enqueue a synthetic run from anywhere in your application:
 
-```sh
-bin/rails perchfall_rails:install:migrations
-bin/rails db:migrate
+```ruby
+Perchfall::Rails::RunJob.perform_later(url: "https://example.com")
+# => #<Perchfall::Rails::RunJob ...>
 ```
 
-### Routes
+When the job runs, it creates one `SyntheticRun` record with the full Chromium report, network errors, and console errors. View it at `/perchfall/synthetic_runs`.
 
-Mount the engine in `config/routes.rb`:
+To suppress known-noisy errors, pass `ignore:` rules:
 
 ```ruby
-mount Perchfall::Rails::Engine, at: "/perchfall"
-```
+rule = Perchfall::IgnoreRule.new(
+  pattern: "chrome-error://",
+  type:    "*",
+  target:  :console
+)
 
-The dashboard will be available at `/perchfall/synthetic_runs`.
+Perchfall::Rails::RunJob.perform_later(
+  url:           "https://example.com",
+  scenario_name: "homepage",
+  ignore:        [rule]
+)
+```
 
 ## Configuration
 
-Create an initializer at `config/initializers/perchfall_rails.rb`:
+The install generator creates `config/initializers/perchfall_rails.rb` with `base_controller` set to `"ApplicationController"` (with a warning logged at boot in production until you change it) and the optional attributes pre-commented with sample values. A configured initializer looks like:
 
 ```ruby
 Perchfall::Rails.configure do |config|
-  # Required in production: set this to a controller that enforces authentication.
-  # The engine will log a warning at boot if this is still ApplicationController
-  # in a production environment.
   config.base_controller = "AuthenticatedController"
 
-  # ActiveJob queue name for synthetic run jobs. Defaults to :synthetic.
-  config.queue_name = :synthetic
+  # config.queue_name              = :synthetic
+  # config.overrides_stylesheet    = "perchfall_rails_overrides"
+  # config.after_persist           = ->(run) { SomeJob.perform_later(run.id) if run.failed? }
+  # config.synthetic_run_extension = "SyntheticRunExtension"
 end
 ```
 
+- `base_controller` — controller the engine inherits from. Required in production; the engine logs a warning at boot if this is still `ApplicationController` in a production environment. Must inherit from `ActionController::Base`.
+- `queue_name` — ActiveJob queue used by `RunJob`. Defaults to `:synthetic`.
+- `overrides_stylesheet` — optional path (without extension) to a host stylesheet loaded after the engine CSS. Use to override `--perchfall-*` CSS custom properties.
+- `after_persist` — optional callable invoked after each `SyntheticRun` is persisted. Receives the run as a single positional argument and fires on both the happy path and `RunJob`'s error rescues — once per persisted run, which under ActiveJob retries means once per attempt. Use `run.id` to route downstream work to that specific persisted run (`SomeJob.perform_later(run.id)`) — each retry attempt persists a distinct id, so `run.id` does **not** dedup across attempts. The engine provides no cross-attempt key today, so handlers that need once-per-failure-event semantics (notifications, ticket-opens) should be designed to be idempotent on the host's natural keys, or should accept at-least-once delivery. Exceptions raised by the callable are rescued and logged; they do not interrupt the pipeline. See [ADR 0006](docs/adr/0006-synthetic-run-after-persist-hook.md).
+- `synthetic_run_extension` — optional name of a host module the engine includes into `Perchfall::Rails::SyntheticRun` from a `config.to_prepare` block (so the include fires after host initializers, after eager_load in production, and again after every code reload in development). Use it to declare host-side associations, scopes, or callbacks (`belongs_to :user`, &c.). The named module must be autoloadable. Callbacks added through the extension run as part of the engine's `SyntheticRun.create!`; if one raises, the create fails, the job dies, no `SyntheticRun` is written (not even an error row), and `after_persist` does not fire. Reserve extension callbacks for declarations and logic that has been hardened against raising; for observability-style side effects, use `after_persist`. See [ADR 0007](docs/adr/0007-synthetic-run-extension.md).
+
 ## Authentication
 
 The engine has no built-in authentication. Set `base_controller` to a controller that enforces whatever authentication your application uses:
 
 ```ruby
-# config/initializers/perchfall_rails.rb
 Perchfall::Rails.configure do |config|
   config.base_controller = "Admin::BaseController"
 end
 ```
 
-`base_controller` must inherit from `ActionController::Base`. The engine views use `csrf_meta_tags`, `csp_meta_tag`, and `stylesheet_link_tag`, none of which are available on `ActionController::API` controllers.
+`base_controller` must inherit from `ActionController::Base`. Engine views use `csrf_meta_tags`, `csp_meta_tag`, and `stylesheet_link_tag`, none of which are available on `ActionController::API` controllers.
 
-## Enqueueing checks
+## Scoping runs to the current user
 
-Enqueue a synthetic run from anywhere in your application:
+By default the dashboard shows every `SyntheticRun` in the database. To scope it — e.g. each user only sees their own runs — define `synthetic_runs_scope` on `base_controller`:
 
 ```ruby
-Perchfall::Rails::RunJob.perform_later(url: "https://example.com")
-```
+class AuthenticatedController < ApplicationController
+  before_action :authenticate_user!
 
-To suppress known-noisy errors, pass `ignore:` rules:
+  private
 
-```ruby
-rule = Perchfall::IgnoreRule.new(
-  pattern: "chrome-error://",
-  type:    "*",
-  target:  :console
-)
-Perchfall::Rails::RunJob.perform_later(
-  url:           "https://example.com",
-  scenario_name: "homepage",
-  ignore:        [rule]
-)
+  def synthetic_runs_scope
+    current_user.synthetic_runs
+  end
+end
 ```
 
-**Retry behavior:** When a run fails with a `Perchfall::Errors::Error`, the job persists an error record and then re-raises the exception so the queue adapter can retry normally. Each retry attempt that also fails will create an additional error record. If you want to cap error records at one per enqueued job, configure `discard_on` in a subclass or use your queue adapter's retry settings:
+The engine calls `synthetic_runs_scope` from both `index` and `show`. If the host returns an unordered relation, the engine merges in a default `recent` order so pagination stays stable. Pair this with two association declarations on the host side: a `belongs_to :user` on `Perchfall::Rails::SyntheticRun` declared via `config.synthetic_run_extension` (which includes the host module into the engine's model — see [ADR 0007](docs/adr/0007-synthetic-run-extension.md)), and the matching `has_many :synthetic_runs, class_name: "Perchfall::Rails::SyntheticRun"` directly on your host model (e.g. `User`). The `synthetic_run_extension` seam includes its module into `SyntheticRun`, so it can only carry the `belongs_to` side; `has_many` belongs on whichever host model owns the association. See [ADR 0005](docs/adr/0005-synthetic-runs-controller-scope-hook.md).
+
+## Retry behavior
+
+When a run fails with `Perchfall::Errors::Error`, the job persists an error record and re-raises so the queue adapter can retry normally. Each retry that also fails creates another error record. To cap error records at one per enqueued job, subclass `RunJob` and `discard_on`:
 
 ```ruby
 class MyRunJob < Perchfall::Rails::RunJob
@@ -143,73 +147,32 @@ class MyRunJob < Perchfall::Rails::RunJob
 end
 ```
 
-## Tailwind CSS
+## Theming
 
-The engine views use semantic Tailwind token names. Add the following to your Tailwind configuration to define the required tokens:
+The engine ships its own stylesheet. Default colors render well in both light and dark mode (the dashboard follows `prefers-color-scheme`).
 
-**Tailwind v4**:
+To customize colors, point `config.overrides_stylesheet` at a host CSS file:
 
-`tailwindcss-rails` automatically generates a bridge file at `app/assets/builds/tailwind/perchfall_rails.css` when the engine is bundled. Import it from your Tailwind CSS entry point, then define the required tokens. Replace the example values with your application's actual colors:
+```ruby
+Perchfall::Rails.configure do |config|
+  config.overrides_stylesheet = "perchfall_rails_overrides"
+end
+```
 
 ```css
-@import "tailwindcss";
-@import "../builds/tailwind/perchfall_rails";
-
-@theme {
-  --color-primary: #2563eb;
-  --color-muted: #6b7280;
-  --color-subtle: #9ca3af;
-  --color-error: #ef4444;
-  --color-border-subtle: #e5e7eb;
-
-  --color-neutral-0: #ffffff;
-  --color-neutral-150: #e5e7eb;
-  --color-neutral-900: #111827;
+/* app/assets/stylesheets/perchfall_rails_overrides.css */
+:root {
+  --perchfall-color-primary: #db2777;
+  --perchfall-color-error:   #b91c1c;
 }
 ```
 
-The `../builds/tailwind/perchfall_rails` path assumes your CSS entry point is in `app/assets/tailwind/` or `app/assets/stylesheets/`. Adjust if your layout differs.
-
-**Tailwind v3** (`tailwind.config.js`):
-
-Add the engine's views to your content paths and define the required tokens. Replace the example values with your application's actual colors:
-
-```js
-const { execSync } = require("child_process");
-const enginePath = execSync("bundle show perchfall-rails").toString().trim();
-
-module.exports = {
-  content: [
-    // ... your existing content paths
-    `${enginePath}/app/views/**/*.html.erb`,
-  ],
-  theme: {
-    extend: {
-      colors: {
-        primary: "#2563eb",
-        muted: "#6b7280",
-        subtle: "#9ca3af",
-        error: "#ef4444",
-        neutral: {
-          0: "#ffffff",
-          150: "#e5e7eb",
-          900: "#111827",
-        },
-      },
-      borderColor: {
-        subtle: "#e5e7eb",
-      },
-    },
-  },
-}
-```
+Available tokens are defined in [`app/assets/stylesheets/perchfall/rails/application.css`](app/assets/stylesheets/perchfall/rails/application.css). Headline tokens: `--perchfall-color-primary`, `--perchfall-color-error`, `--perchfall-color-text`, `--perchfall-color-muted`, `--perchfall-color-subtle`, `--perchfall-color-surface`, `--perchfall-color-surface-alt`, `--perchfall-color-border`. The file also exposes typography, spacing, and radius tokens.
 
-If your application does not use Tailwind, the views render unstyled but functional.
+Hosts that need full chrome around the dashboard (admin nav, branding) can override the engine layout by placing their own `app/views/layouts/perchfall/rails/application.html.erb` in the host application.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then run `rake test` to run the tests.
-
 ```sh
 bin/setup
 bundle exec rake test
@@ -217,12 +180,12 @@ bundle exec rake test
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/beflagrant/perchfall-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/beflagrant/perchfall-rails/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at <https://github.com/beflagrant/perchfall-rails>. See [CONTRIBUTING.md](CONTRIBUTING.md). Release notes live in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
 
 ## Code of Conduct
 
-Everyone interacting in the perchfall-rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/beflagrant/perchfall-rails/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the perchfall-rails project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/app/assets/stylesheets/perchfall/rails/application.css

@@ -0,0 +1,258 @@
+/* ===================================================================
+   perchfall-rails engine styles
+   Hand-authored. Override colors via --perchfall-* CSS custom
+   properties in a host stylesheet referenced through
+   `config.overrides_stylesheet`.
+   =================================================================== */
+
+/* -------------------------------------------------------------------
+   1. Tokens (light)
+   ------------------------------------------------------------------- */
+:root {
+  --perchfall-color-primary:      #2563eb;
+  --perchfall-color-error:        #ef4444;
+  --perchfall-color-text:         #111827;
+  --perchfall-color-muted:        #6b7280;
+  --perchfall-color-subtle:       #9ca3af;
+  --perchfall-color-surface:      #ffffff;
+  --perchfall-color-surface-alt:  #f9fafb;
+  --perchfall-color-border:       #e5e7eb;
+
+  --perchfall-font-family:        ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --perchfall-font-size-sm:       0.875rem;
+  --perchfall-font-size-base:     1rem;
+  --perchfall-font-size-lg:       1.125rem;
+  --perchfall-font-size-xl:       1.25rem;
+  --perchfall-font-size-2xl:      1.5rem;
+  --perchfall-font-size-3xl:      1.875rem;
+  --perchfall-font-size-5xl:      3rem;
+  --perchfall-line-height-tight:  1.2;
+  --perchfall-line-height-normal: 1.4;
+
+  --perchfall-space-0-5:          0.125rem;
+  --perchfall-space-1:            0.25rem;
+  --perchfall-space-2:            0.5rem;
+  --perchfall-space-3:            0.75rem;
+  --perchfall-space-4:            1rem;
+  --perchfall-space-6:            1.5rem;
+  --perchfall-space-8:            2rem;
+
+  --perchfall-radius-lg:          0.5rem;
+  --perchfall-radius-2xl:         1rem;
+
+  --perchfall-container-max:      1280px;
+}
+
+/* -------------------------------------------------------------------
+   2. Tokens (dark)
+   ------------------------------------------------------------------- */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --perchfall-color-primary:     #60a5fa;
+    --perchfall-color-error:       #f87171;
+    --perchfall-color-text:        #f3f4f6;
+    --perchfall-color-muted:       #9ca3af;
+    --perchfall-color-subtle:      #6b7280;
+    --perchfall-color-surface:     #111827;
+    --perchfall-color-surface-alt: #1f2937;
+    --perchfall-color-border:      #374151;
+  }
+}
+
+/* -------------------------------------------------------------------
+   3. Reset (scoped to .pf-root)
+   ------------------------------------------------------------------- */
+.pf-root,
+.pf-root *,
+.pf-root *::before,
+.pf-root *::after {
+  box-sizing: border-box;
+}
+
+.pf-root {
+  font-family: var(--perchfall-font-family);
+  color: var(--perchfall-color-text);
+  line-height: var(--perchfall-line-height-normal);
+  background: var(--perchfall-color-surface-alt);
+  min-height: 100vh;
+}
+
+.pf-root a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.pf-root hr {
+  border: none;
+  border-top: 1px solid var(--perchfall-color-border);
+  margin: 0;
+}
+
+.pf-container {
+  max-width: var(--perchfall-container-max);
+  margin: 0 auto;
+  padding: var(--perchfall-space-8);
+}
+
+/* -------------------------------------------------------------------
+   4. Utilities (.pf-*)
+   ------------------------------------------------------------------- */
+
+/* Display */
+.pf-flex   { display: flex; }
+.pf-grid   { display: grid; }
+
+/* Flex */
+.pf-flex-col       { flex-direction: column; }
+.pf-flex-row       { flex-direction: row; }
+.pf-flex-1         { flex: 1 1 0%; }
+.pf-items-start    { align-items: flex-start; }
+.pf-items-center   { align-items: center; }
+.pf-justify-between { justify-content: space-between; }
+.pf-self-stretch   { align-self: stretch; }
+
+/* Grid templates */
+.pf-grid-cols-2   { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.pf-grid-runs     { grid-template-columns: 2fr 1fr 1fr 1fr 1fr 1fr; }
+.pf-grid-summary  { grid-template-columns: 1fr 1fr; }
+
+/* Gap */
+.pf-gap-0-5 { gap: var(--perchfall-space-0-5); }
+.pf-gap-1   { gap: var(--perchfall-space-1); }
+.pf-gap-2   { gap: var(--perchfall-space-2); }
+.pf-gap-3   { gap: var(--perchfall-space-3); }
+.pf-gap-4   { gap: var(--perchfall-space-4); }
+.pf-gap-6   { gap: var(--perchfall-space-6); }
+
+/* Sizing */
+.pf-w-full { width: 100%; }
+.pf-w-64   { width: 16rem; }
+
+/* Padding */
+.pf-p-8   { padding: var(--perchfall-space-8); }
+.pf-px-3  { padding-left: var(--perchfall-space-3); padding-right: var(--perchfall-space-3); }
+.pf-px-4  { padding-left: var(--perchfall-space-4); padding-right: var(--perchfall-space-4); }
+.pf-py-2  { padding-top: var(--perchfall-space-2); padding-bottom: var(--perchfall-space-2); }
+
+/* Typography: size */
+.pf-text-sm   { font-size: var(--perchfall-font-size-sm); }
+.pf-text-base { font-size: var(--perchfall-font-size-base); }
+.pf-text-lg   { font-size: var(--perchfall-font-size-lg); }
+.pf-text-xl   { font-size: var(--perchfall-font-size-xl); }
+.pf-text-2xl  { font-size: var(--perchfall-font-size-2xl); }
+.pf-text-3xl  { font-size: var(--perchfall-font-size-3xl); }
+.pf-text-5xl  { font-size: var(--perchfall-font-size-5xl); }
+
+/* Typography: weight */
+.pf-font-normal     { font-weight: 400; }
+.pf-font-semibold   { font-weight: 600; }
+.pf-font-extrabold  { font-weight: 800; }
+
+/* Typography: line-height */
+.pf-leading-tight  { line-height: var(--perchfall-line-height-tight); }
+.pf-leading-normal { line-height: var(--perchfall-line-height-normal); }
+
+/* Typography: color */
+.pf-text-primary { color: var(--perchfall-color-primary); }
+.pf-text-error   { color: var(--perchfall-color-error); }
+.pf-text-muted   { color: var(--perchfall-color-muted); }
+.pf-text-subtle  { color: var(--perchfall-color-subtle); }
+.pf-text-body    { color: var(--perchfall-color-text); }
+
+/* Typography: alignment + decoration */
+.pf-text-right  { text-align: right; }
+.pf-capitalize  { text-transform: capitalize; }
+.pf-underline   { text-decoration: underline; }
+.pf-truncate    { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-break-all   { word-break: break-all; }
+
+/* Borders */
+.pf-border         { border: 1px solid var(--perchfall-color-border); }
+.pf-border-subtle  { border-color: var(--perchfall-color-border); }
+.pf-rounded-lg     { border-radius: var(--perchfall-radius-lg); }
+.pf-rounded-2xl    { border-radius: var(--perchfall-radius-2xl); }
+
+/* Backgrounds */
+.pf-bg-surface      { background-color: var(--perchfall-color-surface); }
+.pf-bg-surface-alt  { background-color: var(--perchfall-color-surface-alt); }
+
+/* Effects */
+.pf-cursor-pointer { cursor: pointer; }
+.pf-opacity-60     { opacity: 0.6; }
+
+/* Forms */
+.pf-input,
+.pf-select {
+  font: inherit;
+  color: var(--perchfall-color-text);
+  background-color: var(--perchfall-color-surface);
+  border: 1px solid var(--perchfall-color-border);
+  border-radius: var(--perchfall-radius-lg);
+  padding: var(--perchfall-space-2) var(--perchfall-space-3);
+}
+.pf-input:focus,
+.pf-select:focus {
+  outline: 2px solid var(--perchfall-color-primary);
+  outline-offset: 1px;
+}
+.pf-button {
+  font: inherit;
+  color: var(--perchfall-color-primary);
+  background-color: var(--perchfall-color-surface);
+  border: 1px solid var(--perchfall-color-border);
+  border-radius: var(--perchfall-radius-lg);
+  padding: var(--perchfall-space-2) var(--perchfall-space-4);
+  cursor: pointer;
+  font-weight: 600;
+}
+.pf-button:hover {
+  background-color: var(--perchfall-color-surface-alt);
+}
+
+/* Hover utilities */
+.pf-hover\:pf-text-primary:hover { color: var(--perchfall-color-primary); }
+
+/* Responsive: md (>= 768px) */
+@media (min-width: 768px) {
+  .pf-md\:pf-flex-row     { flex-direction: row; }
+  .pf-md\:pf-items-center { align-items: center; }
+}
+
+/* -------------------------------------------------------------------
+   5. Pagy pagination
+   ------------------------------------------------------------------- */
+.pf-root nav.pagy {
+  display: flex;
+  gap: var(--perchfall-space-2);
+  align-items: center;
+  font-size: var(--perchfall-font-size-sm);
+  margin-top: var(--perchfall-space-4);
+}
+
+.pf-root nav.pagy a,
+.pf-root nav.pagy span,
+.pf-root nav.pagy label {
+  display: inline-block;
+  padding: var(--perchfall-space-2) var(--perchfall-space-3);
+  border: 1px solid var(--perchfall-color-border);
+  border-radius: var(--perchfall-radius-lg);
+  color: var(--perchfall-color-primary);
+  background-color: var(--perchfall-color-surface);
+  text-decoration: none;
+}
+
+.pf-root nav.pagy a.current,
+.pf-root nav.pagy .current {
+  color: var(--perchfall-color-text);
+  background-color: var(--perchfall-color-surface-alt);
+  font-weight: 600;
+}
+
+.pf-root nav.pagy a:hover {
+  background-color: var(--perchfall-color-surface-alt);
+}
+
+.pf-root nav.pagy .gap {
+  border: none;
+  background: transparent;
+}

data/app/controllers/perchfall/rails/synthetic_runs_controller.rb

@@ -3,20 +3,64 @@
 module Perchfall
   module Rails
     class SyntheticRunsController < Perchfall::Rails.configuration.base_controller.constantize
+      layout "perchfall/rails/application"
+
       include ::Pagy::Method
 
       def index
-        runs = SyntheticRun.recent
+        runs = resolved_synthetic_runs_scope
         runs = runs.for_status(params[:status]) if SyntheticRun::STATUSES.include?(params[:status])
         runs = runs.for_url(params[:url])       if params[:url].present?
         @pagy, @runs = pagy(:offset, runs)
       end
 
       def show
-        @run = SyntheticRun.find(params[:id])
+        @run = resolved_synthetic_runs_scope.find(params[:id])
       rescue ActiveRecord::RecordNotFound
         head :not_found
       end
+
+      private
+
+      # ADR 0005's host seam. Hosts define `synthetic_runs_scope` on their
+      # `base_controller` to scope the dashboard (e.g. `current_user.synthetic_runs`).
+      # This method is the engine's internal dispatcher into that host method
+      # — named distinctly from the host hook so:
+      #
+      # - `respond_to?(:synthetic_runs_scope, true)` consults the host's
+      #   `respond_to_missing?`, so `method_missing`-based delegation is
+      #   detected. The previous `defined?(super)` form silently fell through
+      #   to the engine's unscoped default for that case — an auth-bypass risk.
+      # - The host's `synthetic_runs_scope` is reached via normal instance
+      #   dispatch — no `super` inversion. The previous shape had the engine
+      #   define a same-named method that called `super` to reach the host's,
+      #   which is non-obvious to a reader of either side.
+      #
+      # `respond_to?` still walks the ancestry, so an unrelated method named
+      # `synthetic_runs_scope` from a concern or mixin can be picked up —
+      # the validation guard below surfaces that as a self-diagnosing error
+      # when the unrelated method returns the wrong type.
+      #
+      # The host's return value is validated; nil or non-relation raises a
+      # self-diagnosing error. If the host's relation has no order clause,
+      # `recent` is applied — "always ordered" is the seam's contract, not
+      # something only `index` patches up.
+      def resolved_synthetic_runs_scope
+        scope =
+          if respond_to?(:synthetic_runs_scope, true)
+            synthetic_runs_scope
+          else
+            Perchfall::Rails::SyntheticRun.recent
+          end
+
+        unless scope.is_a?(ActiveRecord::Relation)
+          raise "synthetic_runs_scope must return an ActiveRecord::Relation " \
+                "(got #{scope.class}) — see ADR 0005"
+        end
+        return scope if scope.order_values.any?
+
+        scope.recent
+      end
     end
   end
 end

data/app/jobs/perchfall/rails/run_job.rb

@@ -10,22 +10,12 @@ module Perchfall
       def perform(url:, scenario_name: nil, ignore: [], client: nil)
         client ||= Perchfall::Client.new
         report = client.run(url: url, scenario_name: scenario_name, ignore: ignore)
-        SyntheticRun::Persist.call(report, url: url, scenario_name: scenario_name)
+        SyntheticRun::Persist.from_report(report, url: url, scenario_name: scenario_name)
       rescue Perchfall::Errors::PageLoadError => e
-        SyntheticRun.create!(
-          url: url,
-          scenario_name: scenario_name,
-          status: "error",
-          raw_report: e.report.to_h
-        )
+        SyntheticRun::Persist.from_error(url: url, scenario_name: scenario_name, raw_report: e.report.to_h)
         raise
       rescue Perchfall::Errors::Error => e
-        SyntheticRun.create!(
-          url: url,
-          scenario_name: scenario_name,
-          status: "error",
-          raw_report: { "error" => e.message }
-        )
+        SyntheticRun::Persist.from_error(url: url, scenario_name: scenario_name, raw_report: { "error" => e.message })
         raise
       end
     end

data/app/services/perchfall/rails/synthetic_run/persist.rb

@@ -4,10 +4,46 @@ module Perchfall
   module Rails
     class SyntheticRun
       class Persist
-        def self.call(report, url:, scenario_name: nil)
-          new(report, url: url, scenario_name: scenario_name).call
+        def self.from_report(report, url:, scenario_name: nil)
+          persisting { new(report, url: url, scenario_name: scenario_name).call }
         end
 
+        def self.from_error(url:, raw_report:, scenario_name: nil)
+          persisting do
+            SyntheticRun.create!(
+              url: url, scenario_name: scenario_name, status: "error", raw_report: raw_report
+            )
+          end
+        end
+
+        # Every entry point that persists a SyntheticRun routes through here so
+        # the after_persist hook fires exactly once per persisted run — adding
+        # a third entry point can't silently forget the hook, only by-passing
+        # this helper can.
+        def self.persisting
+          run = yield
+          invoke_after_persist(run)
+          run
+        end
+        private_class_method :persisting
+
+        def self.invoke_after_persist(run)
+          hook = Perchfall::Rails.configuration.after_persist
+          return unless hook
+
+          hook.call(run)
+        rescue StandardError, ScriptError => e
+          # Catch ScriptError too — NotImplementedError or LoadError from a host
+          # hook would otherwise escape past RunJob's Perchfall-only rescues and
+          # supplant the engine's error. Signal/memory exceptions propagate.
+          backtrace = (e.backtrace || []).first(5).join("\n  ")
+          ::Rails.logger.error(
+            "Perchfall::Rails after_persist hook raised for SyntheticRun ##{run.id}: " \
+            "#{e.class}: #{e.message}\n  #{backtrace}"
+          )
+        end
+        private_class_method :invoke_after_persist
+
         def initialize(report, url:, scenario_name:)
           @report        = report
           @url           = url

data/app/views/layouts/perchfall/rails/application.html.erb

@@ -5,9 +5,16 @@
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
-    <%= stylesheet_link_tag :app %>
+    <%= stylesheet_link_tag "perchfall/rails/application", media: "all" %>
+    <% if Perchfall::Rails.configuration.overrides_stylesheet.present? %>
+      <%= stylesheet_link_tag Perchfall::Rails.configuration.overrides_stylesheet, media: "all" %>
+    <% end %>
   </head>
   <body>
-    <%= yield %>
+    <div class="pf-root">
+      <div class="pf-container">
+        <%= yield %>
+      </div>
+    </div>
   </body>
 </html>

data/app/views/perchfall/rails/synthetic_runs/_console_error_card.html.erb

@@ -1,14 +1,14 @@
-<div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-4">
-  <h3 class="text-3xl font-extrabold leading-[120%] <%= heading_color %>">
-    <%= title %> <span class="text-2xl font-semibold <%= count_color %>">(<%= count %>)</span>
+<div class="pf-p-8 pf-border pf-border-subtle pf-rounded-2xl pf-bg-surface pf-flex pf-flex-col pf-gap-4">
+  <h3 class="pf-text-3xl pf-font-extrabold pf-leading-tight <%= heading_color %>">
+    <%= title %> <span class="pf-text-2xl pf-font-semibold <%= count_color %>">(<%= count %>)</span>
   </h3>
   <% errors.each_with_index do |err, i| %>
-    <div class="flex flex-col gap-1 <%= 'opacity-60' if dimmed %>">
-      <span class="text-xl font-normal text-neutral-900 break-all"><%= err["text"] %></span>
-      <span class="text-sm font-normal text-muted"><%= err["type"] %> &mdash; <%= err["location"] %></span>
+    <div class="pf-flex pf-flex-col pf-gap-1 <%= 'pf-opacity-60' if dimmed %>">
+      <span class="pf-text-xl pf-font-normal pf-text-body pf-break-all"><%= err["text"] %></span>
+      <span class="pf-text-sm pf-font-normal pf-text-muted"><%= err["type"] %> &mdash; <%= err["location"] %></span>
     </div>
     <% unless i == errors.size - 1 %>
-      <hr class="border-subtle">
+      <hr>
     <% end %>
   <% end %>
 </div>

data/app/views/perchfall/rails/synthetic_runs/_network_error_card.html.erb

@@ -1,14 +1,14 @@
-<div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-4">
-  <h3 class="text-3xl font-extrabold leading-[120%] <%= heading_color %>">
-    <%= title %> <span class="text-2xl font-semibold <%= count_color %>">(<%= count %>)</span>
+<div class="pf-p-8 pf-border pf-border-subtle pf-rounded-2xl pf-bg-surface pf-flex pf-flex-col pf-gap-4">
+  <h3 class="pf-text-3xl pf-font-extrabold pf-leading-tight <%= heading_color %>">
+    <%= title %> <span class="pf-text-2xl pf-font-semibold <%= count_color %>">(<%= count %>)</span>
   </h3>
   <% errors.each_with_index do |err, i| %>
-    <div class="flex flex-col gap-1 <%= 'opacity-60' if dimmed %>">
-      <span class="text-xl font-normal text-neutral-900 break-all"><%= err["url"] %></span>
-      <span class="text-sm font-normal text-muted"><%= err["method"] %> &mdash; <%= err["failure"] %></span>
+    <div class="pf-flex pf-flex-col pf-gap-1 <%= 'pf-opacity-60' if dimmed %>">
+      <span class="pf-text-xl pf-font-normal pf-text-body pf-break-all"><%= err["url"] %></span>
+      <span class="pf-text-sm pf-font-normal pf-text-muted"><%= err["method"] %> &mdash; <%= err["failure"] %></span>
     </div>
     <% unless i == errors.size - 1 %>
-      <hr class="border-subtle">
+      <hr>
     <% end %>
   <% end %>
 </div>

data/app/views/perchfall/rails/synthetic_runs/index.html.erb

@@ -1,60 +1,59 @@
-<div class="flex flex-col gap-6 w-full">
-  <div class="flex flex-col md:flex-row items-start md:items-center self-stretch justify-between gap-4">
-    <h2 class="text-5xl font-extrabold leading-[120%] text-primary">Synthetic Runs</h2>
+<div class="pf-flex pf-flex-col pf-gap-6 pf-w-full">
+  <div class="pf-flex pf-flex-col pf-md:pf-flex-row pf-items-start pf-md:pf-items-center pf-self-stretch pf-justify-between pf-gap-4">
+    <h2 class="pf-text-5xl pf-font-extrabold pf-leading-tight pf-text-primary">Synthetic Runs</h2>
 
-    <%= form_with url: synthetic_runs_path, method: :get, class: "flex flex-row gap-3 items-center" do |f| %>
+    <%= form_with url: synthetic_runs_path, method: :get, class: "pf-flex pf-flex-row pf-gap-3 pf-items-center" do |f| %>
       <%= f.select :status,
             Perchfall::Rails::SyntheticRun::STATUSES.map { |status| [status.capitalize, status] },
             { include_blank: "All statuses", selected: params[:status] },
-            class: "text-sm font-medium text-muted border border-neutral-150 rounded-lg px-3 py-2 bg-neutral-0" %>
+            class: "pf-select pf-text-sm pf-font-semibold pf-text-muted" %>
       <%= f.text_field :url,
             placeholder: "Filter by URL",
             value: params[:url],
-            class: "text-sm text-neutral-900 border border-neutral-150 rounded-lg px-3 py-2 bg-neutral-0 w-64" %>
-      <%= f.submit "Filter",
-            class: "text-sm font-semibold text-primary border border-neutral-150 rounded-lg px-4 py-2 bg-neutral-0 cursor-pointer" %>
+            class: "pf-input pf-text-sm pf-w-64" %>
+      <%= f.submit "Filter", class: "pf-button pf-text-sm" %>
     <% end %>
   </div>
 
-  <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-6">
-    <div class="grid grid-cols-[2fr_1fr_1fr_1fr_1fr_1fr] gap-4 items-center">
-      <span class="text-lg font-semibold leading-[140%] text-muted">URL / Scenario</span>
-      <span class="text-lg font-semibold leading-[140%] text-muted">Status</span>
-      <span class="text-lg font-semibold leading-[140%] text-muted text-right">HTTP</span>
-      <span class="text-lg font-semibold leading-[140%] text-muted text-right">Duration</span>
-      <span class="text-lg font-semibold leading-[140%] text-muted text-right">Net errs</span>
-      <span class="text-lg font-semibold leading-[140%] text-muted text-right">When</span>
+  <div class="pf-p-8 pf-border pf-border-subtle pf-rounded-2xl pf-bg-surface pf-flex pf-flex-col pf-gap-6">
+    <div class="pf-grid pf-grid-runs pf-gap-4 pf-items-center">
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted">URL / Scenario</span>
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted">Status</span>
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted pf-text-right">HTTP</span>
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted pf-text-right">Duration</span>
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted pf-text-right">Net errs</span>
+      <span class="pf-text-lg pf-font-semibold pf-leading-normal pf-text-muted pf-text-right">When</span>
     </div>
 
-    <hr class="border-subtle">
+    <hr>
 
     <% if @runs.none? %>
-      <p class="text-xl font-normal text-muted">No runs found.</p>
+      <p class="pf-text-xl pf-font-normal pf-text-muted">No runs found.</p>
     <% end %>
 
     <% @runs.each_with_index do |run, i| %>
-      <div class="grid grid-cols-[2fr_1fr_1fr_1fr_1fr_1fr] gap-4 items-center">
-        <div class="flex flex-col gap-0.5">
-          <%= link_to synthetic_run_path(run), class: "text-xl font-normal leading-[140%] text-primary underline truncate" do %>
+      <div class="pf-grid pf-grid-runs pf-gap-4 pf-items-center">
+        <div class="pf-flex pf-flex-col pf-gap-0-5">
+          <%= link_to synthetic_run_path(run), class: "pf-text-xl pf-font-normal pf-leading-normal pf-text-primary pf-underline pf-truncate" do %>
             <%= run.scenario_name || run.url %>
           <% end %>
           <% if run.scenario_name.present? %>
-            <span class="text-sm font-normal text-muted"><%= run.url %></span>
+            <span class="pf-text-sm pf-font-normal pf-text-muted"><%= run.url %></span>
           <% end %>
         </div>
 
-        <span class="<%= run.ok? ? 'text-primary' : 'text-error' %> text-xl font-semibold leading-[140%]">
+        <span class="<%= run.ok? ? 'pf-text-primary' : 'pf-text-error' %> pf-text-xl pf-font-semibold pf-leading-normal">
           <%= run.status.capitalize %>
         </span>
 
-        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.http_status || "—" %></span>
-        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.duration_ms ? "#{run.duration_ms}ms" : "—" %></span>
-        <span class="text-xl font-normal leading-[140%] text-neutral-900 text-right"><%= run.network_error_count %></span>
-        <span class="text-xl font-normal leading-[140%] text-muted text-right"><%= time_ago_in_words(run.created_at) %> ago</span>
+        <span class="pf-text-xl pf-font-normal pf-leading-normal pf-text-body pf-text-right"><%= run.http_status || "—" %></span>
+        <span class="pf-text-xl pf-font-normal pf-leading-normal pf-text-body pf-text-right"><%= run.duration_ms ? "#{run.duration_ms}ms" : "—" %></span>
+        <span class="pf-text-xl pf-font-normal pf-leading-normal pf-text-body pf-text-right"><%= run.network_error_count %></span>
+        <span class="pf-text-xl pf-font-normal pf-leading-normal pf-text-muted pf-text-right"><%= time_ago_in_words(run.created_at) %> ago</span>
       </div>
 
       <% unless i == @runs.size - 1 %>
-        <hr class="border-subtle">
+        <hr>
       <% end %>
     <% end %>
   </div>

data/app/views/perchfall/rails/synthetic_runs/show.html.erb

@@ -1,65 +1,65 @@
-<div class="flex flex-col gap-6 w-full">
-  <div class="flex flex-row items-center gap-4">
-    <%= link_to synthetic_runs_path, class: "text-muted hover:text-primary text-lg w-full" do %>
+<div class="pf-flex pf-flex-col pf-gap-6 pf-w-full">
+  <div class="pf-flex pf-flex-row pf-items-center pf-gap-4">
+    <%= link_to synthetic_runs_path, class: "pf-text-muted pf-hover:pf-text-primary pf-text-lg pf-w-full" do %>
       &larr; All runs
     <% end %>
   </div>
-  <div class="flex flex-row items-center gap-4">
-    <h2 class="text-5xl font-extrabold leading-[120%] text-primary w-full">
+  <div class="pf-flex pf-flex-row pf-items-center pf-gap-4">
+    <h2 class="pf-text-5xl pf-font-extrabold pf-leading-tight pf-text-primary pf-w-full">
       <%= @run.scenario_name.presence || @run.url %>
     </h2>
   </div>
 
-  <div class="flex flex-col md:flex-row gap-4 self-stretch items-start">
+  <div class="pf-flex pf-flex-col pf-md:pf-flex-row pf-gap-4 pf-self-stretch pf-items-start">
     <%# Summary card %>
-    <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-6 flex-1">
-      <h3 class="text-3xl font-extrabold leading-[120%] text-primary">Summary</h3>
+    <div class="pf-p-8 pf-border pf-border-subtle pf-rounded-2xl pf-bg-surface pf-flex pf-flex-col pf-gap-6 pf-flex-1">
+      <h3 class="pf-text-3xl pf-font-extrabold pf-leading-tight pf-text-primary">Summary</h3>
 
-      <dl class="flex flex-col gap-4">
-        <div class="grid grid-cols-2 gap-4">
-          <dt class="text-lg font-semibold text-muted">Status</dt>
-          <dd class="text-xl font-semibold <%= @run.ok? ? 'text-primary' : 'text-error' %>">
+      <dl class="pf-flex pf-flex-col pf-gap-4">
+        <div class="pf-grid pf-grid-summary pf-gap-4">
+          <dt class="pf-text-lg pf-font-semibold pf-text-muted">Status</dt>
+          <dd class="pf-text-xl pf-font-semibold <%= @run.ok? ? 'pf-text-primary' : 'pf-text-error' %>">
             <%= @run.status.capitalize %>
           </dd>
         </div>
-        <hr class="border-subtle">
-        <div class="grid grid-cols-2 gap-4">
-          <dt class="text-lg font-semibold text-muted">Scenario</dt>
-          <dd class="text-xl font-normal text-neutral-900 break-all"><%= @run.scenario_name %></dd>
+        <hr>
+        <div class="pf-grid pf-grid-summary pf-gap-4">
+          <dt class="pf-text-lg pf-font-semibold pf-text-muted">Scenario</dt>
+          <dd class="pf-text-xl pf-font-normal pf-text-body pf-break-all"><%= @run.scenario_name %></dd>
         </div>
-        <hr class="border-subtle">
+        <hr>
         <% if @run.scenario_name.present? %>
-          <div class="grid grid-cols-2 gap-4">
-            <dt class="text-lg font-semibold text-muted">URL</dt>
-            <dd class="text-xl font-normal text-neutral-900"><%= @run.url %></dd>
+          <div class="pf-grid pf-grid-summary pf-gap-4">
+            <dt class="pf-text-lg pf-font-semibold pf-text-muted">URL</dt>
+            <dd class="pf-text-xl pf-font-normal pf-text-body"><%= @run.url %></dd>
           </div>
-          <hr class="border-subtle">
+          <hr>
         <% end %>
-        <div class="grid grid-cols-2 gap-4">
-          <dt class="text-lg font-semibold text-muted">HTTP status</dt>
-          <dd class="text-xl font-normal text-neutral-900"><%= @run.http_status || "—" %></dd>
+        <div class="pf-grid pf-grid-summary pf-gap-4">
+          <dt class="pf-text-lg pf-font-semibold pf-text-muted">HTTP status</dt>
+          <dd class="pf-text-xl pf-font-normal pf-text-body"><%= @run.http_status || "—" %></dd>
         </div>
-        <hr class="border-subtle">
-        <div class="grid grid-cols-2 gap-4">
-          <dt class="text-lg font-semibold text-muted">Duration</dt>
-          <dd class="text-xl font-normal text-neutral-900"><%= @run.duration_ms ? "#{@run.duration_ms}ms" : "—" %></dd>
+        <hr>
+        <div class="pf-grid pf-grid-summary pf-gap-4">
+          <dt class="pf-text-lg pf-font-semibold pf-text-muted">Duration</dt>
+          <dd class="pf-text-xl pf-font-normal pf-text-body"><%= @run.duration_ms ? "#{@run.duration_ms}ms" : "—" %></dd>
         </div>
-        <hr class="border-subtle">
-        <div class="grid grid-cols-2 gap-4">
-          <dt class="text-lg font-semibold text-muted">Run at</dt>
-          <dd class="text-xl font-normal text-neutral-900"><%= @run.created_at.strftime("%b %-d, %Y at %H:%M UTC") %></dd>
+        <hr>
+        <div class="pf-grid pf-grid-summary pf-gap-4">
+          <dt class="pf-text-lg pf-font-semibold pf-text-muted">Run at</dt>
+          <dd class="pf-text-xl pf-font-normal pf-text-body"><%= @run.created_at.strftime("%b %-d, %Y at %H:%M UTC") %></dd>
         </div>
       </dl>
     </div>
 
-    <div class="flex flex-col gap-4 flex-1">
+    <div class="pf-flex pf-flex-col pf-gap-4 pf-flex-1">
       <% if @run.network_errors.any? %>
         <%= render "network_error_card",
               errors:        @run.network_errors,
               title:         "Network Errors",
               count:         @run.network_error_count,
-              heading_color: "text-primary",
-              count_color:   "text-error",
+              heading_color: "pf-text-primary",
+              count_color:   "pf-text-error",
               dimmed:        false %>
       <% end %>
 
@@ -68,15 +68,15 @@
               errors:        @run.console_errors,
               title:         "Console Errors",
               count:         @run.console_error_count,
-              heading_color: "text-primary",
-              count_color:   "text-error",
+              heading_color: "pf-text-primary",
+              count_color:   "pf-text-error",
               dimmed:        false %>
       <% end %>
 
       <% if @run.network_errors.none? && @run.console_errors.none? %>
-        <div class="p-8 border border-solid border-neutral-150 rounded-2xl bg-neutral-0 flex flex-col gap-2">
-          <h3 class="text-3xl font-extrabold leading-[120%] text-primary">No errors</h3>
-          <p class="text-xl font-normal text-muted">This run completed cleanly.</p>
+        <div class="pf-p-8 pf-border pf-border-subtle pf-rounded-2xl pf-bg-surface pf-flex pf-flex-col pf-gap-2">
+          <h3 class="pf-text-3xl pf-font-extrabold pf-leading-tight pf-text-primary">No errors</h3>
+          <p class="pf-text-xl pf-font-normal pf-text-muted">This run completed cleanly.</p>
         </div>
       <% end %>
 
@@ -85,8 +85,8 @@
               errors:        @run.ignored_network_errors,
               title:         "Ignored Network Errors",
               count:         @run.ignored_network_errors.size,
-              heading_color: "text-muted",
-              count_color:   "text-subtle",
+              heading_color: "pf-text-muted",
+              count_color:   "pf-text-subtle",
               dimmed:        true %>
       <% end %>
 
@@ -95,8 +95,8 @@
               errors:        @run.ignored_console_errors,
               title:         "Ignored Console Errors",
               count:         @run.ignored_console_errors.size,
-              heading_color: "text-muted",
-              count_color:   "text-subtle",
+              heading_color: "pf-text-muted",
+              count_color:   "pf-text-subtle",
               dimmed:        true %>
       <% end %>
     </div>

data/lib/generators/perchfall/rails/templates/initializer.rb

@@ -8,4 +8,34 @@ Perchfall::Rails.configure do |config|
 
   # ActiveJob queue name for synthetic run jobs. Defaults to :synthetic.
   # config.queue_name = :synthetic
+
+  # Optional host stylesheet (no extension) loaded after the engine CSS.
+  # Use to override --perchfall-* CSS custom properties for theming.
+  # config.overrides_stylesheet = "perchfall_rails_overrides"
+
+  # Optional callable invoked after each SyntheticRun is persisted. Receives
+  # the persisted run as a single positional argument. Fires on the happy
+  # path and on RunJob's error rescues — once per persisted run, which under
+  # ActiveJob retries means once per attempt. Use run.id to route downstream
+  # work to that specific persisted run (e.g. SomeJob.perform_later(run.id))
+  # — each retry attempt persists a distinct id, so run.id does NOT dedup
+  # across attempts. The engine provides no cross-attempt key today, so
+  # handlers that need once-per-failure-event semantics (notifications,
+  # ticket-opens) should be idempotent on the host's natural keys, or
+  # should accept at-least-once. Exceptions are rescued and logged; they
+  # do not interrupt the pipeline. See ADR 0006.
+  # config.after_persist = ->(run) { SomeJob.perform_later(run.id) if run.failed? }
+
+  # Optional name of a host module the engine includes into
+  # Perchfall::Rails::SyntheticRun from a config.to_prepare block on boot
+  # (and re-includes on every code reload in development). Use to declare
+  # host-side associations, scopes, or callbacks (`belongs_to :user`, &c.).
+  # The named module must be autoloadable.
+  # Callbacks added here run as part of the engine's SyntheticRun.create!; if
+  # one raises, the create fails, the job dies, no SyntheticRun is written
+  # (not even an error row), and after_persist does not fire. Reserve extension
+  # callbacks for declarations and logic that has been hardened against
+  # raising; for observability-style side effects, use after_persist. See
+  # ADR 0007.
+  # config.synthetic_run_extension = "SyntheticRunExtension"
 end

data/lib/perchfall/rails/configuration.rb

@@ -3,11 +3,14 @@
 module Perchfall
   module Rails
     class Configuration
-      attr_accessor :base_controller, :queue_name
+      attr_accessor :after_persist, :base_controller, :overrides_stylesheet, :queue_name, :synthetic_run_extension
 
       def initialize
+        @after_persist = nil
         @base_controller = "ApplicationController"
+        @overrides_stylesheet = nil
         @queue_name = :synthetic
+        @synthetic_run_extension = nil
       end
     end
 

data/lib/perchfall/rails/engine.rb

@@ -21,6 +21,14 @@ module Perchfall
           Perchfall::Rails::RegexpSerializer,
           Perchfall::Rails::IgnoreRuleSerializer
         )
+
+        # ADR 0007: include the host-provided extension module into SyntheticRun.
+        # config.to_prepare fires after all host initializers (so the config is
+        # set), after eager_load in production (so the model is loaded), and on
+        # every code reload in development (so the include re-applies after
+        # Zeitwerk swaps the class). Module#include is idempotent on its own.
+        extension = Perchfall::Rails.configuration.synthetic_run_extension
+        Perchfall::Rails::SyntheticRun.include(extension.constantize) if extension
       end
 
       initializer "perchfall.node_path" do
@@ -28,6 +36,15 @@ module Perchfall
         existing = ENV["NODE_PATH"].to_s
         ENV["NODE_PATH"] = [local_node_modules, existing].reject(&:empty?).join(":")
       end
+
+      initializer "perchfall.rails.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << root.join("app/assets/stylesheets").to_s
+          if app.config.assets.respond_to?(:precompile)
+            app.config.assets.precompile << "perchfall/rails/application.css"
+          end
+        end
+      end
     end
   end
 end

data/lib/perchfall/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Perchfall
   module Rails
-    VERSION = "0.2.2"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: perchfall-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Yossef Mendelssohn
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pagy
@@ -66,7 +67,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- app/assets/tailwind/perchfall_rails/engine.css
+- app/assets/stylesheets/perchfall/rails/application.css
 - app/controllers/perchfall/rails/synthetic_runs_controller.rb
 - app/jobs/perchfall/rails/run_job.rb
 - app/models/perchfall/rails/synthetic_run.rb
@@ -123,7 +124,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Rails engine for integrating Perchfall synthetic monitoring
 test_files: []

data/app/assets/tailwind/perchfall_rails/engine.css

@@ -1 +0,0 @@
-@source "../../../views/**/*.html.erb";