studio-engine 0.47.2 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 918309978020f15861f65e0a861325bb7ba93046b4d9039aa1aaa1ae6da22c95
-  data.tar.gz: 682e1529aeca6541d08ab5173028bd407b3538fed1e1b9dd3fb88b70b11e0145
+  metadata.gz: 5cfb0ff6698fde0520d0d6e081ffd49d99801473831f92c18e86a9cb9dc177a1
+  data.tar.gz: 2a96a7e242ff9211d0307326e77258136b725a99d5d749a9664e5194336af72c
 SHA512:
-  metadata.gz: 3da6d45e75a8adcbb72b39117e416381b6c6962fe4b831ee2a90d4feddd9b60a4c63b969cc85d442780685d0a0c2916fe423e7dd11c1df392d2fa06a3f9267e4
-  data.tar.gz: 40e41ee896e9375ebeb9522afb78a9ed481c57c6f15f7a2681a9a51211cf861875a82125bdc52cc6a3b5b9d9820d46e72bd6b2b961822f46ee39367300564755
+  metadata.gz: d142923e12b84afc01d96afda2cdaf578ef422a6e34f480cad0917671140ad99bf5eb73d70b0283eed6ba4a5eece21f98ea356662a963c504fdef758ccf3b857
+  data.tar.gz: 657e2a9742b8e92317a3128593fe50663cb2fd09ca004a1700d0dc0e0a4c6916d7f0d024c28b6098a93e6424cfacb174bdf46878cadcf9dab953b5532725e520

data/CHANGELOG.md

@@ -4,8 +4,242 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Fixed
+
+- **`Studio.profile_sections`' `if:` gate no longer fails open on a Symbol.**
+  `if: :some_predicate` — Rails' own `before_action ..., if: :method_name`
+  spelling, and so the most natural thing a host will write — was coerced
+  straight to `true`, because a Symbol does not answer `call`. The gate silently
+  did nothing, with no signal to the host, in the same permissive direction as
+  the bug `if:` was added to fix. Symbols and Strings now name a method on the
+  view; a name the view does not answer drops the row rather than rendering it.
+  Lambdas and plain booleans are unchanged.
+
+### Added
+
+- **`/profile` gains the Email row — changeable from any signed-in session.**
+  `PATCH /profile/email` (`profile_email_path`) applies the change directly.
+
+  **THE GOOGLE EXCEPTION.** An account with a linked Google identity **cannot**
+  change its email: Google is the authoritative source for that address, and
+  letting the two drift means the next OAuth sign-in either re-links to a
+  stranger's row or cannot find its own. The row shows the address with the
+  reason instead of a field, and the endpoint refuses independently — a disabled
+  input is a courtesy, and anyone can POST.
+
+  **What a direct change trades away, stated so nobody rediscovers it:** a
+  hijacked session can move the account to another inbox, and the old address has
+  no veto. Two protections are kept precisely BECAUSE the veto is gone —
+
+  - the **old address is mailed** after every change (OPSEC-046), so a change
+    nobody made is visible to the person losing the account, and
+  - **every other session is invalidated** (OPSEC-045), so a hijacker holding a
+    second cookie loses it the moment the address moves. The session that made
+    the change is re-established, so the person doing it is not signed out.
+
+- **`Studio::ProfileMailer`** with `email_change_notification`, plus a new
+  standard `Studio::EmailCatalog` entry so its copy, subject and banner are
+  operator-editable on `/admin/emails` like every other Studio email. **Namespaced deliberately:**
+  `app/mailers` is an autoload path and this engine is not isolated, so a host's
+  top-level `UserMailer` shadows the engine's — mcritchie-studio's fork defines no
+  `email_change_notification` at all (a bare call raises `NoMethodError`), and
+  turf-monster's defines one with the SAME signature — so there the call would
+  not raise, it would quietly send TURF's copy, banner and `account_url` instead
+  of the engine's. The silent case is the dangerous one.
+
+- **`/profile` gains the Google account row.** Shows the linked identity with an
+  Unlink control, or a branded Connect button that POSTs to OmniAuth's own
+  `/auth/google_oauth2` (the engine does not draw a link route — the middleware
+  owns that path). Lifted from turf-monster's `/account` Identities card.
+
+  New route: `DELETE /profile/google` → `profile_unlink_google_path`.
+
+  **`Studio::OauthIdentity`** carries the rules, pure and duck-typed like
+  `Studio::ProfileImage`: `google_linked?`, `remaining_sign_ins`,
+  `unlink_orphans_account?`. It matches **both** provider spellings in the wild —
+  `google_oauth2` (the OmniAuth strategy name that lands in `users.provider`) and
+  `google` (what `Studio.auth_methods` calls it).
+
+  **THE ORPHAN GUARD — the reason this is not a straight copy.** turf-monster's
+  unlink is an unconditional `update!(provider: nil, uid: nil)`. For an account
+  whose only sign-in is Google — blank email so no magic link, no wallet, no
+  password — that silently locks someone out of their own account behind a button
+  labelled "Unlink". It is safe in turf today only because turf's users happen to
+  carry an email, which is a property of that app's **data**, not of its code.
+
+  The engine refuses instead, and gates on **`Studio.auth_methods`, not merely on
+  the column**: an app that has an `email` column but does not offer magic-link
+  sign-in cannot use it to get back in, so counting it would be exactly the wrong
+  answer. The row disables the button with the reason beside it; the endpoint
+  refuses the request independently, because a disabled button is a courtesy and
+  anyone can send the `DELETE`.
+
+  **What counts as a way back in is deliberately narrow**, because a false
+  positive here permits an unlink that orphans an account. A password counts only
+  via `Studio.password_login_available?` (`auth_method?(:password)` **and** the
+  User answering `authenticate`) — turf-monster removed `has_secure_password` and
+  kept the column, so its rows carry fossil digests no code can authenticate
+  against. A wallet counts only when the host has **explicitly** named its
+  signing-wallet column via `Studio.wallet_address_method`; the engine does not
+  guess a conventional reader, because turf's `User#solana_address` returns
+  `web3 || web2` and only the web3 address can sign in — the web2 one is
+  custodial, with no signer. An unconfigured app is treated as having no wallet
+  sign-in, which errs toward refusing: the cost is a refusal the operator fixes
+  with one config line, against someone locked out of their account.
+
+  The row declares `requires: %i[provider uid]` **and**
+  `if: -> { Studio.auth_method?(:google) }` — the model gate and the app gate are
+  different questions, and only the pair is correct. **Every** consumer's users
+  table carries `provider` and `uid`, so the model gate alone selected the whole
+  fleet; mcritchie-industries has both columns, `auth_methods = %i[magic_link]`,
+  and no omniauth gem at all, and would have been handed a "Link Google Account"
+  button leading nowhere. The engine's login page already asks the app question
+  before drawing this identical button (`app/views/sessions/new.html.erb`).
+
+- **`Studio.profile_sections` rows accept `if:`** — an optional callable gating a
+  row on an app capability, evaluated at resolve time, called with the view when
+  it takes an argument and without when it does not. Distinct from `requires:`,
+  which asks whether the user MODEL can serve the row.
+
+- **The shared profile page — `/profile`.** The engine now ships the account page
+  itself, not just the parts. `Studio::ProfilesController` renders a page of
+  declared rows; iteration one ships two, **change your photo** and **change your
+  first name**. Every consumer gets it on upgrade with no configuration.
+
+  **Why this page exists at all.** `components/_user_nav` has always linked the
+  username and the avatar to `defined?(account_path) ? account_path : "#"`, and
+  only turf-monster draws an account route — so every app that renders the
+  ENGINE's copy of that partial shipped a navbar whose avatar and username are
+  `href="#"`. A dead link looks exactly like a working one until it is clicked,
+  which is why it survived in production. The engine assumed a page every consumer
+  was expected to write for itself; now it ships the page.
+
+  **Which apps that actually is** (host views shadow engine views, so a fork does
+  not receive this): **mcritchie-industries and acquisition-studio** render the
+  engine partial and had the dead link. **mcritchie-studio** and **turf-monster**
+  each ship their own `app/views/components/_user_nav.html.erb` and are unaffected
+  either way; **moms-app** forks `layouts/_navbar` and renders no user nav at all.
+
+  **Why `/profile` and not `/account`.** turf-monster owns `AccountsController`
+  and the `account_path` helper. A shared `/account` route would raise
+  `Invalid route name, already in use` while turf's own `routes.rb` loads, which
+  takes down **every** route in that app — the same collision that forced
+  `draw_admin_emails_routes` and `draw_onboarding_routes` to be opt-in. `profile`
+  is claimed by none of the five consumers (mcritchie-studio,
+  mcritchie-industries, turf-monster, moms-app, acquisition-studio — each checked
+  2026-08-14), so **`Studio.draw_profile_routes` defaults to `true`** and a
+  brand-new app is correct on day one. It also buys turf a migration path: its
+  `/account` keeps working untouched while its rows move to `/profile` one at a
+  time, and `/account` is deleted only once it is empty.
+
+  | Route | Helper | What it does |
+  |---|---|---|
+  | `GET /profile` | `profile_path` | The page |
+  | `PATCH /profile` | `profile_path` | Scalar fields (today: `first_name`) |
+  | `PATCH /profile/avatar` | `profile_avatar_path` | The picture |
+
+  The avatar has a route of its own **deliberately**: an attachment param
+  submitted empty PURGES the attachment, so one form carrying both the name and
+  the file would delete someone's photo every time they edited their name.
+
+  **The photo row is turf-monster's avatar interaction, standardized.** Click the
+  picture, a hover cap reads "Update", pick a file, crop it square, and it saves
+  immediately — no Save button and no visible file field. It runs on the engine's
+  existing `imageUploadHost` factory and shared crop-photo modal, the same
+  primitives `/admin/emails` uses.
+
+  Two changes from turf's copy, both deliberate:
+
+  - **The click target is a `<button>`, not a `<div>`.** turf's is a `div @click`,
+    which no keyboard or screen-reader user can reach — for them the only way to
+    change a photo would be a mouse. Same visual; the hover cap also reveals on
+    focus.
+  - **The crop confirm goes through `onCropConfirmed()`, not `applyCrop()`.** Every
+    `imageUploadHost` on a page hears the same window event, so binding
+    `applyCrop` directly means a page that later grows a second uploader has both
+    hosts save the same crop. `onCropConfirmed` checks the owner token first.
+
+  **The page brings its own modals.** A row declares `modals: true` and the page
+  mounts `studio/modals/_scoped_host` on a `profileModals` store, so the row works
+  in an app that renders no shared modal host at all (mcritchie-industries,
+  moms-app, acquisition-studio) and is not shadowed in the apps that ship a fork of
+  `studio/modals/_host` (mcritchie-studio, turf-monster). **No host app has to
+  touch its layout to get a working avatar cropper.** cropper.js loads only when
+  a resolved row actually needs it.
+
+- **`Studio.profile_sections` — declare the rows, per app.** Same shape as
+  `Studio.sidebar_sections`: a static Array or a callable receiving the view, keys
+  symbolized, `admin: true` rows gated. Compose against
+  `Studio.default_profile_sections` so a later release that adds a standard row
+  delivers it to you:
+
+  ```ruby
+  Studio.configure do |config|
+    config.profile_sections = ->(view) {
+      Studio.default_profile_sections +
+        [ { key: :wallet, title: "Identities", partial: "profiles/wallet" } ]
+    }
+  end
+  ```
+
+  Drop a standard row by key instead of restating the list:
+  `config.profile_sections = Studio.default_profile_sections.reject { |s| s[:key] == :avatar }`.
+
+  **`nil` — the default — means the standard page, NOT a blank one.** That
+  distinction is what makes an empty initializer produce a working page.
+
+  A row may declare `requires:` — an attribute the current user must respond to —
+  and is **dropped when this host's model does not have it**. The consuming apps
+  genuinely disagree about `users` (mcritchie-industries has eight columns and no
+  `first_name`; turf-monster has forty), so a shared page that assumed a column
+  would raise `NoMethodError` on every signed-in request there. MI gets a page
+  with the photo row and no name row until it installs the standard profile
+  columns, at which point the row appears with no code change.
+
+- **`Studio::UserProfile` — the display helpers, written once.** A model concern
+  supplying `display_name`, `avatar_initials`, `avatar_color` and
+  `AVATAR_COLORS`. `components/_avatar` has always called all three and the engine
+  has never provided any of them, so all three apps wrote their own — and they had
+  drifted (`"anon"` vs `"User"` for the same empty state; two different email-prefix
+  casings). `include Studio::UserProfile` and delete your copy. Every method is
+  overridable by defining it in the class body.
+
+  **Adopting changes behavior in mcritchie-industries**, deliberately: a user with
+  no name now falls back to `"anon"` rather than `"User"`, and an email-derived
+  name is capitalized. The merged chain is
+  `username → name → first_name → email prefix → truncated wallet → "anon"`,
+  respond_to?-guarded at every link.
+
+- **`Studio::ProfileImage` — one allowlist for profile uploads.** `ALLOWED_CONTENT_TYPES`
+  (PNG, JPEG, WebP), `MAX_BYTES` (8 MB) and `acceptable?(file)`, lifted from
+  turf-monster's `ApplicationController#valid_image?`. It is an allowlist rather
+  than a `start_with?("image/")` check because an avatar is attacker-supplied
+  bytes served back to other people, and an SVG is a script host wearing an
+  image's content type.
+
+- **`Studio::FIRST_NAME_MAX_LENGTH`** (40) — one constant for a column now written
+  from two surfaces (the onboarding step and `/profile`) and rendered by a third
+  (the form's `maxlength`). `Studio::OnboardingController::MAX_FIRST_NAME` now
+  reads it instead of defining a second copy.
+
 ### Changed
 
+- **`components/_user_nav` no longer renders a dead link.** The username and
+  avatar point at **a host's own `account_path` where it exists**, at
+  `profile_path` otherwise, and render as **plain text** when neither exists.
+  The name and the picture still render in that last case — only the link is
+  dropped. Previously both were `href="#"`.
+
+  **The host's page wins deliberately** — the engine does not repoint an app that
+  already has an account page of its own. No consumer exercises that branch today
+  (turf-monster is the only app with an `account_path`, and it forks this partial
+  anyway), so it is a rule for the apps that adopt `/profile` later rather than a
+  behavior change now.
+
+  So: **no consumer's navbar destination changes on this upgrade.**
+  mcritchie-industries and acquisition-studio gain a working link where they had
+  `href="#"`; every other consumer forks the partial and is untouched.
+
 - **No pre-registered email seeds a logo — `magic_link` was the last one, and it
   seeded the Studio wordmark onto the SIGN-IN email.** `STANDARD`'s `magic_link`
   entry carried `logo: "emails/logo-horizontal.png"`, and

data/app/controllers/studio/onboarding_controller.rb

@@ -23,7 +23,11 @@ module Studio
     # Both actions are for the freshly signed-in user, so authentication is the
     # host's default require_authentication — no skip_before_action here.
 
-    MAX_FIRST_NAME = 40
+    # The shared cap (Studio::FIRST_NAME_MAX_LENGTH). Kept under the old name
+    # here because it is referenced from outside this class; what changed is that
+    # it is no longer a SECOND definition of the same number. /profile writes the
+    # same column and now reads the same constant.
+    MAX_FIRST_NAME = Studio::FIRST_NAME_MAX_LENGTH
 
     # POST /onboarding/first_name
     #

data/app/controllers/studio/profiles_controller.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Studio
+  # /profile — the shared account page every Studio app gets.
+  #
+  # A plain host-inherited controller in the same shape as StyleController and
+  # Studio::EmailsController: its view is a bare content wrapper, so it renders
+  # inside each host's application layout and picks up that app's navbar, theme
+  # and flash. The engine supplies the page; the app supplies the frame.
+  #
+  # WHY /profile AND NOT /account (2026-08-14, operator's call). turf-monster owns
+  # `AccountsController` and the `account_path` helper today. Drawing a shared
+  # /account route would raise `Invalid route name, already in use` while turf's
+  # own routes.rb loads, which takes down EVERY route in that app — the exact
+  # failure that forced draw_admin_emails_routes and draw_onboarding_routes to be
+  # opt-in. `profile` is unclaimed in all five consumers, so this page can be
+  # drawn by default, which is what makes a brand-new app correct on day one.
+  #
+  # It also buys the migration path: turf keeps /account working untouched while
+  # its rows move to /profile one at a time, and /account is deleted only once it
+  # is empty. Two pages briefly coexisting is the point, not an accident.
+  #
+  # WHAT ROWS RENDER is Studio.profile_sections — see lib/studio/profile_sections.rb.
+  # Iteration one ships two: the avatar and the first name.
+  class ProfilesController < ::ApplicationController
+    # The host's own guard, supplied by Studio::ErrorHandling and format-aware
+    # (HTML redirects to login; JSON gets a clean 401 rather than a 406).
+    before_action :require_authentication
+
+    # THE shared cap, not a copy of it — see Studio::FIRST_NAME_MAX_LENGTH. The
+    # onboarding step writes this same column and reads this same constant, so
+    # the two surfaces cannot drift apart.
+    MAX_FIRST_NAME = Studio::FIRST_NAME_MAX_LENGTH
+
+    def show
+      @profile_sections = Studio.profile_sections_for(view_context)
+    end
+
+    # PATCH /profile — the scalar fields. Today that is the first name.
+    def update
+      return unsupported("name") unless row_rendered?(:first_name)
+
+      value = normalized_first_name
+
+      if value.blank?
+        return redirect_to profile_path, alert: "Enter your first name.", status: :see_other
+      end
+
+      rescue_and_log(target: current_user) do
+        attrs = { first_name: value }
+        # Backfill `name` when it is blank so the display-name chain has
+        # something better than an email prefix to show. Same rule as the
+        # onboarding step, which writes this column from the other direction.
+        attrs[:name] = value if current_user.respond_to?(:name) && current_user.name.blank?
+
+        if current_user.update(attrs)
+          # Read back rather than trusting the write. A host whose before_save
+          # DERIVES first_name from name (turf-monster's set_name_parts does
+          # exactly that) would silently discard the value, and a flash saying
+          # "Saved" over a discarded write is worse than a plain failure.
+          # Reporting what actually persisted keeps the page honest on a host the
+          # engine has not met yet.
+          persisted = current_user.reload.first_name.to_s
+
+          if persisted == value
+            redirect_to profile_path, notice: "Name updated."
+          else
+            redirect_to profile_path,
+                        alert: "This app derives your name from another field — it saved as #{persisted.presence || "blank"}.",
+                        status: :see_other
+          end
+        else
+          redirect_to profile_path,
+                      alert: current_user.errors.full_messages.to_sentence.presence || "Could not save that name.",
+                      status: :see_other
+        end
+      end
+    end
+
+    # PATCH /profile/avatar — the picture, on its own route.
+    #
+    # SEPARATE FROM #update deliberately: an attachment param submitted empty
+    # PURGES the attachment, so a combined form that carried both would delete
+    # someone's avatar every time they edited their name. turf-monster learned
+    # this and branched inside its own #update; a separate route is the same
+    # lesson expressed so the trap cannot be reintroduced.
+    def avatar
+      return unsupported("profile photo") unless row_rendered?(:avatar)
+
+      file = params.dig(:profile, :avatar)
+
+      if file.blank?
+        return redirect_to profile_path, alert: "Choose an image first.", status: :see_other
+      end
+
+      unless Studio::ProfileImage.acceptable?(file)
+        return redirect_to profile_path, alert: Studio::ProfileImage::MESSAGE, status: :see_other
+      end
+
+      rescue_and_log(target: current_user) do
+        current_user.avatar.attach(file)
+        redirect_to profile_path, notice: "Photo updated."
+      end
+    end
+
+    # PATCH /profile/email — change the address, from any signed-in session.
+    #
+    # DIRECT, not out-of-band (operator's call, 2026-08-14). An earlier build
+    # mailed a confirmation link to the current address and applied the change
+    # only when the holder of that inbox clicked it. That is the stronger flow and
+    # it is gone on purpose: the session is now the authority.
+    #
+    # What that trades away, stated so nobody has to rediscover it: a hijacked
+    # session can move the account to another inbox, and the old address no
+    # longer gets a veto. Two things are kept BECAUSE the veto is gone —
+    #
+    #   * the OLD address is mailed after every change (OPSEC-046), so a change
+    #     nobody made is visible to the person losing the account, and
+    #   * every OTHER session is invalidated (OPSEC-045), so a hijacker holding a
+    #     second cookie loses it the moment the address moves.
+    #
+    # THE GOOGLE EXCEPTION. An account with a linked Google identity cannot
+    # change its email here: Google is the authoritative source for that address,
+    # and letting the two drift means the next OAuth sign-in either re-links to a
+    # stranger's row or fails to find its own. Unlink Google first, then change it.
+    def email
+      return unsupported("email") unless row_rendered?(:email)
+
+      if Studio::OauthIdentity.google_linked?(current_user)
+        return redirect_to profile_path, status: :see_other,
+                           alert: "Your email comes from your linked Google account. " \
+                                  "Unlink Google first if you want to change it."
+      end
+
+      value = params.dig(:profile, :email).to_s.strip
+      current = current_user.email.to_s
+
+      return redirect_to profile_path, alert: "Enter an email address.", status: :see_other if value.blank?
+
+      if value.casecmp?(current)
+        return redirect_to profile_path, alert: "That is already your email address.", status: :see_other
+      end
+
+      rescue_and_log(target: current_user) do
+        unless current_user.update(email: value)
+          next redirect_to profile_path, status: :see_other,
+                           alert: current_user.errors.full_messages.to_sentence.presence ||
+                                  "Could not save that address."
+        end
+
+        # The new address has not been proved yet; the host's own verification
+        # flow picks it up from here.
+        current_user.update_columns(email_verified_at: nil) if current_user.respond_to?(:email_verified_at)
+
+        # ROTATE FIRST, MAIL SECOND — the order matters and it was the other way
+        # round. Studio::Email.deliver can raise (a host's delivery record is a
+        # create! plus perform_later with no rescue at that level), and a mail
+        # failure between the write and the rotation would leave the address
+        # changed with every other session still live. That is the exact window
+        # OPSEC-045 exists to close, so it closes before anything that can throw.
+        # turf-monster's own apply_email_change rotates first for the same reason.
+        if current_user.respond_to?(:regenerate_session_token!)
+          current_user.regenerate_session_token!
+          # Re-establish THIS session. Rotating without it signs out the very
+          # person who just made the change — correct when the actor arrived from
+          # a confirmation link, wrong now that the actor IS the session.
+          session[:session_token] = current_user.session_token if current_user.respond_to?(:session_token)
+        end
+
+        if current.present?
+          Studio::Email.deliver(Studio::ProfileMailer, :email_change_notification,
+                                current_user, current, value, to: current, user: current_user)
+        end
+
+        redirect_to profile_path, notice: "Email changed to #{value}."
+      end
+    end
+
+    # DELETE /profile/google — drop the linked Google identity.
+    #
+    # REFUSES WHEN IT WOULD ORPHAN THE ACCOUNT. turf-monster's version is an
+    # unconditional `update!(provider: nil, uid: nil)`; for an account whose only
+    # sign-in is Google (no email, so no magic link; no wallet; no password) that
+    # locks someone out of their own account behind a button labelled "Unlink".
+    # It is safe in turf only because turf's users happen to carry an email —
+    # a property of that app's data, not of the code.
+    #
+    # Studio::OauthIdentity gates on Studio.auth_methods, not merely on the
+    # column: an app with an email column that does not offer magic-link sign-in
+    # cannot use it to get back in.
+    def unlink_google
+      return unsupported("Google account") unless row_rendered?(:google)
+
+      unless Studio::OauthIdentity.google_linked?(current_user)
+        return redirect_to profile_path, alert: "No Google account is linked.", status: :see_other
+      end
+
+      if Studio::OauthIdentity.unlink_orphans_account?(current_user)
+        return redirect_to profile_path, status: :see_other,
+                           alert: "Google is the only way to sign in to this account. " \
+                                  "Add an email address first, then unlink."
+      end
+
+      rescue_and_log(target: current_user) do
+        current_user.update!(provider: nil, uid: nil)
+        redirect_to profile_path, notice: "Google account unlinked."
+      end
+    end
+
+    private
+
+    # Would the page render this row for this viewer?
+    #
+    # A HIDDEN ROW IS NOT A GUARD. Studio::ProfileSections drops a row this host
+    # cannot serve, so nobody SEES a first-name form in an app without the
+    # column — but the endpoint stays open to anyone who posts to it, and
+    # rescue_and_log RE-RAISES, so an unguarded write is a 500 plus an ErrorLog
+    # row. Three of the five consumers have an avatar attachment and no
+    # first_name column right now.
+    #
+    # ASKED OF THE RESOLVER, not of one of its rules — and that distinction was a
+    # real bug, caught in review. This used to call served_by?, which answers only
+    # the MODEL gate (`requires:`). Once rows also carried an APP gate (`if:`),
+    # the two questions came apart: mcritchie-industries drops the Google row
+    # because it offers no Google sign-in, while the endpoint — asking only about
+    # columns it does have — stayed open. The comment here claimed they "cannot
+    # drift" while they were already drifting.
+    #
+    # Asking the resolver makes that true rather than asserted: the page and the
+    # endpoint run the same code and get the same answer, whatever gates a row
+    # grows next.
+    def row_rendered?(key)
+      profile_rows.any? { |section| section[:key] == key.to_sym }
+    end
+
+    # Memoized per request: a host's `if:` may be a lambda doing real work, and a
+    # write should not pay for it more than once.
+    def profile_rows
+      @profile_rows ||= Studio.profile_sections_for(view_context)
+    end
+
+    # Land the person back on a page that works rather than on a bare 404. This
+    # is unreachable through the UI — the row that posts here is not rendered —
+    # so the wording is for whoever is poking at the endpoint directly.
+    def unsupported(label)
+      redirect_to profile_path,
+                  alert: "This app has no #{label} to change.",
+                  status: :see_other
+    end
+
+    # Collapse runs of whitespace and cap the length. Done here rather than in a
+    # model validation because the engine does not own the host's User class.
+    def normalized_first_name
+      params.dig(:profile, :first_name).to_s.strip.gsub(/\s+/, " ")[0, MAX_FIRST_NAME].to_s
+    end
+  end
+end

data/app/mailers/studio/profile_mailer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Studio
+  # The two emails an email change sends.
+  #
+  # NAMESPACED, and that is load-bearing rather than tidiness. `app/mailers` is an
+  # autoload path and this engine is not isolated, so a host that defines a
+  # top-level `UserMailer` SHADOWS the engine's outright. Two consumers do:
+  # mcritchie-studio (which defines no email-change actions, so a bare call would
+  # raise NoMethodError) and turf-monster (which defines `email_change_confirmation`
+  # and `email_change_notification` ALREADY, with its own signature and its own
+  # `confirm_email_change_url` pointing at /account). That second case is the
+  # dangerous one: no exception, no warning, and the engine's flow quietly mails a
+  # link to turf's route instead of its own.
+  #
+  # Under `Studio::` nothing shadows it, following Studio::NewsletterMailer.
+  #
+  # ONE EMAIL, and it goes to the address being LEFT:
+  #
+  #   email_change_notification → the OLD address, after the change lands. With
+  #     the change applying directly from any signed-in session, this mail is the
+  #     only thing that makes a change nobody made VISIBLE to the person losing
+  #     the account. That is why it survives and why it is sent even though
+  #     nothing about it is required for the change to work.
+  class ProfileMailer < ApplicationMailer
+    layout "branded_mailer"
+
+    # To the OLD address, after the swap landed.
+    def email_change_notification(user, old_email, new_email)
+      @user      = user
+      @app_name  = Studio.app_name
+      @old_email = old_email
+      @new_email = new_email
+
+      @banner     = Studio::Banner.for(:email_change_notification, name: display_name_for(user))
+      @banner_url = Studio::EmailCatalog.resolved_url(:email_change_notification)
+      @banner_alt = [@banner&.header, "your #{@app_name} email was changed"].compact.join(" — ")
+
+      mail(to: old_email, subject: Studio::EmailCatalog.subject_for(:email_change_notification, name: display_name_for(user)))
+    end
+
+    private
+
+    # The engine's User contract guarantees display_name, but this mailer is also
+    # reachable from a host whose model is mid-migration; a name is a nicety and
+    # must never be the reason an email fails to send.
+    def display_name_for(user)
+      return nil unless user.respond_to?(:display_name)
+
+      user.display_name
+    rescue StandardError
+      nil
+    end
+  end
+end