studio-engine 0.86.0 → 0.88.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6007443c9eeb21b16c521e76c956e5c05755ff0c264bbbf0f387f04ee79bd8
-  data.tar.gz: 1c6dd57eaf48aa3900de531b440766c8cb69281172f6c8a1aeb0daae45b7ca1b
+  metadata.gz: e16f65ea44055886fea1ffb0743a9415caa612f858caa0ff7dabb7c87beeeb15
+  data.tar.gz: 9690ad40a9e766646995ddfa1c69c8c22191e3509bb944d5c184ea5c1a1b21e2
 SHA512:
-  metadata.gz: 9fe2eb18d609180eeaaf03be1cf497bfc1b57407266565b8328757de5dd7f7c0633d5c5a81ab244cb39e4be9a211080a903c2d0490e181cfa07e89aca4838f97
-  data.tar.gz: 997135fe0ac9f3aea6d0da57c0d8af31b95e49320464fda777f441479250edf81af4bdbd4e93043a971d406e1779f819a7490707e733621e156ad95432c1c204
+  metadata.gz: ae4786abebc9f1d9dc86cc3992f4a6f4225c4fceaa20b73fca12ddd43afad1e4d6ef2807a8d3302bdf2d811792995fdac42961a02c6b70637f8923e841e61402
+  data.tar.gz: 3ba6c43faf9e1f7a03596b70924fc099469d8c95ce967f63e4a2ba8f4f0da0112db6068e701e739fa7e3ce5435bd07ee456b2982fec91ebb9561a4bc3dd18b09

data/CHANGELOG.md

@@ -4,6 +4,71 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.88.0 — 2026-10-05
+
+### Added
+
+- **Surveys.** Define a survey in app code — `Studio.define_survey "first-game"
+  do ... end` in `config/surveys/*.rb`, loaded on boot and each reload — with six
+  question types (`emoji_scale`, `rating`, `choice`, `multi_choice`,
+  `short_text`, `long_text`), each with `required:` and `help:`. The engine
+  serves it at `GET /surveys/:slug`: one question per screen with a progress
+  bar, tap-to-advance, number keys and Enter, autosave of every answer, resume
+  where the respondent left off, a thank-you screen with the survey's
+  `next_action`, `prefers-reduced-motion` support, and a single-form fallback
+  without JavaScript. Answers are stored in the new `studio_survey_responses`
+  table (`Studio::SurveyResponse`) with a snapshot of each question's label and
+  the chosen option's label, so editing a survey never rewrites old responses.
+  **Opt in** with `config.draw_survey_routes = true`; **run
+  `bin/rails studio_engine:install:migrations && bin/rails db:migrate`** first.
+- **`config.survey_ref_resolver`** (`->(controller) { ref }`) attributes an email
+  arrival, and **`config.on_survey_completed`** (`->(response) { ... }`) runs once
+  when a response completes; a raising hook is logged, never shown. A survey
+  answers to a signed-in user, an attributed email arrival, or anyone when it
+  declares `allow_anonymous true`.
+- **The survey results panel at `/admin/surveys`**, admin-only: started,
+  completed and completion rate per survey; per-question distribution bars and
+  averages, a scrolling list of text answers with the respondent's username or
+  "anonymous"; date-range and completed-only filters; CSV export. **Opt in**
+  with `config.draw_admin_survey_routes = true`. See `docs/SURVEYS.md`.
+
+## 0.87.0 — 2026-10-04
+
+### Changed
+
+- **The site footer is on by default. An unset `config.site_footer` now renders
+  a footer wherever `studio_site_footer` is called**; before, it rendered
+  nothing. The default footer is built from what the engine already knows: the
+  app's name (the site identity's title, else `config.app_name`), its footer or
+  navbar logo, the © line, and a Privacy Policy and a Terms of Service link for
+  each of the routes named `privacy` and `terms` that the host has (a GET route
+  that needs no arguments; anything else is not linked). It has no address, no
+  map, no phone, no email, no tagline, no social row and no link columns, and
+  names no Leaflet. The rule for where it shows is unchanged. **An app that
+  sets `config.site_footer` to a Hash or a callable renders exactly what it did**,
+  and an app that does not call the helper is unaffected. A callable that
+  answers `nil` still declines the footer for that request.
+
+### Added
+
+- **`config.site_footer = false` turns the footer off.** It is the one opt-out,
+  and it is distinct from unset (`nil`), which is the default footer.
+  `Studio.site_footer_enabled?` and `Studio.site_footer_declared?` read the
+  three states.
+- **`config.site_footer_address`: the location, as one setting.** A Hash of the
+  facts' `address:` keys (`street:`, `city_line:`, `lat:`, `lng:`, and the
+  optional `zoom:` and `directions_url:`) gives the footer its Location band,
+  and its map when both coordinates are present, without writing the facts
+  callable. It applies to the default footer and to an app's own facts that
+  carry no address. An address in the app's own facts wins, whole, and
+  `address: false` there shows none.
+- **docs/NEW_APP_SETUP.md has a Site Footer step (§ 10)**, and its layout ends
+  with `<%= studio_site_footer %>`. The sections after it moved down by one.
+
+### Fixed
+
+- `address: false` in the footer's facts shows no address instead of raising.
+
 ## 0.86.0 — 2026-10-03
 
 ### Added

data/README.md

@@ -41,8 +41,9 @@ resolved.
 - **Site identity and link previews**: `Studio::SiteIdentity` holds the app's title, description and image, edited at `/admin/link_preview` beside a live unfurl card and read anywhere through `Studio.site_identity`. Every page unfurls with it unless it calls `link_preview image:, title:, description:`, and `Studio::LinkPreviewBots` serves preview fetchers a slim page under iMessage's 1 MiB limit. Adopt with `bin/rails g studio:site_identity`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).
 - **Public user page**: `/u/:username` shows a user's avatar and username (nothing else), and unfurls with their avatar, falling back to the site image. Link any username to it with `link_to_user_profile(user)` or `studio_user_profile_path(user)`. Opt in with `config.draw_public_user_routes = true`. See [`docs/PUBLIC_USER_PAGE.md`](docs/PUBLIC_USER_PAGE.md).
 - **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
-- **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer from `config.site_footer` (brand, social profiles, link columns, an address with a live map, legal links), every part optional. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).
+- **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer. It is on by default: with nothing configured it prints the app's name, logo and the legal links the app has routes for, and no address. `config.site_footer` declares the app's own facts (brand, social profiles, link columns, an address with a live map, legal links), every part optional; `config.site_footer_address` adds a location in one setting; `config.site_footer = false` turns the footer off. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).
 - **Booking**: a simple scheduler on Google Calendar appointment schedules, with or without the footer. With `config.booking_url`, `studio_booking_frame` embeds Google's booking page, `studio_booking_link` opens it in a popup, and `config.draw_booking_routes = true` draws `/schedule` (or name the app's own page with `config.booking_path`). `config.booking_crop` crops the frame to the slot picker at rest, from numbers `bin/booking-crop-measure` reads off the app's own schedule. See [`docs/BOOKING.md`](docs/BOOKING.md).
+- **Surveys**: define a survey in app code (`config/surveys/*.rb`, `Studio.define_survey`) with six question types — emoji scale, 1–5 rating, single and multiple choice, short and long text — and the engine serves it at `/surveys/:slug`: one question per screen, autosave, resume, keyboard shortcuts, and a no-JavaScript fallback. `config.on_survey_completed` and `config.survey_ref_resolver` let the app fire its own goals and attribute email arrivals. An admin panel at `/admin/surveys` breaks results down per question and exports CSV. Opt in with `config.draw_survey_routes = true` and `config.draw_admin_survey_routes = true`. See [`docs/SURVEYS.md`](docs/SURVEYS.md).
 
 ## Configuration
 
@@ -137,6 +138,8 @@ Set `Studio.draw_session_routes = true` to add the session-drift rehydrate endpo
 
 Set `Studio.draw_booking_routes = true` to add the booking page (`GET /schedule`, helper `studio_booking_path`) — off by default because mcritchie-studio draws its own `/schedule` until it adopts this one. An app that keeps its own booking page names it with `Studio.booking_path` instead ([`docs/BOOKING.md`](docs/BOOKING.md)).
 
+Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys/:slug`, helper `studio_survey_path`) and `Studio.draw_admin_survey_routes = true` to add the admin results panel (`/admin/surveys`, helpers `admin_surveys_path` / `admin_survey_path`) — both off by default because an app may already own those paths. Both need the `studio_survey_responses` table ([`docs/SURVEYS.md`](docs/SURVEYS.md)).
+
 **Magic links need the `studio_links` table.** Install it with `bin/rails studio_engine:install:migrations && bin/rails db:migrate` (install all of them) before enabling `:magic_link` — never by hand-copying the migration, which collides with the task's own copy on `class CreateStudioLinks`. Without the table, the first sign-in raises `Studio::Link::MissingTable`.
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.

data/app/controllers/studio/admin_surveys_controller.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Studio
+  # The survey results panel (docs/SURVEYS.md). Admin-only, drawn only when
+  # Studio.draw_admin_survey_routes is on.
+  #
+  #   GET /admin/surveys                every survey: started, completed, rate
+  #   GET /admin/surveys/:slug          per-question breakdown, filterable
+  #   GET /admin/surveys/:slug/export   the same filtered responses as CSV
+  #
+  # A slug with stored responses but no definition left in app code still lists
+  # and exports (its breakdown needs the definition, so its page says so).
+  class AdminSurveysController < ::ApplicationController
+    before_action :require_admin
+    before_action :require_table
+
+    def index
+      started = Studio::SurveyResponse.group(:survey_slug).count
+      completed = Studio::SurveyResponse.completed.group(:survey_slug).count
+      slugs = (Studio.surveys.map(&:slug) + started.keys).uniq.sort
+      @rows = slugs.map do |slug|
+        s = started.fetch(slug, 0)
+        c = completed.fetch(slug, 0)
+        { slug: slug, survey: Studio.survey(slug), started: s, completed: c,
+          rate: Studio::Survey::Breakdown.percent(c, s) }
+      end
+    end
+
+    def show
+      @slug = params[:slug].to_s
+      @survey = Studio.survey(@slug)
+      @filters = filters
+      scope = filtered_scope
+      @started = scope.count
+      @completed = scope.completed.count
+      return unless @survey
+
+      @breakdown = Studio::Survey::Breakdown.new(@survey, breakdown_rows(scope))
+    end
+
+    def export
+      slug = params[:slug].to_s
+      survey = Studio.survey(slug)
+      @filters = filters
+      @slug = slug
+      rows = filtered_scope.includes(:user).order(:id).map do |r|
+        { response_id: r.id, survey_version: r.survey_version, status: r.completed? ? "completed" : "in_progress",
+          started_at: r.started_at, completed_at: r.completed_at, respondent: r.respondent_label,
+          user_id: r.user_id, email_ref: r.email_ref, user_agent_class: r.user_agent_class, answers: r.answers }
+      end
+      csv = Studio::Survey::Export.new(survey, rows).to_csv
+      send_data csv, type: "text/csv; charset=utf-8",
+                     filename: "survey-#{slug.parameterize}-#{Time.current.strftime("%Y%m%d")}.csv"
+    end
+
+    private
+
+    def require_table
+      return if Studio::SurveyResponse.table_ready?
+
+      raise Studio::SurveyResponse::MissingTable,
+            "studio_survey_responses is not installed — run bin/rails studio_engine:install:migrations && bin/rails db:migrate"
+    end
+
+    def filters
+      {
+        from: parse_date(params[:from]),
+        to: parse_date(params[:to]),
+        completed: params[:completed] == "1"
+      }
+    end
+
+    def parse_date(value)
+      Date.iso8601(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # Dates filter on started_at, inclusive of both whole days.
+    def filtered_scope
+      scope = Studio::SurveyResponse.for_survey(@slug)
+      scope = scope.where(started_at: @filters[:from].beginning_of_day..) if @filters[:from]
+      scope = scope.where(started_at: ..@filters[:to].end_of_day) if @filters[:to]
+      scope = scope.completed if @filters[:completed]
+      scope
+    end
+
+    def breakdown_rows(scope)
+      scope.includes(:user).order(:id).map do |r|
+        { answers: r.answers, respondent: r.respondent_label, at: r.completed_at || r.updated_at }
+      end
+    end
+  end
+end

data/app/controllers/studio/surveys_controller.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Studio
+  # The public survey pages (docs/SURVEYS.md). Drawn only when
+  # Studio.draw_survey_routes is on.
+  #
+  #   GET   /surveys/:slug               the survey: one question per screen with JS,
+  #                                      a single form without it
+  #   PATCH /surveys/:slug/answers/:key  autosave one answer (JSON)
+  #   POST  /surveys/:slug               submit: store every answer, complete, thank
+  #   GET   /surveys/:slug/thanks        the thank-you screen and next action
+  #
+  # A response row is created on the FIRST ANSWER, not on page view, so a link
+  # preview bot or a bounce never counts as "started".
+  class SurveysController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+
+    before_action :load_survey
+    before_action :require_table
+    before_action :require_respondent
+
+    def show
+      @response = locate_response
+      return redirect_to(studio_survey_thanks_path(@survey.slug), status: :see_other) if @response&.completed?
+
+      @errors = {}
+      render_survey
+    end
+
+    def answer
+      question = @survey.question(params[:key])
+      return render(json: { error: "unknown question" }, status: :not_found) unless question
+
+      response = open_response!
+      return render(json: { error: "already complete" }, status: :conflict) unless response
+
+      ok, error = rescue_survey_write(response) { response.record_answer(question, params[:value]) }
+      if ok
+        render json: { saved: true, key: question.key, answered: response.answers.keys & @survey.keys }
+      else
+        render json: { saved: false, error: error }, status: :unprocessable_entity
+      end
+    end
+
+    def submit
+      response = open_response!
+      return redirect_to(studio_survey_thanks_path(@survey.slug), status: :see_other) unless response
+
+      submitted = submitted_answers
+      @errors = {}
+      Studio::SurveyResponse.transaction do
+        @survey.questions.each do |question|
+          next unless submitted.key?(question.key)
+
+          ok, error = response.record_answer(question, submitted[question.key])
+          @errors[question.key] = error unless ok
+        end
+      end
+      response.missing_required(@survey).each { |key| @errors[key] ||= "This one is required." }
+
+      if @errors.empty? && response.complete!(@survey)
+        run_completed_hook(response)
+        redirect_to studio_survey_thanks_path(@survey.slug), status: :see_other
+      elsif response.completed?
+        # A racing submit completed it first; that one fired the hook.
+        redirect_to studio_survey_thanks_path(@survey.slug), status: :see_other
+      else
+        @response = response
+        render_survey(status: :unprocessable_entity)
+      end
+    end
+
+    def thanks
+      @response = locate_response
+      redirect_to(studio_survey_path(@survey.slug), status: :see_other) unless @response&.completed?
+    end
+
+    private
+
+    def load_survey
+      @survey = Studio.survey(params[:slug])
+      render :not_found, status: :not_found unless @survey
+    end
+
+    def require_table
+      return if Studio::SurveyResponse.table_ready?
+
+      raise Studio::SurveyResponse::MissingTable,
+            "studio_survey_responses is not installed — run bin/rails studio_engine:install:migrations && bin/rails db:migrate"
+    end
+
+    # Signed in, arrived by an attributed email link, or an anonymous survey.
+    def require_respondent
+      return if @survey.allow_anonymous? || survey_user || survey_ref.present?
+
+      render :sign_in_required, status: :unauthorized
+    end
+
+    def render_survey(status: :ok)
+      @resume_key = @errors.keys.first || @response&.resume_key(@survey)
+      @resume_index = @resume_key ? @survey.keys.index(@resume_key) : nil
+      render :show, status: status
+    end
+
+    def survey_user
+      return @survey_user if defined?(@survey_user)
+
+      @survey_user = respond_to?(:current_user, true) ? current_user : nil
+    end
+
+    def survey_ref
+      return @survey_ref if defined?(@survey_ref)
+
+      @survey_ref = begin
+        Studio.survey_ref_resolver&.call(self).to_s.strip.presence
+      rescue StandardError => e
+        log_survey_error(e)
+        nil
+      end
+    end
+
+    def token_key = "studio_survey_#{@survey.slug}"
+
+    def session_token
+      session[token_key] ||= SecureRandom.urlsafe_base64(24)
+    end
+
+    def locate_response
+      Studio::SurveyResponse.locate(@survey, user: survey_user, token: session[token_key])
+    end
+
+    # The visitor's open response, created on demand; nil if theirs is complete.
+    def open_response!
+      existing = locate_response
+      return nil if existing&.completed?
+
+      response = existing || Studio::SurveyResponse.open_for!(
+        @survey, user: survey_user, token: session_token, email_ref: survey_ref, user_agent: request.user_agent
+      )
+      response.update!(email_ref: survey_ref.first(255)) if response.email_ref.blank? && survey_ref.present?
+      response
+    end
+
+    def submitted_answers
+      raw = params[:answers]
+      return {} unless raw.respond_to?(:permit)
+
+      permitted = @survey.questions.map { |q| q.multi? ? { q.key => [] } : q.key }
+      raw.permit(*permitted).to_h
+    end
+
+    def rescue_survey_write(target)
+      yield
+    rescue ActiveRecord::ActiveRecordError => e
+      log_survey_error(e, target: target)
+      [false, "Couldn't save that answer. Please try again."]
+    end
+
+    def run_completed_hook(response)
+      Studio.on_survey_completed&.call(response)
+    rescue StandardError => e
+      log_survey_error(e, target: response)
+    end
+
+    def log_survey_error(error, target: nil)
+      log = defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!) ? ::ErrorLog.capture!(error) : nil
+      log.update(target: target) if log && target && log.respond_to?(:target=)
+      Rails.logger.error("[studio-survey] #{error.class}: #{error.message}")
+    rescue StandardError
+      Rails.logger.error("[studio-survey] #{error.class}: #{error.message}")
+    end
+  end
+end

data/app/helpers/studio/site_footer_helper.rb

@@ -10,15 +10,18 @@ module Studio
   #   <%= studio_booking_popup %>           the dialog those links open
   #   <%= studio_footer_map %>              the map alone, e.g. on a contact page
   #
-  # Every one of them renders NOTHING when its configuration is absent
-  # (Studio.site_footer, Studio.booking_url), so a layout or a shared view can
-  # call them before an app has declared anything.
+  # THE FOOTER IS ON BY DEFAULT: with Studio.site_footer unset, the layout line
+  # renders the default footer (the site name, the logo, and the legal links the
+  # host has routes for), and `config.site_footer = false` turns it off. The
+  # booking helpers render NOTHING without Studio.booking_url, and the map
+  # nothing without an address, so a layout or a shared view can call any of
+  # them before an app has declared anything.
   #
   # Prefixed names for the reason Studio::GeoHelper gives: every helper module is
   # included into every view.
   module SiteFooterHelper
-    # The resolved facts (Studio::SiteFooter.resolve), or nil. Resolved once per
-    # request.
+    # The resolved facts (Studio::SiteFooter.resolve): the app's own, else the
+    # default footer's. nil when the footer is off. Resolved once per request.
     #
     # A callable that RAISES must not take every page down with it, because the
     # footer is in the layout. In production the error is logged once per process
@@ -41,7 +44,7 @@ module Studio
     # Where the footer shows: Studio.site_footer_visible, asked of this view. By
     # default that is every page for a visitor and, for a signed-in viewer, only
     # the controllers in Studio.site_footer_controllers (plus the booking page).
-    # Always false for an app that declared no footer.
+    # Always false for an app that turned the footer off.
     def studio_show_site_footer?
       return false if studio_site_footer_facts.nil?
 

data/app/models/studio/survey_response.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Studio
+  # One respondent's answers to one Studio::Survey (docs/SURVEYS.md).
+  #
+  # The survey is app code; this row is the only thing stored. Each answer is a
+  # self-describing snapshot — value, question label, type, and the option
+  # label(s) chosen — so a response stays readable after its survey changes.
+  class SurveyResponse < ApplicationRecord
+    self.table_name = "studio_survey_responses"
+
+    class MissingTable < StandardError; end
+
+    belongs_to :user, class_name: "::User", optional: true
+
+    validates :survey_slug, presence: true
+    validates :started_at, presence: true
+
+    scope :completed, -> { where.not(completed_at: nil) }
+    scope :in_progress, -> { where(completed_at: nil) }
+    scope :for_survey, ->(slug) { where(survey_slug: slug.to_s) }
+
+    before_validation { self.started_at ||= Time.current }
+
+    UA_BOT = /bot|crawl|spider|slurp|preview|facebookexternalhit|curl|wget|python|headless/i
+    UA_TABLET = /ipad|tablet|kindle|silk|(android(?!.*mobile))/i
+    UA_MOBILE = /mobi|iphone|ipod|android|blackberry|opera mini|iemobile/i
+
+    class << self
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+
+      # The coarse device class stored instead of the raw user agent.
+      def user_agent_class(user_agent)
+        ua = user_agent.to_s
+        return "unknown" if ua.strip.empty?
+        return "bot" if ua.match?(UA_BOT)
+        return "tablet" if ua.match?(UA_TABLET)
+        return "mobile" if ua.match?(UA_MOBILE)
+
+        "desktop"
+      end
+
+      # The visitor's open response, or their latest completed one: by user
+      # first, then by the session token. An anonymous response found by token
+      # is claimed by the user who signs in mid-survey, and the claim drops the
+      # token: logout keeps the survey session key, so a token on a user's row
+      # would hand it to the next person to sign in on that browser.
+      def locate(survey, user: nil, token: nil)
+        scope = for_survey(survey.slug)
+        found = user && scope.where(user_id: user.id).order(completed_at: :desc, id: :desc).find_by(completed_at: nil)
+        found ||= token.present? && scope.where(session_token: token, user_id: nil).order(id: :desc).first
+        found ||= user && scope.where(user_id: user.id).order(id: :desc).first
+        return nil unless found
+
+        found.update!(user_id: user.id, session_token: nil) if user && found.user_id.nil? && found.open?
+        found
+      end
+
+      # Find the visitor's open response or start one. The partial unique
+      # indexes make a double-click race lose to the row that won.
+      def open_for!(survey, user: nil, token:, email_ref: nil, user_agent: nil)
+        existing = locate(survey, user: user, token: token)
+        return existing if existing&.open?
+
+        create!(survey_slug: survey.slug, survey_version: survey.version, user_id: user&.id,
+                session_token: (token unless user), email_ref: email_ref.to_s.strip.presence&.first(255),
+                user_agent_class: user_agent_class(user_agent), answers: {})
+      rescue ActiveRecord::RecordNotUnique
+        locate(survey, user: user, token: token) || raise
+      end
+    end
+
+    def open? = completed_at.nil?
+    def completed? = completed_at.present?
+
+    def answer_entry(key) = (answers || {})[key.to_s]
+    def answer_value(key) = answer_entry(key)&.dig("value")
+
+    def answered?(question)
+      entry = answer_entry(question.key)
+      entry.is_a?(Hash) && !question.blank_value?(entry["value"])
+    end
+
+    # Stores one answer (or clears it, for a blank). Returns [ok, error]. Never
+    # touches a completed response: a finished survey is a record, not a draft.
+    def record_answer(question, raw)
+      return [false, "This survey is already complete."] if completed?
+
+      value, error = question.normalize(raw)
+      return [false, error] if error
+
+      next_answers = (answers || {}).dup
+      if value.nil?
+        next_answers.delete(question.key)
+      else
+        next_answers[question.key] = {
+          "value" => value, "label" => question.label, "type" => question.type.to_s,
+          "display" => question.display(value), "answered_at" => Time.current.utc.iso8601
+        }
+      end
+      self.answers = next_answers
+      self.current_key = question.key
+      save!
+      [true, nil]
+    end
+
+    def missing_required(survey)
+      survey.questions.select { |q| q.required? && !answered?(q) }.map(&:key)
+    end
+
+    # The first unanswered question — where a returning respondent resumes.
+    def resume_key(survey)
+      survey.questions.find { |q| !answered?(q) }&.key || survey.questions.last.key
+    end
+
+    # Completes the response if every required question is answered. Returns
+    # true only when THIS call completed it (false if incomplete or already
+    # done). The flip is one conditional UPDATE, so two racing submits (a no-JS
+    # double click) cannot both win and fire on_survey_completed twice; the
+    # loser reloads and sees the winner's completed_at.
+    def complete!(survey)
+      return false if completed? || missing_required(survey).any?
+
+      now = Time.current
+      flipped = self.class.where(id: id, completed_at: nil)
+                          .update_all(completed_at: now, survey_version: survey.version, updated_at: now)
+      unless flipped == 1
+        reload
+        return false
+      end
+
+      self.completed_at = now
+      self.survey_version = survey.version
+      self.updated_at = now
+      clear_attribute_changes(%w[completed_at survey_version updated_at])
+      true
+    end
+
+    # "username" for a signed-in respondent, "anonymous" otherwise.
+    def respondent_label
+      return "anonymous" unless user
+
+      user.try(:username).presence || user.try(:display_name).presence || "user ##{user.id}"
+    end
+  end
+end

data/app/views/studio/admin_surveys/index.html.erb

@@ -0,0 +1,41 @@
+<%# /admin/surveys — every survey with its funnel (Studio::AdminSurveysController).
+    "Started" counts responses with at least one answer: a row is created on the
+    first answer, never on a page view. %>
+<% content_for(:title, "Surveys") %>
+<div class="max-w-4xl mx-auto px-4 py-6" data-admin-surveys>
+  <h1 class="text-2xl font-extrabold text-heading mb-1">Surveys</h1>
+  <p class="text-sm text-secondary mb-6">Defined in <code>config/surveys/</code>. A response counts as started at its first answer.</p>
+
+  <% if @rows.empty? %>
+    <div class="empty-state">
+      <p class="text-heading font-semibold mb-1">No surveys yet</p>
+      <p class="text-sm text-muted">Define one with <code>Studio.define_survey</code> — see the engine's docs/SURVEYS.md.</p>
+    </div>
+  <% else %>
+    <div class="card overflow-x-auto">
+      <table class="w-full text-sm">
+        <thead>
+          <tr class="text-left border-b border-subtle">
+            <th scope="col" class="px-4 py-3 label-upper font-medium">Survey</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Started</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Completed</th>
+            <th scope="col" class="px-4 py-3 label-upper font-medium text-right">Completion</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @rows.each do |row| %>
+            <tr class="border-b border-subtle last:border-0" data-admin-survey-row="<%= row[:slug] %>">
+              <td class="px-4 py-3">
+                <a href="<%= admin_survey_path(row[:slug]) %>" class="font-semibold text-heading hover:underline"><%= row[:survey]&.title || row[:slug] %></a>
+                <div class="text-xs text-muted font-mono">/surveys/<%= row[:slug] %><% unless row[:survey] %> · definition removed<% end %></div>
+              </td>
+              <td class="px-4 py-3 text-right tabular-nums text-body" data-stat="started"><%= row[:started] %></td>
+              <td class="px-4 py-3 text-right tabular-nums text-body" data-stat="completed"><%= row[:completed] %></td>
+              <td class="px-4 py-3 text-right tabular-nums font-semibold text-heading" data-stat="rate"><%= row[:started].zero? ? "—" : "#{row[:rate]}%" %></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+</div>