product_tours 0.3.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 397e2fbd273b707e9a16302852704ed8e5cc6daf410f3255fe3fa819047163b8
-  data.tar.gz: c040cac638d52a7484f4ef109732211e181f0b103bdbcd938f0d6c3c7b8d10e1
+  metadata.gz: 8c3fecc3261d2acf6fb9267139897e7e0c4c6fa9dd3a8d52466380f2fe040c9e
+  data.tar.gz: 0112d06e16cd88171023f3dd32988348e8dd642334db67c5f33cb1c4194363a4
 SHA512:
-  metadata.gz: b22e2391759e9a49d90728b9709650e5f0f2d1001fdf36d71e4c8d2c494e853007f70794b93c92762363502872f024970cf62660fa4639702aac82c854b2f9ab
-  data.tar.gz: e2ceef66890c00c8a5f3f9293f946e35c366215b08a584a52e49408cb858f245affe2eab62caece0f1b7286f5b5944da9358f3315777b95208e962e715b83b2f
+  metadata.gz: 670382b8c322e3803495d1a294aebfc21036aa69400fb7e9055a98de1243c8ba1e716dadacfcd0909885cbd18e77914f7114f54cb2caf1b388e8e9e386ec00da
+  data.tar.gz: 54eb9697c17e7fd50f170dd21e7d15ee994459acd4b7151d98def0f2622586ca40f913dba9f451ceb7676ac5c79cb33bb946b55469e2c342372c83ba4fecc189

data/AGENTS.md

@@ -5,7 +5,7 @@ Instructions for coding agents. Two audiences:
 - **[Installing product_tours into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add product tours, onboarding guides, or video tutorials.
 - **[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 uploaded videos, Action Text only for rich descriptions — both optional and both degrade rather than raise.
+Requirements: Ruby >= 3.2, Rails >= 7.1 and < 9. Active Storage only for uploaded videos, Action Text only for rich descriptions — both optional and both degrade rather than raise.
 
 If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show product_tours)/AGENTS.md"`.
 
@@ -21,7 +21,7 @@ bin/rails generate product_tours:install
 bin/rails db:migrate
 ```
 
-The generator writes `config/initializers/product_tours.rb`, one migration (`product_tours_posts`), and `mount_product_tours at: "/product_tours"` into `config/routes.rb`. **In development the migration also inserts working demo tutorials**, so the modal has something to open before anyone has written content. Read the initializer it wrote — it is the source of truth over any summary of it, including this file.
+The generator writes `config/initializers/product_tours.rb`, one migration (`product_tours_tours`), and `mount_product_tours at: "/product_tours"` into `config/routes.rb`. **In development the migration also inserts working demo tutorials**, so the modal has something to open before anyone has written content. Read the initializer it wrote — it is the source of truth over any summary of it, including this file.
 
 ### 2. Wire the three things the generator cannot
 
@@ -69,7 +69,7 @@ Then in the running app: open `/product_tours`, confirm the demo tutorials are l
 
 ### Tutorials are content, not code
 
-A tutorial is a row in `product_tours_posts`, written and published in the mounted dashboard. **Do not create tutorials from host-app migrations, seeds, or fixtures** — that is not how this gem is meant to be used, and it puts editorial content in schema history. If the app needs sample content, `bin/rails product_tours:seed_demo` is the supported path.
+A tutorial is a row in `product_tours_tours`, written and published in the mounted dashboard. **Do not create tutorials from host-app migrations, seeds, or fixtures** — that is not how this gem is meant to be used, and it puts editorial content in schema history. If the app needs sample content, `bin/rails product_tours:seed_demo` is the supported path.
 
 What a tutorial carries: a `key`, a title, an optional rich description, an optional video, and at most one primary action (a URL, or the key of the next tutorial — that link is what makes a walkthrough). Keys must match `/\A[a-z0-9]+(?:[._-][a-z0-9]+)*\z/` — lowercase, digits, and `. _ -` as separators. `Billing Setup` and `billingSetup` are invalid; `billing_setup` and `billing.step-1` are fine. `status` is `draft` or `published`, and the key is unique **per locale**, which is how translations work: one row per language for the same key, with locale fallback at resolve time.
 
@@ -112,7 +112,7 @@ exceptions without breaking the visitor flow. Keep it fast or enqueue a job.
 - **Do not create or edit tutorials in code** (see above).
 - **Do not add provider hosts to `frame-src` by hand** — the engine already does it.
 - **Do not serve uploaded videos by blob URL** — the gated media route exists so a leaked signed URL cannot hand over your content.
-- **Do not install Active Storage or Action Text "to make it work"** unless the app actually wants uploads or rich text. Both are optional; the gem checks for them (`Post.video_upload_supported?`, `Post.description_supported?`) and simply offers less.
+- **Do not install Active Storage or Action Text "to make it work"** unless the app actually wants uploads or rich text. Both are optional; the gem checks for them (`Tour.video_upload_supported?`, `Tour.description_supported?`) and simply offers less.
 
 ### Configuration
 
@@ -152,13 +152,19 @@ There are seven options. That is the whole surface.
 
 ## Working on the gem itself
 
+The development toolchain is pinned to Ruby 4.0.5 in `mise.toml`. Do not use
+macOS's `/usr/bin/ruby`. In shells, hooks, or automation where mise activation
+is uncertain, explicitly prepend the configured Ruby, for example
+`PATH="$(mise where ruby)/bin:$PATH" bundle exec rake test`.
+
 ```bash
 bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rake test:system     # real Next/Back/finish flow in headless Chrome
 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, `Post`, dashboard views · `lib/product_tours/` config, widget JS, seeds, engine, CSP patch · `lib/generators/product_tours/install/` the one generator · `config/locales/` 26 locales · `test/` minitest with `test/dummy` as the host app.
+Layout: `app/` controllers, `Tour`, dashboard views · `lib/product_tours/` config, widget JS, seeds, engine, CSP patch · `lib/generators/product_tours/install/` the one generator · `config/locales/` 26 locales · `test/` minitest with `test/dummy` as the host app.
 
 Conventions this codebase holds to — follow them rather than the first thing that works:
 

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-08-11
+
+- **The record is a tour, all the way down.** `ProductTours::Post` is now
+  `ProductTours::Tour`; fresh installs create `product_tours_tours`, linked
+  steps use `action_tour_key`, lifecycle payloads use `tour_id`, the widget
+  resolves `/widget/tour`, and dashboard resources live under `/tours`. There
+  is deliberately no `Post` compatibility alias: v1 is the point where the
+  public vocabulary becomes honest and then freezes under semantic versioning.
+- Existing 0.3.x installs must rename the `product_tours_posts` table to
+  `product_tours_tours` and its `action_post_key` column to `action_tour_key`
+  before booting 1.0.0. Host code must replace `ProductTours::Post`, old
+  dashboard paths, and the old `post_id` lifecycle payload key. Fresh installs
+  need no upgrade migration.
+- Added one headless-Chrome system test that opens a linked walkthrough, moves
+  Next and Back, and finishes it. Capybara and Selenium are development/test
+  dependencies only; the runtime gem API and dependency surface are unchanged.
+- Refreshed the PRD's shipped version, database-index contract, acceptance
+  wording, compatibility wording, and the missing release comparison links.
+- **Uploaded videos now stay behind the engine gate.** The media controller
+  streams full and byte-range responses directly after authorization instead of
+  redirecting to a reusable signed Active Storage blob URL. Hosts gain the
+  privacy promised by the existing docs without losing playback or seeking.
+- **Hosts that load Action View from an initializer boot normally.**
+  `WidgetHelper` is required from `lib` before the engine registers its Action
+  View hook; a dummy-host initializer reproduces that early load on every test
+  boot. `product_tours_tag` is unchanged.
+- The documented model, configuration, route/helper, key, event, and callback
+  surface is now the stable 1.x API. Added a security policy with explicit
+  content, event, deletion, and retention boundaries.
+- Supported combinations are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1.
+  Rails now has a `< 9` upper bound. Release validation builds the gem, verifies
+  RubyGems indexing, and creates the GitHub Release. Generator tests write only
+  under ignored root `tmp/`, so tests cannot contaminate later lint runs.
+
 ## [0.3.3] - 2026-08-08
 
 - **The demo walkthrough is now a tour of Product Tours itself.** Its linked
@@ -36,7 +70,7 @@
   are logged and never turn a working tutorial action into a visitor-facing
   failure.
 
-## 0.3.0
+## [0.3.0] - 2026-08-05
 
 - **One design system across the family.** The stylesheet now opens with a
   shared core — the colour tokens, `.page-head`, `.tabs`, `.filters`, `.card`,
@@ -61,7 +95,17 @@
   button on one line, and a `code.key` truncates inside a list row instead of
   wrapping over three lines.
 
-## 0.2.0
+## [0.2.2] - 2026-08-04
+
+- Restored the intended dashboard width after CSS scoping and documented the
+  shared five-gem family conventions.
+
+## [0.2.1] - 2026-08-04
+
+- Restored the dashboard layout rules that the new scoped wrapper had
+  accidentally overridden.
+
+## [0.2.0] - 2026-08-04
 
 - **`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
@@ -156,8 +200,15 @@
 - Removed generic tutorial duplication now that translations provide the only
   intentional content-copying workflow.
 
-[Unreleased]: https://github.com/yshmarov/product_tours/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/yshmarov/product_tours/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/yshmarov/product_tours/compare/v0.3.3...v1.0.0
+[0.3.3]: https://github.com/yshmarov/product_tours/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/yshmarov/product_tours/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/yshmarov/product_tours/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/yshmarov/product_tours/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/yshmarov/product_tours/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/yshmarov/product_tours/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/yshmarov/product_tours/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/yshmarov/product_tours/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/yshmarov/product_tours/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/yshmarov/product_tours/releases/tag/v0.1.0

data/README.md

@@ -51,7 +51,7 @@ small set of working tutorials so you can try the modal immediately.
 > The dashboard defaults to **development only**. Set `authorize_admin` before
 > deploying it — see [Configure](#configure).
 
-Ruby >= 3.2 · Rails >= 7.1 · Active Storage only for uploaded videos · Action
+Ruby >= 3.2 · Rails >= 7.1 and < 9 · Active Storage only for uploaded videos · Action
 Text only for rich descriptions.
 
 Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
@@ -213,7 +213,7 @@ key. Running the task again updates those records instead of duplicating them.
   <button type="button" data-product-tour="demo_direct_video">Open the direct video tutorial</button>
   <button type="button" data-product-tour="demo_getting_started">Open the getting started guide</button>
   <button type="button" data-product-tour="demo_draft">Try an unpublished tutorial</button>
-  <button type="button" data-product-tour="demo_missing_post">Try a missing tutorial</button>
+  <button type="button" data-product-tour="demo_missing_tour">Try a missing tutorial</button>
 </div>
 <%= product_tours_tag %>
 ```
@@ -296,7 +296,10 @@ table. It emits three Rails notifications:
 | `product_tours.dismissed` | The visitor closed it before using the primary action |
 | `product_tours.completed` | The visitor used the primary action |
 
-Payload: `post_id`, `key`, `locale`, query-free `page_url`, and `source`.
+Payload: `tour_id`, `key`, `locale`, query-free `page_url`, and `source`.
+The `source` vocabulary is also stable: viewed events use `modal`,
+`linked_tour`, or `back`; completed events use `action` or `linked_tour`; and
+dismissed events use `modal`.
 
 Bridge them to Ahoy—or anything else—in your host app:
 
@@ -335,8 +338,51 @@ Invalid, missing, draft, or disabled keys open nothing for the visitor.
 
 No end user gets a Rails error page because somebody renamed a tutorial.
 
+## Compatibility and public API
+
+The following are the model and integration contracts that 1.x will keep
+stable under semantic versioning:
+
+- `ProductTours::Tour`, including `key`, `locale`, `status`, `title`,
+  `video_url`, `video_metadata`, `action_label`, `action_url`,
+  `action_tour_key`, timestamps, `STATUSES`, status methods/scopes,
+  `newest_first`, `action_tour`, `description_supported?`,
+  `video_upload_supported?`, and optional rich-description/video behavior.
+- `ProductTours.configure` and the documented configuration options.
+- `mount_product_tours`, `product_tours_tag`, and `data-product-tour="key"`.
+- The tutorial key grammar and per-locale uniqueness contract.
+- `product_tours.viewed`, `product_tours.dismissed`, and
+  `product_tours.completed`, with `tour_id`, `key`, `locale`, query-free
+  `page_url`, and the documented `source` values.
+- `config.on_event(name, payload, request)` and
+  `product_tours.unresolved_trigger`, whose payload has `key`, `locale`,
+  query-free `page_url`, and one of `invalid_key`, `missing`, `unpublished`, or
+  `disabled` as its `reason`.
+
+Dashboard controllers, view partials, CSS classes, generated HTML, and widget
+implementation objects are private. Incompatible changes to the public list
+above wait for a new major version; a deprecation normally ships first.
+
+### Upgrading from 0.3.x
+
+Version 1.0.0 is the deliberate terminology break from the pre-1.0 API.
+Existing installs must rename their generated table and linked-step column:
+
+```ruby
+rename_table :product_tours_posts, :product_tours_tours
+rename_column :product_tours_tours, :action_post_key, :action_tour_key
+```
+
+Replace `ProductTours::Post` with `ProductTours::Tour`, `post_id` event payloads
+with `tour_id`, and any dashboard links under `/product_tours/posts` with
+`/product_tours/tours`. Fresh installs already generate the new schema.
+
 ## Security
 
+See [SECURITY.md](https://github.com/yshmarov/product_tours/blob/main/SECURITY.md)
+for supported versions, private vulnerability reporting, the stored-data and
+lifecycle-event boundary, and deletion/retention guidance.
+
 - Admin authorization runs server-side on every dashboard request.
 - Public resolution returns only published tutorials allowed by `enabled`.
 - Video providers are an HTTPS allowlist; unsupported URLs render no iframe.
@@ -346,6 +392,11 @@ No end user gets a Rails error page because somebody renamed a tutorial.
   `frame-src` without replacing the host policy.
 - For direct videos on another origin, allow that origin in the host app's
   `media-src` policy.
+- Uploaded videos stream from the gated engine route with byte-range support and
+  private, non-stored responses; no reusable signed blob URL is exposed.
+- The host owns retention and deletion. Remove a row with
+  `ProductTours::Tour.find(id).destroy!`, then apply object-store, backup,
+  analytics, cache, and export retention policies separately.
 
 ## What it doesn't do
 
@@ -360,10 +411,15 @@ stack owns persistence and reporting. The gem stays small enough to understand.
 
 ```bash
 bundle exec rake test
+bundle exec rake test:system
 bundle exec rubocop
 ```
 
-CI runs Rails 7.1 / 7.2 / 8.0 / 8.1 against Ruby 3.2 / 3.3 / 3.4.
+The normal suite covers the Rails engine contract. The system task drives the
+real widget through Next, Back, and finish in headless Chrome. CI runs Rails
+7.1, 7.2, 8.0, and 8.1 against Ruby 3.2 through 4.0, plus that browser test once
+on Ruby 4.0. Rails 9 is outside the 1.x dependency contract until it passes the
+suite.
 
 Bug reports and pull requests are welcome. The most useful report is a real
 Rails app and the exact point where installation or authoring felt confusing.

data/Rakefile

@@ -5,7 +5,15 @@ require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |task|
   task.libs << 'test'
-  task.pattern = 'test/**/*_test.rb'
+  task.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*')
+end
+
+namespace :test do
+  desc 'Run browser (system) tests'
+  Rake::TestTask.new(:system) do |task|
+    task.libs << 'test'
+    task.test_files = FileList['test/system/**/*_test.rb']
+  end
 end
 
 task default: :test

data/SECURITY.md

@@ -0,0 +1,50 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest 1.x version. If a report also
+affects the newest 0.x release, a backport may be published when the fix is
+small and the affected application cannot upgrade immediately.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/product_tours/security/advisories/new)
+and include the affected version, a minimal reproduction, impact, and any known
+workaround. Credentials, session cookies, private application URLs, customer
+content, uploaded videos, and production database contents should not be
+included.
+
+Public disclosure should wait until a fixed version is available and affected
+users have had a reasonable opportunity to upgrade.
+
+## Data and deployment boundary
+
+The public widget resolves only published tours allowed by `config.enabled`,
+which defaults to everyone because showing tutorials in production is the gem's
+purpose. The dashboard is separately protected by `authorize_admin` and fails
+closed outside development until the host explicitly grants access.
+
+A tour can store its key, locale, status, title, video URL and metadata, primary
+action label/destination, timestamps, optional Action Text description, and an
+optional Active Storage video. Uploaded videos stream through the engine's
+authorization gate with private, non-stored responses; the route never redirects
+to a reusable signed blob URL. Hosts still own the storage service, bucket
+policy, backups, retention period, access controls, and incident response.
+
+The gem emits lifecycle events containing a tour id, key, locale, query-free
+page URL, and source, but does not persist visitor events, identity, progress,
+or completion. A host's `on_event` hook receives the raw request; anything it
+derives or persists is part of the host application's own privacy boundary.
+
+Delete a tour with ordinary Active Record when an application policy requires
+erasure:
+
+```ruby
+ProductTours::Tour.find(id).destroy!
+```
+
+That removes the record and lets Rails apply the configured Action Text and
+Active Storage attachment lifecycles. Confirm deletion separately in object
+storage, replicas, backups, caches, analytics, and exports; deleting the live
+row does not rewrite them.

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

@@ -30,10 +30,10 @@ module ProductTours
       ProductTours.locale(request)
     end
 
-    def find_post_by_locale(scope, key)
+    def find_tour_by_locale(scope, key)
       locales = [current_product_tours_locale, I18n.default_locale.to_s].uniq
-      posts = scope.where(locale: locales, key: key).index_by(&:locale)
-      locales.filter_map { |locale| posts[locale] }.first
+      tours = scope.where(locale: locales, key: key).index_by(&:locale)
+      locales.filter_map { |locale| tours[locale] }.first
     end
 
     def clean_page_url(value)

data/app/controllers/product_tours/dashboard_controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ProductTours
-  # Root of the STAFF surface: the post editor and its list.
+  # Root of the STAFF surface: the tour editor and its list.
   #
   # Inherits from `config.base_controller_class` — by default a plain
   # ActionController::Base, which is why `authorize_admin` exists. Point it at

data/app/controllers/product_tours/interactions_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ProductTours
+  class InteractionsController < ApplicationController
+    SIGNALS = %w[viewed dismissed completed].freeze
+
+    def resolve
+      key = params[:key].to_s
+      return handle_unresolved_trigger(key, :disabled) unless ProductTours.enabled?(request)
+      return handle_unresolved_trigger(key, :invalid_key) unless key.match?(Tour::KEY_FORMAT)
+
+      tour = find_tour_by_locale(Tour.all, key)
+      return handle_unresolved_trigger(key, :missing) unless tour
+      return handle_unresolved_trigger(key, :unpublished) unless tour.published?
+
+      render json: tour_payload(tour)
+    end
+
+    def signal
+      return head :forbidden unless ProductTours.enabled?(request)
+
+      action = params[:event_action].to_s
+      return head :unprocessable_entity unless SIGNALS.include?(action)
+
+      tour = find_tour_by_locale(Tour.published, params[:key].to_s)
+      return head :not_found unless tour
+
+      payload = {
+        tour_id: tour.id,
+        key: tour.key,
+        locale: tour.locale,
+        page_url: clean_page_url(params[:page_url]),
+        source: params[:source].to_s.presence
+      }
+      event_name = "product_tours.#{action}"
+      ActiveSupport::Notifications.instrument(event_name, payload)
+      notify_host(event_name, payload)
+      head :no_content
+    end
+
+    private
+
+    def notify_host(event_name, payload)
+      ProductTours.config.on_event.call(event_name, payload, request)
+    rescue StandardError => e
+      Rails.logger.error("product_tours: on_event hook raised #{e.class}: #{e.message}")
+    end
+
+    def tour_payload(tour)
+      video = tour.resolved_video
+      video[:url] = media_path(tour) if video&.dig(:kind) == 'upload'
+      {
+        key: tour.key,
+        locale: tour.locale,
+        title: tour.title,
+        descriptionHtml: description_html(tour),
+        video: video,
+        action: {
+          label: tour.action_label.presence || default_action_label(tour),
+          url: tour.action_url.presence,
+          tourKey: tour.action_tour_key.presence
+        }
+      }
+    end
+
+    def default_action_label(tour)
+      key = tour.action_tour_key.present? ? :next : :done
+      I18n.t(key, scope: :product_tours, default: key.to_s.humanize)
+    end
+
+    def description_html(tour)
+      return unless Tour.description_supported? && tour.description.present?
+
+      tour.description.body.to_s
+    end
+  end
+end

data/app/controllers/product_tours/media_controller.rb

@@ -2,13 +2,32 @@
 
 module ProductTours
   class MediaController < ApplicationController
+    include ActiveStorage::Streaming if defined?(::ActiveStorage::Streaming)
+
     def show
-      post = Post.find(params[:id])
-      allowed = ProductTours.admin?(request) || (ProductTours.enabled?(request) && post.published?)
+      tour = Tour.find(params[:id])
+      allowed = ProductTours.admin?(request) || (ProductTours.enabled?(request) && tour.published?)
       return head :forbidden unless allowed
-      return head :not_found unless post.uploaded_video?
+      return head :not_found unless tour.uploaded_video?
+
+      stream(tour.video.blob)
+    end
+
+    private
 
-      redirect_to main_app.rails_blob_path(post.video, disposition: 'inline')
+    # Keep the browser on the authorized engine URL while retaining the byte
+    # range behavior video playback and seeking need. Active Storage's own
+    # streaming concern supports both full and ranged responses without a
+    # permanent signed blob URL escaping this controller's gate.
+    def stream(blob)
+      response.headers['Cache-Control'] = 'private, no-store'
+      if request.headers['Range'].present?
+        send_blob_byte_range_data blob, request.headers['Range']
+      else
+        response.headers['Accept-Ranges'] = 'bytes'
+        response.headers['Content-Length'] = blob.byte_size.to_s
+        send_blob_stream blob, disposition: 'inline'
+      end
     end
   end
 end