studio-engine 0.87.0 → 0.88.0

data/app/views/studio/surveys/_question.html.erb

@@ -0,0 +1,77 @@
+<%# One survey question as a fieldset (studio/surveys/show). It is a complete
+    form control without JavaScript: native radios, checkboxes and text fields
+    named answers[key], with `required` so the no-JS form validates in the
+    browser too. The script enhances it into one screen of the stepper. %>
+<% key = question.key %>
+<% dom = "studio-survey-#{key}" %>
+<% value = response&.answer_value(key) %>
+<% ends = %i[emoji_scale rating].include?(question.type) && (question.low_label || question.high_label) %>
+<% described = [("#{dom}-help" if question.help), ("#{dom}-scale" if ends), "#{dom}-error"].compact.join(" ") %>
+<fieldset class="studio-survey__step" id="<%= dom %>" data-survey-step
+          data-key="<%= key %>" data-type="<%= question.type %>" data-required="<%= question.required? %>"
+          aria-describedby="<%= described %>">
+  <legend class="studio-survey__question" id="<%= dom %>-label" tabindex="-1" data-survey-focus>
+    <span class="studio-survey__qnum">Question <%= index + 1 %> of <%= total %></span>
+    <%= question.label %><% if question.required? %><span class="studio-survey__req" aria-hidden="true">*</span><span class="studio-survey__sr"> (required)</span><% end %>
+  </legend>
+  <% if question.help %>
+    <p class="studio-survey__help" id="<%= dom %>-help"><%= question.help %></p>
+  <% end %>
+
+  <div class="studio-survey__body">
+    <% case question.type %>
+    <% when :emoji_scale, :rating %>
+      <div class="studio-survey__scale">
+        <% question.options.each_with_index do |opt, i| %>
+          <label class="studio-survey__tile" data-survey-choice>
+            <input type="radio" class="studio-survey__input" name="answers[<%= key %>]" value="<%= opt.value %>"
+                   <%= "checked" if value.to_s == opt.value.to_s %> <%= "required" if question.required? %>
+                   <% if opt.face %>aria-label="<%= opt.label %>"<% end %>>
+            <% if opt.face %>
+              <span class="studio-survey__face" aria-hidden="true"><%= opt.face %></span>
+              <span class="studio-survey__tile-label" aria-hidden="true"><%= opt.label %></span>
+            <% else %>
+              <span class="studio-survey__num"><%= opt.label %></span>
+            <% end %>
+            <span class="studio-survey__kbd" aria-hidden="true"><%= i + 1 %></span>
+          </label>
+        <% end %>
+      </div>
+      <% if ends %>
+        <div class="studio-survey__ends" aria-hidden="true">
+          <span>1 · <%= question.low_label %></span><span><%= question.high_label %> · 5</span>
+        </div>
+        <p class="studio-survey__sr" id="<%= dom %>-scale">1 means <%= question.low_label || "lowest" %>, 5 means <%= question.high_label || "highest" %>.</p>
+      <% end %>
+    <% when :choice, :multi_choice %>
+      <% multi = question.multi? %>
+      <% chosen = Array(value).map(&:to_s) %>
+      <div class="studio-survey__options">
+        <% if multi %><input type="hidden" name="answers[<%= key %>][]" value=""><% end %>
+        <% question.options.each_with_index do |opt, i| %>
+          <label class="studio-survey__option" data-survey-choice>
+            <input type="<%= multi ? "checkbox" : "radio" %>" class="studio-survey__input"
+                   name="answers[<%= key %>]<%= "[]" if multi %>" value="<%= opt.value %>"
+                   <%= "checked" if chosen.include?(opt.value.to_s) %> <%= "required" if question.required? && !multi %>>
+            <span class="studio-survey__mark<%= " studio-survey__mark--box" if multi %>" aria-hidden="true"></span>
+            <span class="studio-survey__option-label"><%= opt.label %></span>
+            <% if i < 9 %><span class="studio-survey__kbd" aria-hidden="true"><%= i + 1 %></span><% end %>
+          </label>
+        <% end %>
+      </div>
+    <% when :short_text %>
+      <input type="text" class="input-field studio-survey__text" id="<%= dom %>-input" name="answers[<%= key %>]"
+             value="<%= value %>" maxlength="<%= question.max_length %>" aria-labelledby="<%= dom %>-label"
+             placeholder="<%= question.placeholder || "Type your answer" %>" autocomplete="off"
+             <%= "required" if question.required? %> data-survey-text>
+    <% when :long_text %>
+      <textarea class="input-field studio-survey__text" id="<%= dom %>-input" name="answers[<%= key %>]" rows="5"
+                maxlength="<%= question.max_length %>" aria-labelledby="<%= dom %>-label"
+                placeholder="<%= question.placeholder || "Type your answer" %>"
+                <%= "required" if question.required? %> data-survey-text><%= value %></textarea>
+      <p class="studio-survey__counter" aria-hidden="true"><span data-survey-counter><%= value.to_s.length %></span> / <%= question.max_length %></p>
+    <% end %>
+  </div>
+
+  <p class="studio-survey__error" id="<%= dom %>-error" role="alert" data-survey-error <%= "hidden" unless error %>><%= error %></p>
+</fieldset>

data/app/views/studio/surveys/_script.html.erb

@@ -0,0 +1,288 @@
+<%# The survey stepper: progressive enhancement over studio/surveys/show.
+    Plain JavaScript (no Alpine dependency), idempotent per root so a Turbo
+    render that re-runs it never double-binds. Bound roots are tracked in a
+    WeakSet, never in a DOM attribute: Turbo's snapshot cache clones the page,
+    and a clone keeps every attribute but none of the listeners, so a marker
+    in the DOM would make a restored page look set up while it is dead.
+    Autosave is best effort: the final Submit posts the whole form, so a
+    failed autosave loses nothing. %>
+<%= javascript_tag nonce: true do %>
+(function () {
+  "use strict";
+
+  // Shared across re-runs of this script (Turbo evaluates it on every visit).
+  var bound = window.__studioSurveyBound || (window.__studioSurveyBound = new WeakSet());
+
+  function init(root) {
+    if (bound.has(root)) return;
+    bound.add(root);
+
+    var form = root.querySelector("[data-survey-form]");
+    var steps = Array.prototype.slice.call(root.querySelectorAll("[data-survey-step]"));
+    var total = steps.length - 1;
+    var back = root.querySelector("[data-survey-back]");
+    var next = root.querySelector("[data-survey-next]");
+    var submit = root.querySelector("[data-survey-submit]");
+    var top = root.querySelector("[data-survey-top]");
+    var bar = root.querySelector("[data-survey-progress]");
+    var fill = root.querySelector("[data-survey-progress-fill]");
+    var count = root.querySelector("[data-survey-count]");
+    var status = root.querySelector("[data-survey-status]");
+    var hint = root.querySelector("[data-survey-hint]");
+    // A page restored from Turbo's cache comes back on the step it was left
+    // on; resume there rather than at the server's original resume point.
+    var restored = -1;
+    // The GLOBAL token, not the form's: with per_form_csrf_tokens on, the
+    // form's hidden token is bound to the POST and refused on the PATCH.
+    var csrf = root.dataset.csrf || "";
+    var reduce = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    var saved = {};
+    var timers = {};
+    var current = -1;
+    var pointerPick = false;
+    var submitting = false;
+
+    form.noValidate = true;
+    if (root.classList.contains("is-enhanced")) {
+      Array.prototype.forEach.call(root.querySelectorAll("[data-survey-step]"), function (step, i) {
+        if (step.classList.contains("is-active")) restored = i;
+      });
+    }
+    root.classList.add("is-enhanced");
+    top.hidden = false;
+
+    function typeOf(step) { return step.dataset.type || ""; }
+    function isChoice(step) { return /^(emoji_scale|rating|choice)$/.test(typeOf(step)); }
+    function isMulti(step) { return typeOf(step) === "multi_choice"; }
+    function inputs(step) { return Array.prototype.slice.call(step.querySelectorAll("input.studio-survey__input")); }
+
+    function valueOf(step) {
+      if (isMulti(step)) return inputs(step).filter(function (i) { return i.checked; }).map(function (i) { return i.value; });
+      if (isChoice(step)) {
+        var picked = inputs(step).filter(function (i) { return i.checked; })[0];
+        return picked ? picked.value : "";
+      }
+      var field = step.querySelector("[data-survey-text]");
+      return field ? field.value.trim() : "";
+    }
+
+    function answered(step) {
+      var v = valueOf(step);
+      return Array.isArray(v) ? v.length > 0 : v !== "";
+    }
+
+    function setError(step, message) {
+      var el = step.querySelector("[data-survey-error]");
+      if (!el) return;
+      el.textContent = message || "";
+      el.hidden = !message;
+      step.classList.toggle("is-invalid", !!message);
+    }
+
+    function save(step) {
+      var key = step.dataset.key;
+      if (!key || submitting) return Promise.resolve(true);
+      var value = valueOf(step);
+      var fingerprint = JSON.stringify(value);
+      if (saved[key] === fingerprint) return Promise.resolve(true);
+
+      var body = new FormData();
+      if (Array.isArray(value)) {
+        if (value.length === 0) body.append("value[]", "");
+        value.forEach(function (v) { body.append("value[]", v); });
+      } else {
+        body.append("value", value);
+      }
+      var url = root.dataset.answerBase + encodeURIComponent(key);
+      status.textContent = "Saving…";
+      return fetch(url, {
+        method: "PATCH",
+        body: body,
+        credentials: "same-origin",
+        headers: { "Accept": "application/json", "X-CSRF-Token": csrf }
+      }).then(function (res) {
+        // fetch resolves on a 4xx/5xx — the status is the only signal.
+        if (!res.ok) {
+          return res.json().catch(function () { return {}; }).then(function (data) {
+            if (res.status === 422 && data.error) setError(step, data.error);
+            status.textContent = "Not saved yet — your answers still go in when you submit.";
+            return false;
+          });
+        }
+        saved[key] = fingerprint;
+        status.textContent = "Saved";
+        return true;
+      }).catch(function () {
+        status.textContent = "Offline? Your answers still go in when you submit.";
+        return false;
+      });
+    }
+
+    function render(index, direction) {
+      steps.forEach(function (step, i) {
+        var active = i === index;
+        step.hidden = !active;
+        step.classList.toggle("is-active", active);
+        if (active) {
+          if (direction && !reduce) step.dataset.dir = direction; else delete step.dataset.dir;
+        }
+      });
+      current = index;
+      var onIntro = index === 0;
+      var last = index === steps.length - 1;
+      back.hidden = onIntro;
+      next.hidden = last;
+      next.textContent = onIntro ? "Start" : "Next";
+      submit.hidden = !last;
+      // The number-key shortcut only means something on a choice or scale.
+      var step = steps[index];
+      hint.hidden = !(step.dataset.key && (isChoice(step) || isMulti(step)));
+
+      var position = onIntro ? 0 : index;
+      fill.style.width = (total ? (position / total) * 100 : 0) + "%";
+      bar.setAttribute("aria-valuenow", String(position));
+      // The intro already says how many questions there are.
+      count.textContent = onIntro ? "" : "Question " + index + " of " + total;
+
+      var focusTarget = steps[index].querySelector("[data-survey-focus]");
+      if (focusTarget && direction) focusTarget.focus({ preventScroll: true });
+      if (direction) window.scrollTo({ top: 0, behavior: reduce ? "auto" : "smooth" });
+    }
+
+    function go(index) {
+      if (index < 0 || index >= steps.length || index === current) return;
+      render(index, index > current ? "fwd" : "back");
+    }
+
+    function forward() {
+      var step = steps[current];
+      if (step.dataset.key) {
+        if (step.dataset.required === "true" && !answered(step)) {
+          setError(step, "This one is required.");
+          var first = step.querySelector("input:not([type=hidden]), textarea");
+          if (first) first.focus();
+          return;
+        }
+        setError(step, "");
+      }
+      if (current === steps.length - 1) {
+        // No autosave here: the POST carries every answer, and a PATCH racing
+        // it would land after completion and be refused.
+        submitForm();
+      } else {
+        if (step.dataset.key) save(step);
+        go(current + 1);
+      }
+    }
+
+    function submitForm() {
+      if (form.requestSubmit) form.requestSubmit(submit); else form.submit();
+    }
+
+    // The first required question still missing an answer, for a Submit that
+    // jumps ahead (Enter on the last step, or a mid-survey reload).
+    form.addEventListener("submit", function (event) {
+      for (var i = 1; i < steps.length; i++) {
+        if (steps[i].dataset.required === "true" && !answered(steps[i])) {
+          event.preventDefault();
+          go(i);
+          setError(steps[i], "This one is required.");
+          return;
+        }
+      }
+      Object.keys(timers).forEach(function (key) { clearTimeout(timers[key]); });
+      submitting = true;
+      submit.disabled = true;
+      submit.textContent = "Sending…";
+    });
+
+    back.addEventListener("click", function () { go(current - 1); });
+    next.addEventListener("click", forward);
+
+    root.addEventListener("pointerdown", function (event) {
+      pointerPick = !!event.target.closest("[data-survey-choice]");
+    });
+
+    root.addEventListener("change", function (event) {
+      var step = event.target.closest("[data-survey-step]");
+      if (!step || !step.dataset.key || step.hidden) return;
+      setError(step, "");
+      if (isChoice(step)) {
+        save(step);
+        // Advance on a tap or a number key, never on arrow keys: arrows move
+        // through a radio group and must not jump the reader off the question.
+        if (pointerPick) {
+          pointerPick = false;
+          setTimeout(function () { if (steps[current] === step) forward(); }, reduce ? 0 : 260);
+        }
+      } else if (isMulti(step)) {
+        save(step);
+      }
+    });
+
+    root.addEventListener("input", function (event) {
+      var field = event.target.closest("[data-survey-text]");
+      if (!field) return;
+      var step = field.closest("[data-survey-step]");
+      var counter = step.querySelector("[data-survey-counter]");
+      if (counter) counter.textContent = String(field.value.length);
+      clearTimeout(timers[step.dataset.key]);
+      timers[step.dataset.key] = setTimeout(function () { save(step); }, 900);
+    });
+
+    root.addEventListener("keydown", function (event) {
+      if (event.defaultPrevented || event.altKey) return;
+      // A tap on an already-chosen option fires pointerdown but no change, so
+      // the flag would outlive it and make the next arrow key advance.
+      pointerPick = false;
+      var step = steps[current];
+      var target = event.target;
+      var inText = target.matches && target.matches("textarea, input[type=text]");
+
+      if (event.key === "Enter") {
+        if (target.tagName === "BUTTON" || target.tagName === "A") return;
+        if (target.tagName === "TEXTAREA" && !(event.metaKey || event.ctrlKey)) return;
+        event.preventDefault();
+        forward();
+        return;
+      }
+
+      if (inText || event.metaKey || event.ctrlKey || !/^[1-9]$/.test(event.key)) return;
+      if (!step.dataset.key || !(isChoice(step) || isMulti(step))) return;
+      var option = inputs(step)[parseInt(event.key, 10) - 1];
+      if (!option) return;
+      event.preventDefault();
+      option.checked = isMulti(step) ? !option.checked : true;
+      option.focus({ preventScroll: true });
+      pointerPick = isChoice(step);
+      option.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+
+    var resume = root.dataset.resumeIndex;
+    var start = resume === "" || resume === undefined ? 0 : parseInt(resume, 10) + 1;
+    var hasErrors = root.dataset.hasErrors === "true";
+    // A fresh visitor sees the intro; a returning one lands on their next
+    // question, and a failed submit on the first question it flagged.
+    if (restored >= 0) start = restored;
+    render(start > 0 ? start : 0, null);
+    if (restored < 0 && (start > 0 || hasErrors)) {
+      var focusTarget = steps[current].querySelector("[data-survey-focus]");
+      if (focusTarget) focusTarget.focus({ preventScroll: true });
+      if (start > 0 && !hasErrors) status.textContent = "Welcome back — picking up where you left off.";
+    }
+    // Answers already on the page are already stored.
+    steps.forEach(function (step) { if (step.dataset.key) saved[step.dataset.key] = JSON.stringify(valueOf(step)); });
+  }
+
+  function boot() {
+    Array.prototype.forEach.call(document.querySelectorAll("[data-studio-survey]"), init);
+  }
+
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot); else boot();
+  // Turbo re-runs this script on every visit; bind the turbo:load hook once.
+  if (!window.__studioSurveyTurboHook) {
+    window.__studioSurveyTurboHook = true;
+    document.addEventListener("turbo:load", boot);
+  }
+})();
+<% end %>

data/app/views/studio/surveys/_styles.html.erb

@@ -0,0 +1,95 @@
+<%# Survey styles, scoped under .studio-survey. Plain CSS on the theme's CSS
+    custom properties (--color-cta, --color-surface, ...) rather than Tailwind
+    utilities, so the page looks the same in every host whatever its Tailwind
+    scan picks up, and follows the host's dark and light palettes for free.
+    Motion is opt-out: prefers-reduced-motion drops every transition. %>
+<style>
+  /* overflow-x: clip, not hidden: the slide-in must never widen the page, and
+     clip makes no scroll container, so the sticky nav still sticks. */
+  .studio-survey { --sv-accent: var(--color-cta, #8E82FE); display: flex; justify-content: center; padding: 1.25rem 1rem 2rem; color: var(--color-text-body); overflow-x: clip; }
+  .studio-survey [hidden] { display: none !important; }
+  .studio-survey__shell { width: 100%; max-width: 36rem; }
+  .studio-survey__sr { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+  .studio-survey__top { margin-bottom: 1.75rem; }
+  .studio-survey__progress { height: 6px; border-radius: 999px; background: var(--color-surface-alt); overflow: hidden; }
+  .studio-survey__progress-fill { display: block; height: 100%; width: 0; border-radius: inherit; background: var(--sv-accent); transition: width .35s cubic-bezier(.2, .8, .2, 1); }
+  .studio-survey__count { min-height: 1.25rem; margin: .5rem 0 0; font-size: .8125rem; line-height: 1.25rem; color: var(--color-text-muted); }
+  .studio-survey__step { border: 0; margin: 0 0 2.25rem; padding: 0; min-width: 0; }
+  .studio-survey__title { margin: 0 0 .75rem; font-size: 1.75rem; line-height: 1.2; font-weight: 800; color: var(--color-text); outline: none; }
+  .studio-survey__intro-copy { margin: 0 0 1rem; font-size: 1.0625rem; line-height: 1.55; color: var(--color-text-body); white-space: pre-line; }
+  .studio-survey__meta { margin: 0; font-size: .8125rem; color: var(--color-text-muted); }
+  .studio-survey__question { display: block; width: 100%; padding: 0; margin: 0 0 .5rem; font-size: 1.375rem; line-height: 1.3; font-weight: 700; color: var(--color-text); outline: none; }
+  .studio-survey__qnum { display: block; margin-bottom: .375rem; font-size: .75rem; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; color: var(--color-text-muted); }
+  .studio-survey.is-enhanced .studio-survey__qnum { display: none; }
+  .studio-survey__req { color: var(--sv-accent); margin-left: .125rem; }
+  .studio-survey__help { margin: 0 0 1rem; font-size: .9375rem; line-height: 1.5; color: var(--color-text-secondary); }
+  .studio-survey__body { margin-top: 1rem; }
+  .studio-survey__error { margin: .75rem 0 0; font-size: .875rem; font-weight: 600; color: var(--color-danger-ink, var(--color-danger)); }
+  .studio-survey__input { position: absolute; opacity: 0; width: 1px; height: 1px; margin: 0; pointer-events: none; }
+
+  .studio-survey__scale { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: .5rem; }
+  .studio-survey__tile { position: relative; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: .3rem; min-height: 4.75rem; padding: .75rem .25rem; border: 2px solid var(--color-border); border-radius: 1rem; background: var(--color-surface); color: var(--color-text-body); cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: transform .12s ease, border-color .15s ease, background-color .15s ease; }
+  .studio-survey__tile:hover { border-color: var(--color-border-strong); }
+  .studio-survey__tile:active { transform: scale(.95); }
+  .studio-survey__face { font-size: 2.125rem; line-height: 1; transition: transform .18s cubic-bezier(.3, 1.6, .5, 1); }
+  .studio-survey__num { font-size: 1.5rem; line-height: 1; font-weight: 800; color: var(--color-text); }
+  .studio-survey__tile-label { font-size: .6875rem; line-height: 1.15; text-align: center; color: var(--color-text-secondary); }
+  .studio-survey__ends { display: flex; justify-content: space-between; gap: 1rem; margin-top: .5rem; font-size: .75rem; color: var(--color-text-muted); }
+
+  .studio-survey__options { display: flex; flex-direction: column; gap: .5rem; }
+  .studio-survey__option { position: relative; display: flex; align-items: center; gap: .75rem; min-height: 3.25rem; padding: .75rem 1rem; border: 2px solid var(--color-border); border-radius: .875rem; background: var(--color-surface); color: var(--color-text-body); font-size: 1rem; cursor: pointer; -webkit-tap-highlight-color: transparent; transition: border-color .15s ease, background-color .15s ease; }
+  .studio-survey__option:hover { border-color: var(--color-border-strong); }
+  .studio-survey__mark { flex: none; display: grid; place-items: center; width: 1.25rem; height: 1.25rem; border: 2px solid var(--color-text-muted); border-radius: 999px; background: var(--color-surface); }
+  .studio-survey__mark--box { border-radius: .375rem; }
+  .studio-survey__option-label { flex: 1 1 auto; min-width: 0; }
+
+  .studio-survey__tile:has(input:checked), .studio-survey__option:has(input:checked) { border-color: var(--sv-accent); background: color-mix(in srgb, var(--sv-accent) 14%, var(--color-surface)); color: var(--color-text); }
+  .studio-survey__tile:has(input:checked) .studio-survey__face { transform: scale(1.18); }
+  .studio-survey__tile:has(input:checked) .studio-survey__tile-label { color: var(--color-text); font-weight: 600; }
+  .studio-survey__option:has(input:checked) .studio-survey__mark { border-color: var(--sv-accent); background: var(--sv-accent); box-shadow: inset 0 0 0 3px var(--color-surface); }
+  .studio-survey__option:has(input:checked) .studio-survey__mark--box { box-shadow: none; }
+  .studio-survey__option:has(input:checked) .studio-survey__mark--box::after { content: ""; width: .35rem; height: .65rem; margin-top: -.15rem; border: solid var(--btn-primary-fg, #fff); border-width: 0 2px 2px 0; transform: rotate(45deg); }
+  .studio-survey__tile:has(input:focus-visible), .studio-survey__option:has(input:focus-visible) { outline: 3px solid color-mix(in srgb, var(--sv-accent) 70%, transparent); outline-offset: 2px; }
+
+  .studio-survey__kbd { display: none; font-size: .625rem; font-weight: 600; color: var(--color-text-muted); border: 1px solid var(--color-border); border-radius: .25rem; padding: 0 .3rem; line-height: 1.4; }
+  .studio-survey__tile .studio-survey__kbd { position: absolute; top: .3rem; right: .35rem; }
+  .studio-survey__option .studio-survey__kbd { margin-left: auto; }
+  @media (hover: hover) and (pointer: fine) { .studio-survey.is-enhanced .studio-survey__option .studio-survey__kbd { display: inline-block; } }
+  /* On a scale tile the badge needs the room a phone-width tile does not have. */
+  @media (hover: hover) and (pointer: fine) and (min-width: 640px) { .studio-survey.is-enhanced .studio-survey__tile .studio-survey__kbd { display: inline-block; } }
+
+  .studio-survey__text { width: 100%; font-size: 1rem; }
+  textarea.studio-survey__text { min-height: 9rem; resize: vertical; line-height: 1.5; }
+  .studio-survey__counter { margin: .375rem 0 0; text-align: right; font-size: .75rem; color: var(--color-text-muted); }
+
+  .studio-survey__nav { display: flex; align-items: center; gap: .75rem; }
+  .studio-survey.is-enhanced .studio-survey__nav { position: sticky; bottom: 0; padding: .75rem 0 calc(.75rem + env(safe-area-inset-bottom, 0px)); background: linear-gradient(to top, var(--color-page) 72%, transparent); }
+  .studio-survey__nav .btn { min-height: 3rem; min-width: 6.5rem; }
+  .studio-survey__forward { margin-left: auto; }
+  .studio-survey__status { min-height: 1.25rem; margin: .5rem 0 0; font-size: .75rem; text-align: center; color: var(--color-text-muted); }
+  .studio-survey__hint { margin: .25rem 0 0; font-size: .75rem; text-align: center; color: var(--color-text-muted); }
+  @media (hover: none), (pointer: coarse) { .studio-survey__hint { display: none; } }
+
+  .studio-survey__card { padding: 2rem 1.5rem; text-align: center; border: 1px solid var(--color-border); border-radius: 1.25rem; background: var(--color-surface); }
+  .studio-survey__burst { font-size: 3rem; line-height: 1; margin-bottom: .75rem; }
+
+  @keyframes studio-survey-in-fwd { from { opacity: 0; transform: translateX(1.5rem); } to { opacity: 1; transform: none; } }
+  @keyframes studio-survey-in-back { from { opacity: 0; transform: translateX(-1.5rem); } to { opacity: 1; transform: none; } }
+  @keyframes studio-survey-shake { 0%, 100% { transform: none; } 25% { transform: translateX(-6px); } 75% { transform: translateX(6px); } }
+  .studio-survey__step.is-active[data-dir="fwd"] { animation: studio-survey-in-fwd .3s cubic-bezier(.2, .8, .2, 1); }
+  .studio-survey__step.is-active[data-dir="back"] { animation: studio-survey-in-back .3s cubic-bezier(.2, .8, .2, 1); }
+  .studio-survey__step.is-invalid .studio-survey__body { animation: studio-survey-shake .3s ease; }
+  @media (prefers-reduced-motion: reduce) {
+    .studio-survey *, .studio-survey *::before, .studio-survey *::after { animation: none !important; transition: none !important; }
+  }
+
+  @media (min-width: 640px) {
+    .studio-survey { padding-top: 3rem; }
+    .studio-survey__question { font-size: 1.625rem; }
+    .studio-survey__title { font-size: 2.125rem; }
+    .studio-survey__scale { gap: .75rem; }
+    .studio-survey__tile { min-height: 5.5rem; }
+    .studio-survey__face { font-size: 2.5rem; }
+    .studio-survey__tile-label { font-size: .75rem; }
+  }
+</style>

data/app/views/studio/surveys/not_found.html.erb

@@ -0,0 +1,11 @@
+<%# An unknown survey slug. Says nothing about why. %>
+<% content_for(:title, "Survey not found") %>
+<%= render "studio/surveys/styles" %>
+<main class="studio-survey" data-studio-survey-missing>
+  <div class="studio-survey__shell">
+    <div class="studio-survey__card">
+      <h1 class="studio-survey__title">Survey not found</h1>
+      <p class="studio-survey__intro-copy">This survey doesn't exist or has closed.</p>
+    </div>
+  </div>
+</main>

data/app/views/studio/surveys/show.html.erb

@@ -0,0 +1,60 @@
+<%# /surveys/:slug — the survey (Studio::SurveysController#show, docs/SURVEYS.md).
+
+    ONE FORM, TWO PRESENTATIONS. Without JavaScript every question renders in
+    order and the Submit button posts the lot. The script below adds
+    .is-enhanced and turns the same markup into one question per screen, with a
+    progress bar, Back and Next, number-key and Enter shortcuts, and an
+    autosave on each answer. Submit is still the same POST either way, so the
+    server's validation is the one rule. %>
+<% total = @survey.questions.size %>
+<% minutes = [(total / 3.0).ceil, 1].max %>
+<% content_for(:title, @survey.title) %>
+<%= render "studio/surveys/styles" %>
+
+<main class="studio-survey" data-studio-survey
+      data-answer-base="<%= studio_survey_path(@survey.slug) %>/answers/"
+      data-csrf="<%= form_authenticity_token %>"
+      data-resume-index="<%= @resume_index %>"
+      data-has-errors="<%= @errors.any? %>"
+      data-total="<%= total %>">
+  <div class="studio-survey__shell">
+    <div class="studio-survey__top" data-survey-top hidden>
+      <div class="studio-survey__progress" role="progressbar" aria-label="Survey progress"
+           aria-valuemin="0" aria-valuemax="<%= total %>" aria-valuenow="0" data-survey-progress>
+        <span class="studio-survey__progress-fill" data-survey-progress-fill></span>
+      </div>
+      <p class="studio-survey__count" aria-live="polite" data-survey-count></p>
+    </div>
+
+    <%= form_with url: studio_survey_path(@survey.slug), method: :post, local: true,
+                  html: { class: "studio-survey__form", data: { survey_form: true } } do %>
+      <section class="studio-survey__step" data-survey-step data-intro aria-labelledby="studio-survey-title">
+        <h1 class="studio-survey__title" id="studio-survey-title" tabindex="-1" data-survey-focus><%= @survey.title %></h1>
+        <% if @survey.intro %>
+          <p class="studio-survey__intro-copy"><%= @survey.intro %></p>
+        <% end %>
+        <p class="studio-survey__meta">
+          <%= pluralize(total, "question") %> · about <%= pluralize(minutes, "minute") %><% if @survey.required_keys.any? %> · <span aria-hidden="true">*</span> required<% end %>
+        </p>
+        <% if @errors.any? %>
+          <p class="studio-survey__error" role="alert">A few answers need another look before this can be sent.</p>
+        <% end %>
+      </section>
+
+      <% @survey.questions.each_with_index do |question, index| %>
+        <%= render "studio/surveys/question", question: question, index: index, total: total,
+                                              response: @response, error: @errors[question.key] %>
+      <% end %>
+
+      <div class="studio-survey__nav">
+        <button type="button" class="btn btn-neutral" data-survey-back hidden>Back</button>
+        <button type="button" class="btn btn-primary studio-survey__forward" data-survey-next hidden>Start</button>
+        <button type="submit" class="btn btn-primary studio-survey__forward" data-survey-submit>Submit</button>
+      </div>
+      <p class="studio-survey__status" aria-live="polite" data-survey-status></p>
+      <p class="studio-survey__hint" data-survey-hint hidden>Press a number to choose · Enter to continue</p>
+    <% end %>
+  </div>
+</main>
+
+<%= render "studio/surveys/script" %>

data/app/views/studio/surveys/sign_in_required.html.erb

@@ -0,0 +1,15 @@
+<%# A survey without allow_anonymous, opened by a visitor who is neither
+    signed in nor arriving by an attributed email link. %>
+<% content_for(:title, @survey.title) %>
+<%= render "studio/surveys/styles" %>
+<main class="studio-survey" data-studio-survey-sign-in>
+  <div class="studio-survey__shell">
+    <div class="studio-survey__card">
+      <h1 class="studio-survey__title"><%= @survey.title %></h1>
+      <p class="studio-survey__intro-copy">Sign in to answer this survey.</p>
+      <% if respond_to?(:login_path) %>
+        <a href="<%= login_path %>" class="btn btn-primary btn-lg">Sign in</a>
+      <% end %>
+    </div>
+  </div>
+</main>

data/app/views/studio/surveys/thanks.html.erb

@@ -0,0 +1,16 @@
+<%# /surveys/:slug/thanks — shown once a response completes. The next action is
+    the survey's own (next_action label:, url:), when it declares one. %>
+<% content_for(:title, "Thank you") %>
+<%= render "studio/surveys/styles" %>
+<main class="studio-survey" data-studio-survey-thanks>
+  <div class="studio-survey__shell">
+    <div class="studio-survey__card">
+      <div class="studio-survey__burst" aria-hidden="true">&#x1F64C;</div>
+      <h1 class="studio-survey__title" tabindex="-1" autofocus>Thank you!</h1>
+      <p class="studio-survey__intro-copy"><%= @survey.thank_you %></p>
+      <% if @survey.next_action %>
+        <a href="<%= @survey.next_action[:url] %>" class="btn btn-primary btn-lg" data-survey-next-action><%= @survey.next_action[:label] %></a>
+      <% end %>
+    </div>
+  </div>
+</main>

data/db/migrate/20261005120000_create_studio_survey_responses.rb

@@ -0,0 +1,47 @@
+# One respondent's answers to one survey (Studio::SurveyResponse,
+# docs/SURVEYS.md). Surveys themselves are defined in app code, not stored; the
+# row keys on the survey's slug and stamps the definition version it was taken
+# under.
+#
+# `answers` is { question_key => { "value", "label", "type", "display",
+# "answered_at" } }: each answer carries the question label and option label it
+# was given under, so a later edit to the definition never rewrites history.
+#
+# No raw IP and no raw user agent: user_agent_class is mobile / tablet /
+# desktop / bot / unknown, which is all the results panel reads.
+#
+# The two partial unique indexes enforce ONE IN-PROGRESS response per signed-in
+# user, and per anonymous session token, for each survey. Completed rows fall
+# out of both, so a respondent's history is unconstrained.
+class CreateStudioSurveyResponses < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_survey_responses do |t|
+      t.string :survey_slug, null: false
+      t.string :survey_version
+      if connection.adapter_name.match?(/postg/i)
+        t.jsonb :answers, null: false, default: {}
+      else
+        t.json :answers, null: false, default: {}
+      end
+      t.bigint :user_id
+      t.string :email_ref
+      t.string :session_token
+      t.string :user_agent_class
+      t.string :current_key
+      t.datetime :started_at, null: false
+      t.datetime :completed_at
+
+      t.timestamps
+    end
+
+    add_index :studio_survey_responses, %i[survey_slug completed_at]
+    add_index :studio_survey_responses, :user_id
+    add_index :studio_survey_responses, :email_ref
+    add_index :studio_survey_responses, %i[survey_slug user_id], unique: true,
+              where: "completed_at IS NULL AND user_id IS NOT NULL",
+              name: "index_studio_survey_responses_one_open_per_user"
+    add_index :studio_survey_responses, %i[survey_slug session_token], unique: true,
+              where: "completed_at IS NULL AND session_token IS NOT NULL",
+              name: "index_studio_survey_responses_one_open_per_session"
+  end
+end

data/lib/studio/engine.rb

@@ -170,6 +170,15 @@ module Studio
 
     public
 
+    # Survey definitions (docs/SURVEYS.md): every *.rb under
+    # Studio.survey_definitions_path, loaded on boot and again on each
+    # development reload so an edited definition takes effect without a restart.
+    # Surveys defined in an initializer instead stay registered either way.
+    config.to_prepare do
+      dir = Studio.survey_definitions_path
+      Studio::Survey.load_definitions!(Rails.root.join(dir)) if dir.present? && Rails.root
+    end
+
     config.after_initialize do
       # Configure the IP -> location provider for every app that has the gem,
       # so geo detection works the same way everywhere: HTTPS (without which