studio-engine 0.117.0 → 0.119.0

data/app/helpers/studio/loader_helper.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Studio
+  # The branded loader (docs/LOADER.md), as view helpers. Every one draws the
+  # app's own icon (Studio.loader_icon) in its theme colours, in the style the
+  # app declared with Studio.loader; there is no per-app markup.
+  #
+  #   <%= studio_loader %>                          96px, the app's style
+  #   <%= studio_loader size: 20, label: "Saving" %> inline, beside text
+  #   <%= studio_loader style: :liquid, percent: 40 %> a fill that follows a percent
+  #   <%= studio_loader_pending %>                  inside a submit button
+  #   <%= studio_loader_overlay %>                  the page-load overlay (layout, once)
+  #
+  # Prefixed names for the reason Studio::GeoHelper gives: every helper module is
+  # included into every view.
+  module LoaderHelper
+    # Bead layers, coolest first: [dash length of 100, stroke width in a 264-unit
+    # icon, opacity]. The colours are CSS (--studio-loader-bead-1..6), so a theme
+    # can retune them. The last three glow.
+    LOADER_BEAD_LAYERS = [[46, 9, 0.5], [30, 9, 0.75], [16, 9, 0.95], [7, 9.5, 1], [2.6, 10, 1], [0.3, 17, 1]].freeze
+    LOADER_BEAD_UNIT = 264.3
+
+    def studio_loader(size: 96, style: nil, icon: nil, art: nil, label: "Loading", percent: nil,
+                      tone: nil, pending: false, **html)
+      config = Studio.loader
+      style = style ? Studio::Loader.style!(style) : config[:style]
+      art_data = nil
+      if Studio::Loader.art_style?(style)
+        art_data = Studio::Loader.art(art || config[:art], style)
+        style = Studio::Loader::DEFAULT_STYLE if art_data.nil?
+      end
+
+      render "studio/loader/loader",
+             style: style,
+             size: studio_loader_size(size),
+             icon: icon || Studio.loader_icon,
+             art: art_data,
+             label: label,
+             percent: percent.nil? ? nil : percent.to_f.clamp(0, 100).round(1),
+             mono: (tone || (pending ? :mono : nil)).to_s == "mono",
+             pending: pending,
+             uid: "studio-loader-#{SecureRandom.hex(4)}",
+             html: html
+    end
+
+    # The small loader a submit button carries. Hidden until the button, or the
+    # form it submits, is aria-busy (Turbo marks the form; studio/loader marks
+    # the button for a form Turbo does not drive). Drawn in the button's own
+    # text colour, so it reads on any fill.
+    def studio_loader_pending(size: 18, style: :breathe, **options)
+      studio_loader(size: size, style: style, pending: true, **options)
+    end
+
+    # The full-page overlay: once, in the layout's body. studio/loader shows it
+    # when a visit the user started (never a background replace) or a marked
+    # form outlasts `delay` ms, and window.StudioLoader.show() / hide() drive it
+    # for any other long wait. A submit Turbo does not drive clears its overlay
+    # and busy button after `max_wait` ms, so a response that became a download
+    # never leaves them up; a Turbo visit is never capped.
+    # Any studio_loader option (style:, icon:, art:) passes through.
+    def studio_loader_overlay(label: "Loading", delay: 350, max_wait: 15_000, size: 96, **options)
+      render "studio/loader/overlay", label: label, delay: delay.to_i, max_wait: max_wait.to_i, size: size, options: options
+    end
+
+    def studio_loader_size(size)
+      size.is_a?(Numeric) ? "#{size}px" : size.to_s
+    end
+
+    # The stroke layers a weld bead draws over the art's outline path.
+    def studio_loader_bead_layers(art)
+      unit = art[:width] / LOADER_BEAD_UNIT
+      LOADER_BEAD_LAYERS.each_with_index.map do |(dash, width, opacity), index|
+        { n: index + 1, dash: dash, width: (width * unit).round(2), opacity: opacity, glow: index >= 3 }
+      end
+    end
+  end
+end

data/app/helpers/studio_theme_helper.rb

@@ -10,6 +10,6 @@ module StudioThemeHelper
       Studio::ThemeResolver.new(colors).to_css
     end
 
-    tag.style("#{css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
+    tag.style("#{css}\n#{Studio::TypeScale.css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
   end
 end

data/app/javascript/studio/application.js

@@ -17,9 +17,11 @@ import LinkSidebarController from "studio/controllers/link_sidebar_controller"
 import IdentityMiniController from "studio/controllers/identity_mini_controller"
 import { startPinnedStack } from "studio/pinned_stack"
 import { installAlpineShims } from "studio/alpine_shims"
+import { installStudioLoader } from "studio/loader"
 
 installAlpineShims()
 startPinnedStack()
+installStudioLoader()
 
 application.register("nav-collapse", NavCollapseController)
 application.register("modal-host", ModalHostController)

data/app/javascript/studio/loader.js

@@ -0,0 +1,214 @@
+// studio/loader: drives the branded loader's two live states (docs/LOADER.md).
+// The motion itself is CSS (engine-motion.css, "Branded loader"); this module
+// only decides WHEN the page-load overlay shows and marks busy buttons.
+//
+//   the overlay   [data-studio-loader-overlay], rendered once by
+//                 studio_loader_overlay. Shown when a visit the USER started (a
+//                 Turbo advance or restore; never a replace, a refresh, a frame
+//                 or a prefetch), or a submit of a form marked
+//                 data-studio-loader-overlay, outlasts the overlay's data-delay
+//                 ms; hidden when the page arrives. Its role=status label is
+//                 announced: the overlay never marks itself aria-busy.
+//   pending       a button holding studio_loader_pending. Turbo marks a
+//                 submitting form aria-busy itself; for a form Turbo does not
+//                 drive, the submitter is marked here, and cleared on pagehide
+//                 and on pageshow (a bfcache restore).
+//   the cap       a submit Turbo does not drive clears its overlay and button
+//                 after data-max-wait ms (MAX_WAIT_MS by default): a response that
+//                 turned into a download replaces no page, so nothing else
+//                 would. A Turbo visit is never capped; a non-HTML response
+//                 clears at once, on turbo:reload.
+//   the API       window.StudioLoader.show(caption) / hide() for any other long
+//                 wait, and setPercent(el, n) for a loader drawn with percent:.
+//
+// The logic is exported for test/javascript/loader.test.mjs.
+
+export var DEFAULT_DELAY_MS = 350
+export var MAX_WAIT_MS = 15000
+
+// Only a visit the user started earns the overlay: a click or Turbo.visit
+// (advance) and Back or Forward (restore). A replace is a background refresh
+// (a poll, Turbo 8's page refresh); frames and prefetches never fire turbo:visit.
+export function userVisit(event) {
+  var action = event && event.detail && event.detail.action
+  return action === 'advance' || action === 'restore'
+}
+
+export function overlayDelay(overlay) {
+  var value = overlay ? parseInt(overlay.getAttribute('data-delay'), 10) : NaN
+  return value >= 0 ? value : DEFAULT_DELAY_MS
+}
+
+// The percent a caller handed setPercent, clamped to a number in 0..100.
+export function clampPercent(value) {
+  var n = Number(value)
+  if (!isFinite(n)) return 0
+  return Math.min(100, Math.max(0, n))
+}
+
+export function maxWait(overlay) {
+  var value = overlay ? parseInt(overlay.getAttribute('data-max-wait'), 10) : NaN
+  return value > 0 ? value : MAX_WAIT_MS
+}
+
+function findOverlay(doc) {
+  return doc.querySelector('[data-studio-loader-overlay]')
+}
+
+var pendingTimer = null
+var capTimer = null
+var autoShown = false
+
+// The overlay's status is a live region; rewriting its label after the overlay
+// unhides makes a screen reader say it, where text already present when a
+// region appears is often skipped. The label is kept in data-studio-loader-label,
+// so a second show inside the gap restores it rather than the emptied text.
+function announce(overlay, doc) {
+  var label = overlay.querySelector('[role="status"] .sr-only')
+  if (!label) return
+  var text = label.getAttribute('data-studio-loader-label')
+  if (text === null) { text = label.textContent; label.setAttribute('data-studio-loader-label', text) }
+  label.textContent = ''
+  var win = doc.defaultView
+  ;(win && win.setTimeout ? win.setTimeout.bind(win) : setTimeout)(function () { label.textContent = text }, 50)
+}
+
+export function show(caption, doc) {
+  doc = doc || document
+  clearTimeout(pendingTimer)
+  pendingTimer = null
+  autoShown = false
+  var overlay = findOverlay(doc)
+  if (!overlay) return false
+  var line = overlay.querySelector('[data-studio-loader-caption]')
+  if (line) line.textContent = caption || ''
+  overlay.hidden = false
+  announce(overlay, doc)
+  // One frame hidden=false at opacity 0, then fade in.
+  var raf = (doc.defaultView && doc.defaultView.requestAnimationFrame) || function (fn) { return setTimeout(fn, 16) }
+  raf(function () { if (!overlay.hidden) overlay.setAttribute('data-state', 'shown') })
+  return true
+}
+
+export function hide(doc) {
+  doc = doc || document
+  clearTimeout(pendingTimer)
+  pendingTimer = null
+  var overlay = findOverlay(doc)
+  if (!overlay) return false
+  overlay.removeAttribute('data-state')
+  overlay.hidden = true
+  return true
+}
+
+// Clear the buttons studio/loader marked busy (never one a page marked itself).
+export function clearBusy(doc) {
+  doc = doc || document
+  clearTimeout(capTimer)
+  capTimer = null
+  var marked = doc.querySelectorAll('[data-studio-loader-busy]')
+  for (var i = 0; i < marked.length; i++) {
+    marked[i].removeAttribute('aria-busy')
+    marked[i].removeAttribute('data-studio-loader-busy')
+  }
+}
+
+// Hide the overlay and clear every busy button: the page is ours again.
+export function settle(doc) {
+  doc = doc || document
+  hide(doc)
+  clearBusy(doc)
+}
+
+// The cap never hides an overlay a caller showed through StudioLoader.show().
+function armCap(doc) {
+  clearTimeout(capTimer)
+  capTimer = setTimeout(function () {
+    var shownByUs = autoShown
+    clearBusy(doc)
+    if (shownByUs) hide(doc)
+  }, maxWait(findOverlay(doc)))
+}
+
+// Show after the overlay's delay, so a fast load never flashes it. Uncapped: a
+// slow Turbo visit keeps its overlay until the page arrives.
+export function showSoon(caption, doc) {
+  doc = doc || document
+  var overlay = findOverlay(doc)
+  if (!overlay || !overlay.hidden) return
+  clearTimeout(pendingTimer)
+  pendingTimer = setTimeout(function () { show(caption, doc); autoShown = true }, overlayDelay(overlay))
+}
+
+export function markBusy(button, doc) {
+  doc = doc || document
+  button.setAttribute('aria-busy', 'true')
+  button.setAttribute('data-studio-loader-busy', '')
+  armCap(doc)
+}
+
+export function setPercent(el, value) {
+  if (!el) return
+  var loader = el.classList && el.classList.contains('studio-loader') ? el : el.querySelector('.studio-loader')
+  if (!loader) return
+  loader.setAttribute('data-loader-percent', '')
+  loader.style.setProperty('--studio-loader-percent', String(clampPercent(value)))
+}
+
+// A submitter that carries a pending loader.
+export function pendingSubmitter(event) {
+  var submitter = event && (event.submitter || (event.detail && event.detail.formSubmission && event.detail.formSubmission.submitter))
+  if (!submitter || !submitter.querySelector) return null
+  return submitter.querySelector('.studio-loader[data-loader-pending]') ? submitter : null
+}
+
+var installed = false
+export function installStudioLoader(doc) {
+  doc = doc || document
+  if (installed) return
+  installed = true
+
+  doc.addEventListener('turbo:visit', function (event) { if (userVisit(event)) showSoon('', doc) })
+  // turbo:reload: the response was not HTML (a download), or the visit failed,
+  // and Turbo hands the URL to the browser; no page may ever replace this one.
+  ;['turbo:load', 'turbo:render', 'turbo:before-cache', 'turbo:fetch-request-error', 'turbo:frame-load', 'turbo:reload'].forEach(function (name) {
+    doc.addEventListener(name, function () { hide(doc) })
+  })
+  // Leaving clears the page before the bfcache keeps it; a restore clears it
+  // again, in case it was kept some other way.
+  if (doc.defaultView) {
+    doc.defaultView.addEventListener('pagehide', function () { settle(doc) })
+    doc.defaultView.addEventListener('pageshow', function (event) { if (event.persisted) settle(doc) })
+  }
+
+  doc.addEventListener('turbo:submit-start', function (event) {
+    var form = event.target
+    if (form && form.hasAttribute && form.hasAttribute('data-studio-loader-overlay')) {
+      showSoon(form.getAttribute('data-studio-loader-overlay') || '', doc)
+    }
+  })
+  doc.addEventListener('turbo:submit-end', function (event) {
+    var form = event.target
+    if (form && form.hasAttribute && form.hasAttribute('data-studio-loader-overlay')) hide(doc)
+  })
+
+  // A form Turbo does not drive navigates away on its own; mark the button and,
+  // when asked, the overlay, until the next page replaces this one.
+  doc.addEventListener('submit', function (event) {
+    var form = event.target
+    if (event.defaultPrevented || !form || !form.getAttribute) return
+    var win = doc.defaultView
+    if (win && win.Turbo && form.getAttribute('data-turbo') !== 'false') return
+    var button = pendingSubmitter(event)
+    if (button) markBusy(button, doc)
+    if (form.hasAttribute('data-studio-loader-overlay')) { showSoon(form.getAttribute('data-studio-loader-overlay') || '', doc); armCap(doc) }
+  })
+
+  if (doc.defaultView && !doc.defaultView.StudioLoader) {
+    doc.defaultView.StudioLoader = {
+      show: function (caption) { return show(caption, doc) },
+      hide: function () { return hide(doc) },
+      setPercent: setPercent
+    }
+  }
+}

data/app/mailers/studio/google_setup_mailer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Studio
+  # "Request Google setup", sent to the team when someone presses it in the
+  # Google modal of an app whose OAuth client is not configured yet
+  # (Studio::GoogleSetupRequestsController, Studio::GoogleSignIn). Namespaced so
+  # a host's own mailers cannot shadow it; plain strings in, so an outbox row
+  # stores nothing but text.
+  class GoogleSetupMailer < ApplicationMailer
+    layout false
+
+    # The shared production OAuth client every app's callback is added to, and
+    # who adds it. Facts for the reader of the email, not configuration.
+    OAUTH_PROJECT = "enduring-maxim-491202-t6"
+
+    # host and redirect_uri come from the app's CONFIGURED canonical host
+    # (Studio::GoogleSignIn.canonical_host), never from the request, and are
+    # blank when the app names none: the email then says to set one.
+    def setup_requested(app_name, host, redirect_uri, to)
+      @app_name = app_name
+      @host = host.to_s.strip.presence
+      @redirect_uri = redirect_uri.to_s.strip.presence
+      @oauth_project = OAUTH_PROJECT
+      subject = "Google sign-in setup requested: #{app_name}"
+      subject += " (#{@host})" if @host
+      mail(to: to, subject: subject)
+    end
+  end
+end

data/app/models/concerns/studio/omniauth_user.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Studio
+  # The engine's default Google find-or-create (docs/USER_CONTRACT.md, "Google
+  # sign-in"), so an app signs people in with Google before it writes a line of
+  # its own User code.
+  #
+  # OmniauthCallbacksController calls Studio::OmniauthUser.resolve(User, ...),
+  # which uses the host's own User.from_omniauth when the class answers it and
+  # this module's find_or_create otherwise. A host that wants the default under
+  # its own name includes the concern; a host that defines `def
+  # self.from_omniauth` in the class body overrides it either way, because a
+  # method on the class itself is found before one from an extended module.
+  #
+  # The default, in order:
+  #
+  #   1. the account already holding this Google id (provider + uid);
+  #   2. else the account holding the address, compared case-insensitively, but
+  #      only when Google verified the address: an unverified match answers
+  #      :email_not_verified, since it proves nothing about who holds the
+  #      mailbox;
+  #   3. else a new account, address downcased.
+  #
+  # THE SLUG COLLISION (Carl, 2026-10-29, on voicebox). The documented example
+  # created a second "Mia" whose name_slug was "mia" again; the unique slug index
+  # raised RecordNotUnique, the rescue looked for the address and the uid, found
+  # nobody, and sign-in failed. So the create checks the slug first, and a slug
+  # that is blank or already held becomes user-<id> (settled by Sluggable after
+  # the insert). A collision that survives that, with nobody to find, is logged
+  # with ErrorLog.capture! and answers nil, which the controller turns into a
+  # "use another method" redirect rather than a 500.
+  module OmniauthUser
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def from_omniauth(auth, email_verified: false)
+        Studio::OmniauthUser.find_or_create(self, auth, email_verified: email_verified)
+      end
+    end
+
+    class << self
+      def resolve(model, auth, email_verified: false)
+        if model.respond_to?(:from_omniauth)
+          model.from_omniauth(auth, email_verified: email_verified)
+        else
+          find_or_create(model, auth, email_verified: email_verified)
+        end
+      end
+
+      def find_or_create(model, auth, email_verified: false)
+        provider = read(auth, "provider")
+        uid = read(auth, "uid")
+        return nil if provider.nil? || uid.nil?
+
+        user = model.find_by(provider: provider, uid: uid)
+        return user if user
+
+        email = normalize_email(read(auth, "info", "email"))
+        if email && (existing = find_by_email(model, email))
+          return :email_not_verified unless email_verified
+
+          existing.update!(provider: provider, uid: uid)
+          return existing
+        end
+
+        attributes = { provider: provider, uid: uid, email: email, name: read(auth, "info", "name") }
+        create_with_free_slug(model, attributes, email_verified: email_verified)
+      end
+
+      def normalize_email(value)
+        email = value.to_s.strip.downcase
+        email.empty? ? nil : email
+      end
+
+      def find_by_email(model, email)
+        return nil unless column?(model, "email")
+
+        model.where(model.arel_table[:email].lower.eq(email)).first
+      end
+
+      private
+
+      def create_with_free_slug(model, attributes, email_verified: false)
+        assignable = attributes.select { |key, value| !value.nil? && column?(model, key.to_s) }
+        last_error = nil
+
+        [false, true].each do |force_fallback|
+          record = model.new(assignable)
+          install_fallback_slug(record) if force_fallback || slug_needs_fallback?(model, record)
+          begin
+            model.transaction(requires_new: true) { record.save! }
+            return record
+          rescue ActiveRecord::RecordNotUnique => e
+            last_error = e
+            # A concurrent sign-in made the row first: that row is the answer.
+            # The Google id always identifies it; the address only when Google
+            # verified it, the same rule as step 2 above. An unverified address
+            # that collides with someone else's row hands that row to nobody.
+            found = model.find_by(provider: assignable[:provider], uid: assignable[:uid])
+            found ||= find_by_email(model, assignable[:email]) if email_verified && assignable[:email]
+            return found if found
+          end
+        end
+
+        log_unmatched_collision(last_error)
+        nil
+      end
+
+      def slug_needs_fallback?(model, record)
+        return false unless column?(model, "slug") && record.respond_to?(:name_slug, true)
+
+        candidate = begin
+          record.send(:name_slug).to_s
+        rescue StandardError
+          ""
+        end
+        candidate.strip.empty? || model.unscoped.where(slug: candidate).exists?
+      end
+
+      # user-<token> before the insert, user-<id> once the id exists: Sluggable
+      # writes the first in before_save and settles the second after_create.
+      def install_fallback_slug(record)
+        token = SecureRandom.hex(4)
+        record.define_singleton_method(:name_slug) { id ? "user-#{id}" : "user-#{token}" }
+      end
+
+      def log_unmatched_collision(error)
+        return unless error
+
+        Rails.logger.warn("[omniauth] Google sign-in collided with nobody to find: #{error.class}: #{error.message.to_s[0, 300]}")
+        ErrorLog.capture!(error) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+      rescue StandardError => e
+        Rails.logger.warn("[omniauth] could not log the collision: #{e.class}")
+      end
+
+      def column?(model, name)
+        model.respond_to?(:attribute_names) && model.attribute_names.include?(name)
+      end
+
+      def read(auth, *path)
+        value = path.reduce(auth) do |node, key|
+          break nil if node.nil?
+
+          node.respond_to?(:[]) ? (node[key] || (node[key.to_sym] if node.is_a?(Hash))) : nil
+        end
+        string = value.to_s.strip
+        string.empty? ? nil : string
+      end
+    end
+  end
+end

data/app/views/registrations/new.html.erb

@@ -87,11 +87,9 @@
           </div>
         <% end %>
 
-        <%= button_to "/auth/google_oauth2", method: :post, data: { turbo: false },
-          class: "btn btn-google btn-lg w-full gap-3" do %>
-          <%= render "components/google_logo" %>
-          Sign up with Google
-        <% end %>
+        <%# A POST to the strategy once the app has its OAuth client, the setup
+            modal until then (studio/google_sign_in/_button). %>
+        <%= render "studio/google_sign_in/button", label: "Sign up with Google" %>
       <% end %>
 
       <p class="text-center text-secondary text-sm mt-6">

data/app/views/sessions/new.html.erb

@@ -87,11 +87,9 @@
           </div>
         <% end %>
 
-        <%= button_to "/auth/google_oauth2", method: :post, data: { turbo: false },
-          class: "btn btn-google btn-lg w-full gap-3" do %>
-          <%= render "components/google_logo" %>
-          Sign in with Google
-        <% end %>
+        <%# A POST to the strategy once the app has its OAuth client, the setup
+            modal until then (studio/google_sign_in/_button). %>
+        <%= render "studio/google_sign_in/button", label: "Sign in with Google" %>
       <% end %>
 
       <p class="text-center text-secondary text-sm mt-6">

data/app/views/studio/google_setup_mailer/setup_requested.html.erb

@@ -0,0 +1,18 @@
+<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 15px; line-height: 1.5; color: #1f2937; max-width: 560px;">
+  <p>Someone asked for Google sign-in on <strong><%= @app_name %></strong><%= " (#{@host})" if @host %>.</p>
+  <p>The app already draws the "Sign in with Google" button; it opens a setup notice until the OAuth client is in place. Two steps finish it:</p>
+  <ol>
+    <li>
+      Add this redirect URI to the shared production OAuth client
+      (Google Cloud project <code><%= @oauth_project %></code>, admin@ Chrome profile; Steffon's lane):
+      <% if @redirect_uri %>
+        <p><code style="background: #f3f4f6; padding: 2px 6px; border-radius: 4px;"><%= @redirect_uri %></code></p>
+      <% else %>
+        <p>None yet: the app names no canonical host. Set <code>APP_HOST</code>, or <code>Studio.google_canonical_host</code>, to its production hostname; the URI is then <code>https://&lt;that host&gt;/auth/google_oauth2/callback</code>.</p>
+      <% end %>
+    </li>
+    <li>Set <code>GOOGLE_CLIENT_ID</code> and <code>GOOGLE_CLIENT_SECRET</code> on the app, then restart it.</li>
+  </ol>
+  <p>Once both are set, the button posts straight to Google. This request is sent at most once per app per day. The URI above comes from the app's configuration, never from the request that asked.</p>
+  <p style="color: #6b7280; font-size: 13px;">Guide: studio-engine docs/GOOGLE_AUTH_SETUP.md</p>
+</div>

data/app/views/studio/google_setup_mailer/setup_requested.text.erb

@@ -0,0 +1,23 @@
+Someone asked for Google sign-in on <%= @app_name %><%= " (#{@host})" if @host %>.
+
+The app already draws the "Sign in with Google" button; it opens a setup notice
+until the OAuth client is in place. Two steps finish it:
+
+1. Add this redirect URI to the shared production OAuth client
+   (Google Cloud project <%= @oauth_project %>, admin@ Chrome profile; Steffon's lane):
+
+<% if @redirect_uri -%>
+   <%= @redirect_uri %>
+<% else -%>
+   (none yet: the app names no canonical host. Set APP_HOST, or
+   Studio.google_canonical_host, to its production hostname; the URI is then
+   https://<that host>/auth/google_oauth2/callback)
+<% end -%>
+
+2. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET on the app, then restart it.
+
+Once both are set, the button posts straight to Google. This request is sent at
+most once per app per day. The URI above comes from the app's configuration,
+never from the request that asked.
+
+Guide: studio-engine docs/GOOGLE_AUTH_SETUP.md

data/app/views/studio/google_sign_in/_button.html.erb

@@ -0,0 +1,52 @@
+<%# The "Sign in with Google" button, for every engine page that offers Google
+    (sessions/new, registrations/new, studio/profiles/_google_section).
+
+    Locals:
+      label          — REQUIRED. The button's words ("Sign in with Google").
+      button_class   — optional. Default "btn btn-google btn-lg w-full gap-3".
+      email_fallback — optional, default true. The modal's "Use email instead",
+                       which closes it and focuses the page's email field. The
+                       profile page, where the person is already signed in,
+                       passes false and gets "Not now".
+
+    TWO STATES, by Studio::GoogleSignIn.button_posts?:
+
+      READY — the app has its OAuth client (or registered its own provider, or
+      OmniAuth is in test mode). A POST form to /auth/google_oauth2, Turbo off:
+      OmniAuth's middleware owns that path, and the request phase is POST-only
+      and CSRF-checked.
+
+      NOT YET — no client yet. The same button, opening a modal on a page-scoped
+      host (store googleSetupModals) that says Google sign-in is still being set
+      up, offers "Request Google setup" (POST /_studio/google_setup_request,
+      which mails the team once per app per day) and a way back to email.
+
+    The x-data on the wrapper is load-bearing: studio/modals/_scoped_host
+    declares no Alpine scope of its own, and without one above it the modal
+    registers, opens, and renders nothing (see studio/profiles/show). One button
+    per page; two would mount two hosts on one store. %>
+<%
+  google_label = local_assigns.fetch(:label)
+  google_button_class = local_assigns.fetch(:button_class, "btn btn-google btn-lg w-full gap-3")
+  google_email_fallback = local_assigns.fetch(:email_fallback, true)
+%>
+<% if Studio::GoogleSignIn.button_posts? %>
+  <%= button_to Studio::GoogleSignIn::REQUEST_PATH, method: :post, data: { turbo: false, google_sign_in: "ready" },
+        class: google_button_class do %>
+    <%= render "components/google_logo" %>
+    <%= google_label %>
+  <% end %>
+<% else %>
+  <div x-data data-google-sign-in="setup">
+    <button type="button" class="<%= google_button_class %>" aria-haspopup="dialog"
+            @click="$store.googleSetupModals.open('google-setup')">
+      <%= render "components/google_logo" %>
+      <%= google_label %>
+    </button>
+    <%= render "studio/modals/scoped_host", store: "googleSetupModals" do %>
+      <template x-if="$store.googleSetupModals.current()?.id === 'google-setup'">
+        <%= render "studio/google_sign_in/setup_modal", email_fallback: google_email_fallback %>
+      </template>
+    <% end %>
+  </div>
+<% end %>