studio-engine 0.47.2 → 0.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 918309978020f15861f65e0a861325bb7ba93046b4d9039aa1aaa1ae6da22c95
-  data.tar.gz: 682e1529aeca6541d08ab5173028bd407b3538fed1e1b9dd3fb88b70b11e0145
+  metadata.gz: fa8ab90a0e1627e7150ed1e96a348bae677c3dc35891ccd2a46f99d857cd74d1
+  data.tar.gz: e2a354a9d1d0533a78c63cb19233ae387a4c71f747cd5bf4570fe8d2478979de
 SHA512:
-  metadata.gz: 3da6d45e75a8adcbb72b39117e416381b6c6962fe4b831ee2a90d4feddd9b60a4c63b969cc85d442780685d0a0c2916fe423e7dd11c1df392d2fa06a3f9267e4
-  data.tar.gz: 40e41ee896e9375ebeb9522afb78a9ed481c57c6f15f7a2681a9a51211cf861875a82125bdc52cc6a3b5b9d9820d46e72bd6b2b961822f46ee39367300564755
+  metadata.gz: d7def604f1a4c19da8241953cee4bfa8e8047af2a2ae0e0113628aeed9f5d59ab5fa16bfe667e89687144f0f0afb5117e1bcd1f4747ab69db9c5b892e142c820
+  data.tar.gz: 7424031597c4168ac6a8172360b7dbc2ee584f0ddc5ac205a155fd11343f7e8f91002a40d3b0865eef0218096234aeaf1617ff2133677aa1e51c9b73d91a8cf3

data/CHANGELOG.md

@@ -4,8 +4,212 @@ 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 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,170 @@
+# 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(:first_name) unless serves?(: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(:avatar) unless serves?(: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
+
+    # 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 serves?(:provider) && serves?(:uid)
+
+      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
+
+    # Can this host's user model serve this field?
+    #
+    # A HIDDEN ROW IS NOT A GUARD. Studio::ProfileSections drops a row the 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. That is not hypothetical: three of the five consumers
+    # (mcritchie-industries, moms-app, acquisition-studio) have an avatar
+    # attachment and no first_name column right now.
+    #
+    # The endpoint asks the SAME question the row does, through the SAME method,
+    # so the two cannot drift into disagreeing about what this app supports.
+    def serves?(attribute)
+      Studio::ProfileSections.served_by?(current_user, attribute)
+    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(attribute)
+      redirect_to profile_path,
+                  alert: "This app has no #{attribute.to_s.tr("_", " ")} 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/models/concerns/studio/user_profile.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Studio
+  # The four things every Studio app's User has had to define for itself: how to
+  # name a person on screen, and how to draw them when they have no picture.
+  #
+  # WHY THIS EXISTS. The engine's own components/_avatar partial calls
+  # `display_name`, `avatar_initials` and `avatar_color` — and the engine has
+  # never provided any of them. Every consumer wrote its own; mcritchie-industries'
+  # user.rb even carries a comment explaining that it must, because the engine's
+  # nav renders the partial. Three copies, and by 2026-08-14 they had drifted:
+  #
+  #   mcritchie-studio      name → email prefix (capitalized) → wallet → "anon"
+  #   mcritchie-industries  name → email prefix (raw)                  → "User"
+  #   turf-monster          username → name → email prefix (cap) → wallet → "anon"
+  #
+  # Same intent, three answers, and two different words for the same empty state.
+  # That is the drift a concern removes.
+  #
+  # ON THE MERGED CHAIN. It is turf-monster's — the richest of the three — with
+  # `first_name` folded in after `name`, because /profile now lets people set that
+  # field and a name someone just typed should be the name they see. Apps missing
+  # a link in the chain simply skip it; the chain is respond_to?-guarded end to
+  # end, so mcritchie-industries' eight-column users table walks it without
+  # raising. One consequence worth stating rather than burying: an MI user with no
+  # name now falls back to "anon" instead of "User", and an email-derived name is
+  # capitalized. That is MI adopting the house standard, and its adoption task
+  # owns the change.
+  #
+  # EVERY METHOD IS OVERRIDABLE. These are plain instance methods from an included
+  # module, so a host that defines its own `display_name` in the class body wins
+  # outright. Standardizing the default is the goal; forbidding an app from having
+  # an opinion is not.
+  module UserProfile
+    extend ActiveSupport::Concern
+
+    # The house palette for initial-circle backgrounds. Identical in all three
+    # apps today, which is the clearest possible signal it belonged here.
+    AVATAR_COLORS = %w[#EF4444 #F97316 #EAB308 #22C55E #06B6D4 #3B82F6 #8B5CF6 #EC4899].freeze
+
+    # What to call this person on screen.
+    def display_name
+      studio_profile_username.presence ||
+        studio_profile_attr(:name).presence ||
+        studio_profile_attr(:first_name).presence ||
+        studio_profile_email_prefix.presence ||
+        studio_profile_wallet.presence ||
+        "anon"
+    end
+
+    # One character for the initials circle. Deliberately NOT derived from
+    # display_name: that chain ends in a wallet address or the word "anon", and
+    # "a" for every anonymous account is worse than a neutral mark.
+    def avatar_initials
+      source = studio_profile_username.presence ||
+               studio_profile_attr(:name).presence ||
+               studio_profile_attr(:first_name).presence ||
+               studio_profile_email_prefix.presence
+
+      # `source[0]`, not ActiveSupport's `String#first`: this module is included
+      # into a host model, and nothing here should depend on which core_ext that
+      # host happens to have loaded. Plain Ruby costs nothing and cannot vanish.
+      source.presence.to_s[0]&.upcase || "?"
+    end
+
+    # A stable colour for this account — same person, same circle, every render.
+    # Hashed rather than random for exactly that reason, and keyed off identity
+    # fields so it survives a display-name change.
+    def avatar_color
+      key = studio_profile_username.presence ||
+            studio_profile_attr(:name).presence ||
+            studio_profile_attr(:email).presence ||
+            id.to_s
+
+      AVATAR_COLORS[Digest::MD5.hexdigest(key.to_s).hex % AVATAR_COLORS.size]
+    end
+
+    private
+
+    # Read an attribute only if this host's model actually has it. The whole
+    # tolerance of the chain lives in this one method.
+    def studio_profile_attr(attribute)
+      return nil unless respond_to?(attribute)
+
+      public_send(attribute)
+    end
+
+    # `username` is turf-monster's on-chain handle and does not exist in the hub
+    # apps. It leads the chain where it exists because it is what that app's
+    # people call each other.
+    def studio_profile_username
+      studio_profile_attr(:username)
+    end
+
+    def studio_profile_email_prefix
+      email = studio_profile_attr(:email)
+      return nil if email.blank?
+
+      email.to_s.split("@").first.to_s.capitalize
+    end
+
+    # Defers to the host's own truncation rather than reformatting an address
+    # here — mcritchie-studio and turf-monster both define `truncated_solana`,
+    # and turf's has to pick between a web2 and a web3 address to do it.
+    def studio_profile_wallet
+      studio_profile_attr(:truncated_solana)
+    end
+  end
+end

data/app/views/components/_user_nav.html.erb

@@ -40,6 +40,33 @@
      end
    end %>
 
+<%# Where the username and the avatar point — resolved ONCE, used by both.
+
+    A HOST'S OWN account_path WINS: an app that already has an account page keeps
+    it rather than being repointed at a thinner /profile by a routine dependency
+    bump. An app adopting /profile flips over by DELETING its account route, so
+    the last step of the migration is the deliberate one.
+
+    NO CONSUMER EXERCISES THAT BRANCH TODAY, and the comment here said otherwise
+    until 2026-08-14. turf-monster is the only app with an account_path, and it
+    ships its own app/views/components/_user_nav.html.erb — a host view SHADOWS
+    the engine's in this non-isolated engine, so turf never renders THIS file.
+    The rule is for apps that adopt /profile later.
+
+    nil when NEITHER exists, and then the name and avatar render as plain text.
+    They used to render `href="#"`, which was not a graceful degradation but a
+    dead link. Who that actually reached: mcritchie-industries and
+    acquisition-studio — the consumers rendering this partial rather than a fork
+    of it. A link that goes nowhere looks identical to one that works until it is
+    clicked, which is why nobody reported it.
+%>
+<% studio_nav_destination =
+     if defined?(account_path)
+       account_path
+     elsif defined?(profile_path)
+       profile_path
+     end %>
+
 <div class="flex gap-2">
   <% if logged_in? %>
     <%# Left column: Div 1 + Div 2 stacked %>
@@ -61,9 +88,11 @@
           <%= render "components/admin_dropdown" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
           <%= render "components/theme_toggle_morph" %>
         </div>
-        <% account_link = defined?(account_path) ? account_path : "#" %>
-        <%= link_to account_link, class: "text-heading font-semibold hover:text-primary transition text-base leading-none truncate text-right" do %>
-          <%= current_user.display_name %>
+        <% nav_name_classes = "text-heading font-semibold hover:text-primary transition text-base leading-none truncate text-right" %>
+        <% if studio_nav_destination %>
+          <%= link_to current_user.display_name, studio_nav_destination, class: nav_name_classes %>
+        <% else %>
+          <span class="<%= nav_name_classes %>"><%= current_user.display_name %></span>
         <% end %>
       </div>
       <% div2_content = studio_nav_slot.call(div2_slot, div2_html) %>
@@ -168,9 +197,14 @@
       <% end %>
     </div>
     <%# Div 3 (Avatar): spans both rows %>
-    <% account_link = defined?(account_path) ? account_path : "#" %>
-    <%= link_to account_link, class: "hover:opacity-80 transition flex-shrink-0 flex items-center", "x-bind:style": "$store.devMode && 'background: lightgreen'" do %>
-      <%= render "components/avatar", user: current_user, size: "nav" %>
+    <% if studio_nav_destination %>
+      <%= link_to studio_nav_destination, class: "hover:opacity-80 transition flex-shrink-0 flex items-center", "x-bind:style": "$store.devMode && 'background: lightgreen'" do %>
+        <%= render "components/avatar", user: current_user, size: "nav" %>
+      <% end %>
+    <% else %>
+      <span class="flex-shrink-0 flex items-center" x-bind:style="$store.devMode && 'background: lightgreen'">
+        <%= render "components/avatar", user: current_user, size: "nav" %>
+      </span>
     <% end %>
   <% else %>
     <%= render "components/admin_dropdown" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>