studio-engine 0.58.1 → 0.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 349b589e663f401c61c9d310aaf72e9f86dc63c5dc77cb8ef90ff36904d3ea94
-  data.tar.gz: 614fb35d60924ca44cb8c8f89b0acf48b821f3a325728048c3cc141983976155
+  metadata.gz: 9bf3942309a578282c3ed5d194123c773c659fde728ac53db036f29abee6d09f
+  data.tar.gz: 96dcf654f30bbbc63d7682394b24460091acbc52d310b39cb065ae771e3108a0
 SHA512:
-  metadata.gz: e95e3ead35e2e1e91b22660e8fb4b1beb4509681129c56358c74e20bf8d460bb39f1edbca7ce787789ef7f38d8cf8ecfebc9372e4e417f749a38ea806bf1b279
-  data.tar.gz: d8eb124ab7bdba7b5fbeb6f2b90c56f6528c6e65be7db24768a3f709daf300d8574124837936ac65269722252bf97e40ab5e34f57a9cb06eace380d3ace1b0d2
+  metadata.gz: 67264dd6f10ab6be519740067057f7e39c1d960976e7409b3524de3e61f094bc523172e5e1721dfd09c1bfe95c6bc935c5ccd133696bbdbc581e046b8c1da0f7
+  data.tar.gz: a210c2bbd8591ea197438150788be7594dca951ce7405f975e91892376b739218e0f048ffec483ca702d23573b429b44f104a75b8ca8a67091522a4496b74209

data/CHANGELOG.md

@@ -188,6 +188,49 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **The Geo signpost now reaches every app whose admin chrome the engine owns.**
+  The row added last release went into `components/_admin_dropdown` alone, on the
+  premise that the shared dropdown reaches every app from one change. It does
+  not, and counted against the apps that actually consume this engine it reached
+  **none of them**. Wherever a host declares an admin-flagged sidebar section,
+  `studio_sidebar_replaces_admin_menu?` SUPPRESSES the dropdown and the link
+  sidebar is the admin menu — that is both `mcritchie-studio` and
+  `mcritchie-industries`. An app that forks its navbar outright renders neither,
+  which is `turf-monster`. Nobody was left on the plain engine navbar to see it,
+  so the app carrying the largest admin surface in the ecosystem was among those
+  guaranteed never to.
+
+  The row moved into its own partial, **`components/_geo_signpost`**, and BOTH
+  engine chromes render it — the dropdown as before, and
+  `components/_link_sidebar` under its own admin-chipped `Geo` heading. Nothing
+  to configure: a host on either chrome gets the signage from the version bump.
+
+  **Exactly one of them, never both.** The sidebar carries the row only where it
+  IS the admin menu (the host declared an admin-flagged section, so the dropdown
+  is suppressed). A host declaring only public sections renders BOTH chromes by
+  design, and there the dropdown keeps the row — fixing a reach gap by showing
+  an admin the same row twice is not a fix.
+
+  **A forked chrome still needs one line**, because the engine cannot reach a
+  fork by rendering. Inside your own admin block:
+
+  ```erb
+  <%= render "components/geo_signpost",
+        variant: :sidebar, close_action: "$store.sidebars.gearOpen = false" %>
+  ```
+
+  `variant:` picks the chrome's row shape (`:dropdown`, the default, or
+  `:sidebar`); `close_action:` is the Alpine expression that closes YOUR panel
+  behind the row — the store flag belongs to the caller, so the partial never
+  hardcodes one. See [`docs/GEO.md`](docs/GEO.md#finding-the-page--the-signpost-in-whichever-chrome-the-app-has).
+
+  Behavior is otherwise unchanged: same three states, same words, same
+  self-gating on `admin?`, and `ENABLE_GEO_BLOCKING` still governs the LINK and
+  never the gate. One test hook was renamed — `data-test="geo-signpost-disabled"`,
+  was `admin-dropdown-geo-disabled` — since the row renders in two chromes now
+  and a name claiming one of them was a lie. Grepped ecosystem-wide first: it
+  appeared in no consumer.
+
 - **`.conic-surface` keeps its wash inside its own box.** The wash was an
   OVERSIZED pseudo (`inset: -50%`) spun by a `transform` keyframe, cut back to
   the element by the host's `overflow: hidden`. That clip is not dependable: the

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

@@ -13,29 +13,10 @@
   <div x-show="open" x-cloak @click.outside="open = false" x-transition:enter="transition ease-out duration-100" x-transition:enter-start="opacity-0 scale-95" x-transition:enter-end="opacity-100 scale-100" x-transition:leave="transition ease-in duration-75" x-transition:leave-start="opacity-100 scale-100" x-transition:leave-end="opacity-0 scale-95" class="absolute right-0 mt-2 w-44 bg-surface border border-subtle rounded-lg shadow-lg z-50 py-1">
     <a href="/admin/theme" class="block px-4 py-2 text-sm text-body hover:text-heading hover:bg-surface-alt transition">Theme</a>
     <a href="/admin/navbar" class="block px-4 py-2 text-sm text-body hover:text-heading hover:bg-surface-alt transition">Navbar</a>
-    <%# GEO — shown in every app, LIVE only where it can actually be used.
-        A disabled row rather than a hidden one is the whole point: an app that has
-        not turned geo on still learns the feature exists and what to set, instead
-        of it being invisible until someone reads the gem's docs.
-
-        Two prerequisites, and the row says WHICH is missing, because they are
-        fixed in different places — an env var on the dyno, a line in the app's
-        initializer. The route check is not decoration: where draw_geo_routes is
-        false, `admin_geo_path` does not exist and calling it RAISES, so the
-        disabled branch must never reach for the helper. %>
-    <% geo_routes = respond_to?(:admin_geo_path) %>
-    <% if Studio.geo_blocking_enabled? && geo_routes %>
-      <a href="<%= admin_geo_path %>" class="block px-4 py-2 text-sm text-body hover:text-heading hover:bg-surface-alt transition">Geo</a>
-    <% else %>
-      <span class="block px-4 py-2 text-sm text-muted cursor-not-allowed select-none"
-            data-test="admin-dropdown-geo-disabled"
-            title="<%= geo_routes ? "Set ENABLE_GEO_BLOCKING=true to manage geo blocking" : "Set config.draw_geo_routes = true in config/initializers/studio.rb, then ENABLE_GEO_BLOCKING=true" %>">
-        Geo
-        <span class="block text-xs text-muted">
-          <%= geo_routes ? "Set ENABLE_GEO_BLOCKING=true" : "Draw the geo routes first" %>
-        </span>
-      </span>
-    <% end %>
+    <%# GEO — the signpost lives in components/_geo_signpost, because this
+        dropdown is only ONE of the engine's two admin chromes and an app on the
+        other one never renders this file. Same row, same policy, both chromes. %>
+    <%= render "components/geo_signpost" %>
     <a href="/error_logs" class="block px-4 py-2 text-sm text-body hover:text-heading hover:bg-surface-alt transition">Error Logs</a>
   </div>
 </div>

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

@@ -0,0 +1,133 @@
+<%# THE GEO SIGNPOST — one row, rendered into whichever admin chrome the app has.
+
+    WHY IT IS ITS OWN PARTIAL, and not a block inside the dropdown. 0.58.0 put
+    this row in components/_admin_dropdown on the premise that the shared
+    dropdown reaches every app "from one change". It does not. Counted against
+    the apps that actually consume this engine, the row reached NONE of them:
+
+      * an app whose admin menu is the LINK SIDEBAR never renders the dropdown —
+        studio_sidebar_replaces_admin_menu? suppresses it so the two cog glyphs
+        do not read as a double gear. Both mcritchie-studio and
+        mcritchie-industries declare an admin-flagged section, so both are that;
+      * an app that forks the navbar outright renders neither — turf-monster
+        forks _user_nav and _navbar and owns components/_gear_sidebar;
+      * nobody was left on the plain engine navbar to see it.
+
+    So the policy below now has ONE home, and BOTH engine-owned chromes render
+    it: components/_admin_dropdown and components/_link_sidebar. A host that
+    forks its chrome adopts it in one line, inside its own admin block — an ERB
+    render tag around:
+
+      render "components/geo_signpost",
+             variant: :sidebar, close_action: "$store.sidebars.gearOpen = false"
+
+    Locals:
+      variant      — :dropdown (default), the gear dropdown's narrow rows;
+                     :sidebar, the link sidebar's wide emoji rows.
+      close_action — optional Alpine expression run on click, so the panel the
+                     row lives in closes behind it. The flag is the CALLER's
+                     (linkTreeOpen here, gearOpen in a forked chrome), which is
+                     exactly why this partial must not hardcode one.
+
+    ADMIN CHROME, self-gated. The gate lives HERE rather than in each caller so
+    no caller can forget it: the dropdown shipped without one once and offered
+    /admin/theme and /error_logs to signed-out strangers on a public page.
+%>
+<% if respond_to?(:admin?) && admin? %>
+  <%# The two prerequisites, resolved ONCE and shared by both variants — the
+      point of a single partial is that the two chromes cannot drift into
+      disagreeing about whether geo is reachable.
+
+      The route check is not decoration: where draw_geo_routes is false,
+      `admin_geo_path` is not defined at all, so the disabled branch must never
+      reach for it. A NoMethodError here takes down admin chrome on EVERY page.
+
+      They are named separately because they are FIXED in different places — an
+      env var on the dyno, a line in the app's initializer — so the row says
+      which one is missing rather than a vague "unavailable". %>
+  <% geo_routes = respond_to?(:admin_geo_path) %>
+  <% geo_live   = Studio.geo_blocking_enabled? && geo_routes %>
+
+  <%# THE HINT IS TWO PIECES, prose and machine string, and they are separate
+      elements on purpose. The subtitle exists to hand the operator a string to
+      copy, and that string is one unbreakable token — no spaces, and neither an
+      underscore nor an "=" is a break opportunity. Left as one run of text it
+      measured 187px inside the dropdown's 142px content box and painted past the
+      panel's right border, in every theme and at every width.
+
+      Splitting it lets the break class land on the token ALONE: prose still
+      wraps at word boundaries, and only the machine string breaks mid-character.
+      The class is `break-all`, not `break-words`, deliberately — the engine
+      ships no compiled CSS of its own, so a utility reaches a consumer only when
+      that consumer's Tailwind build scans these views. `break-all` is already
+      carried by engine views that print S3 keys, emails and magic URLs, so it is
+      in every consumer's output today; `break-words` appears nowhere in the
+      engine, and a consumer on a stale build would silently render this row with
+      no break at all — the bug again, in production. Widening the panel was the
+      third option and was declined: w-44 is the shared admin menu for every app,
+      and one row's subtitle is not a reason to move it.
+
+      The code string is also the ANSWER to the title-only instruction. In the
+      no-routes branch the initializer line used to live only in `title`, which
+      is mouse-only and invisible on touch; it is visible text now, and `title`
+      keeps the long form with the file path. %>
+  <% geo_lead  = geo_routes ? "Set" : "Draw the geo routes first" %>
+  <% geo_code  = geo_routes ? "ENABLE_GEO_BLOCKING=true" : "config.draw_geo_routes = true" %>
+  <% geo_title = geo_routes ? "Set ENABLE_GEO_BLOCKING=true to manage geo blocking" : "Set config.draw_geo_routes = true in config/initializers/studio.rb, then ENABLE_GEO_BLOCKING=true" %>
+  <% geo_close = local_assigns[:close_action].presence %>
+
+  <%# `local_assigns[...].presence`, not `fetch(:variant, :dropdown)`. fetch only
+      defaults an ABSENT key, so a caller computing the variant inline —
+      `variant: sidebar? && :sidebar` — hands over an explicit nil, and the old
+      `nil.to_sym` raised NoMethodError inside admin chrome on every page. %>
+  <% if local_assigns[:variant].presence&.to_sym == :sidebar %>
+    <%# Sidebar variant: the wide emoji row the link sidebar's own sections use,
+        so an engine-owned row is indistinguishable from a host-declared one. %>
+    <% if geo_live %>
+      <%= link_to admin_geo_path,
+            class: "group flex items-start gap-3 px-4 py-3 text-sm text-body hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:ring-inset transition",
+            "@click": geo_close do %>
+        <span class="text-lg leading-none flex-shrink-0">🌍</span>
+        <span class="min-w-0">
+          <span class="block font-medium truncate">Geo</span>
+          <span class="block text-xs text-muted leading-snug mt-0.5">Country and subdivision blocking</span>
+        </span>
+      <% end %>
+    <% else %>
+      <%# No `select-none` here, and that is the fix rather than an omission: the
+          row's whole job in this state is to hand over the string below, and
+          select-none made it unselectable. role/aria-disabled give a screen
+          reader the "unavailable destination" this paints for a sighted eye. %>
+      <span class="flex items-start gap-3 px-4 py-3 text-sm text-muted cursor-not-allowed"
+            role="link"
+            aria-disabled="true"
+            data-test="geo-signpost-disabled"
+            title="<%= geo_title %>">
+        <span class="text-lg leading-none flex-shrink-0">🌍</span>
+        <span class="min-w-0">
+          <span class="block font-medium truncate">Geo</span>
+          <span class="block text-xs text-muted leading-snug mt-0.5"><%= geo_lead %>
+            <code class="font-mono break-all"><%= geo_code %></code>
+          </span>
+        </span>
+      </span>
+    <% end %>
+  <% else %>
+    <%# Dropdown variant: the narrow row that shipped in 0.58.0, unchanged apart
+        from the test hook, which no longer names one chrome. %>
+    <% if geo_live %>
+      <a href="<%= admin_geo_path %>" class="block px-4 py-2 text-sm text-body hover:text-heading hover:bg-surface-alt transition">Geo</a>
+    <% else %>
+      <span class="block px-4 py-2 text-sm text-muted cursor-not-allowed"
+            role="link"
+            aria-disabled="true"
+            data-test="geo-signpost-disabled"
+            title="<%= geo_title %>">
+        Geo
+        <span class="block text-xs text-muted"><%= geo_lead %>
+          <code class="font-mono break-all"><%= geo_code %></code>
+        </span>
+      </span>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -136,6 +136,47 @@
         <% end %>
       <% end %>
     <% end %>
+
+    <%# THE GEO SIGNPOST — how a sidebar-chrome app gets geo signage at all.
+
+        This panel IS the admin menu wherever the host declares an admin-flagged
+        section (studio_sidebar_replaces_admin_menu?), and in exactly that case
+        the engine suppresses components/_admin_dropdown — so before this block
+        every app on this chrome was guaranteed NEVER to see the row the 0.58.0
+        signpost added, including the one carrying the largest admin surface in
+        the ecosystem. mcritchie-studio is that one:
+        app/views/layouts/application.html.erb renders this partial, and
+        app/helpers/link_tree_helper.rb stamps `admin: true` on every admin
+        section it declares. mcritchie-industries is the other.
+
+        Engine-owned rather than host-declared on purpose. Appending it to
+        Studio.sidebar_sections instead would make studio_sidebar? and
+        studio_sidebar_replaces_admin_menu? true for apps that declare NO
+        sections — raising a sidebar where none existed and taking Theme,
+        Navbar and Error Logs away from apps that rely on the dropdown.
+
+        EXACTLY ONE HOME PER APP, which is what the second half of the gate
+        buys. A host that declares only PUBLIC sections keeps the dropdown —
+        the engine navbar renders BOTH chromes for that shape, deliberately, so
+        its admins never lose Theme, Navbar and Error Logs. Signposting geo here
+        as well would show such an admin the same row twice, in two menus open
+        at the same time. So the row goes wherever the admin menu IS: the
+        dropdown for that shape, this panel for the shape that suppresses the
+        dropdown.
+
+        The predicate is `studio_sidebar_replaces_admin_menu?` (see
+        StudioSidebarHelper), computed here from the sections already in hand
+        rather than called: this partial renders in hosts and test rigs that
+        provide studio_sidebar_sections without the rest of the helper, and a
+        bare call would raise for them. The two must stay the same question —
+        if the helper's rule changes, this changes with it. %>
+    <% if sidebar_admin && sections.any? { |section| section[:admin] } %>
+      <div class="px-4 pt-4 pb-1 label-upper font-bold text-muted flex items-center gap-2">
+        <span>Geo</span>
+        <span class="rounded border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-[10px] font-mono text-primary">ADMIN</span>
+      </div>
+      <%= render "components/geo_signpost", variant: :sidebar, close_action: close_action %>
+    <% end %>
   </nav>
 <% end %>
 

data/app/views/studio/modals/_web3_step_up.html.erb

@@ -0,0 +1,292 @@
+<%#
+  Web3 step-up — the shared "your session cannot sign on-chain" card.
+
+  THE SITUATION IT NAMES: an account that holds a self-custody wallet signs in
+  with a WEB2 credential — a magic link, email, or Google. Both facts are
+  ordinary alone; together they mean the person is signed in but cannot sign
+  anything on-chain. `SessionContext` has modelled that intersection since it was
+  lifted into this engine (`web2?` AND `phantom_linked?`) and nothing acted on
+  it, so every web3 Studio app logged a wallet owner straight in with no web3
+  beat at all. This partial is the missing step; SessionContext stays the state.
+
+  Ported from turf-monster (2026-08-21), where it shipped first as the working
+  vertical. What is NOT shared — and deliberately stays in the host — is WHEN to
+  show it and what it costs to dismiss: the host's policy decides who sees the
+  card, and the host's gates keep their own teeth. This partial owns ONE step.
+
+  ADVISORY BY CONSTRUCTION. The card is dismissible and says so. A self-custody
+  wallet is the one credential a host cannot reset for a user, so a card that
+  could not be closed would lock a legitimate owner out of their own account
+  over a wallet they merely cannot reach right now. That is why the escape hatch
+  below is not optional decoration — and why enforcement must live in the host's
+  on-chain gates, never in this card.
+
+  Locals (all optional, defaults via local_assigns.fetch):
+    heading         — (default "Sign in with your wallet")
+    subtext         — the one-line why
+    help_url        — the escape hatch for a user who cannot reach their wallet
+                      (default "/help"). Set to nil to drop the line entirely.
+    help_label      — (default "Get help")
+    picker_modal_id — the host's brand picker, reached by "Use a different
+                      wallet" (default "wallet-connect"). The picker is expected
+                      to honour a `backTo` prop pointing back at this card.
+    modal_id        — this card's own id, passed to the picker as backTo
+                      (default "web3-step-up")
+    modal_store     — Alpine store name (default "modals"; the living style
+                      guide mounts a page-scoped host and passes "dsModals")
+    dismiss_event   — window event dispatched on dismissal (default
+                      "web3-step-up-dismissed"). The HOST decides what happens
+                      next — typically releasing an onboarding chain it held
+                      while this card had the screen. This partial never opens
+                      another modal itself.
+
+  PROPS (set by the opener, all optional — the host's policy produces them):
+    provider      — normalised brand key ('phantom' / 'solflare' / 'backpack'),
+                    or null when the account linked its wallet before the host
+                    started remembering the brand.
+    providerLabel — how that brand writes its own name, for the row.
+    walletHint    — the truncated address (4…4), so the user can confirm the
+                    card is asking for the wallet they think it is.
+
+  WITH a remembered provider this is ONE row. Without one it is the same card
+  with the picker as its primary action — the fallback is never a dead end.
+
+  CONTRACT WITH THE HOST'S JS. Signing calls `window.solanaConnectAndVerify(name,
+  { linkMode: false })`, the global every web3 Studio app already provides, and
+  hands a success to `window.handleSolanaVerifySuccess` when present. linkMode is
+  deliberately FALSE: the link path binds to the current user but does not grant
+  the on-chain session, which is the thing this card exists to obtain. One
+  inherited consequence, stated plainly: signing with a DIFFERENT wallet signs
+  you into that wallet's account, exactly as a standalone wallet button does. The
+  walletHint is shown precisely so that is a visible choice, not a surprise.
+
+  CRITICAL (Alpine): this partial is cloned from a <template x-if> by the modal
+  host, so it must have ONE root element, and the x-data below is a
+  DOUBLE-QUOTED attribute — a single " anywhere inside it (a code comment
+  included) closes it early and the whole component mounts as a silent no-op that
+  still renders markup. Keep every inner string SINGLE-quoted.
+%>
+<%
+  heading         = local_assigns.fetch(:heading, "Sign in with your wallet")
+  subtext         = local_assigns.fetch(:subtext,
+                      "This account is secured by a Solana wallet. You are signed in, but this " \
+                      "session can’t sign on-chain — so on-chain actions still need your wallet.")
+  help_url        = local_assigns.fetch(:help_url, "/help")
+  help_label      = local_assigns.fetch(:help_label, "Get help")
+  picker_modal_id = local_assigns.fetch(:picker_modal_id, "wallet-connect")
+  modal_id        = local_assigns.fetch(:modal_id, "web3-step-up")
+  modal_store     = local_assigns.fetch(:modal_store, "modals")
+  dismiss_event   = local_assigns.fetch(:dismiss_event, "web3-step-up-dismissed")
+%>
+<div x-data="{
+       get props() { var c = $store.<%= modal_store %>.current(); return (c && c.props) || {}; },
+       connecting: false,
+       error: '',
+       // Set when the remembered wallet turns out not to be reachable in THIS
+       // browser (a different machine, the extension removed). It flips the card
+       // to the picker rather than leaving the user pressing a button that
+       // cannot work.
+       providerMissing: false,
+       // Which wallets this document can actually see. Read on a poll, NOT once
+       // at mount: wallet provider registration fills in asynchronously, and
+       // this card auto-opens on the render right after auth — the worst
+       // possible moment. A single early read is a coin flip that would badge an
+       // installed wallet as missing.
+       wallets: [],
+       _poll: null,
+       _onRegister: null,
+       get provider() { return this.props.provider || null; },
+       get providerLabel() { return this.props.providerLabel || null; },
+       get walletHint() { return this.props.walletHint || null; },
+       // One-click only while we remember a brand AND it is still reachable.
+       get canOneClick() { return !!this.provider && !this.providerMissing; },
+       // Does the remembered brand answer in THIS document right now? Drives the
+       // Installed badge, the same one the connect picker shows, so a detected
+       // wallet reads identically in both places.
+       get detected() {
+         var name = ('' + (this.provider || '')).toLowerCase();
+         if (!name) return false;
+         return (this.wallets || []).some(function(w) { return w.name && w.name.toLowerCase() === name; });
+       },
+       init() {
+         var self = this;
+         this.refresh();
+         this._onRegister = function() { if (!self.connecting) self.refresh(); };
+         window.addEventListener('wallet-standard:register-wallet', this._onRegister);
+         this._poll = setInterval(function() {
+           if (self.connecting) return;
+           self.refresh();
+           if (self.wallets.length > 0) { clearInterval(self._poll); self._poll = null; }
+         }, 1000);
+       },
+       destroy() {
+         if (this._poll) clearInterval(this._poll);
+         if (this._onRegister) window.removeEventListener('wallet-standard:register-wallet', this._onRegister);
+       },
+       refresh() {
+         this.wallets = (window.walletProvider && window.walletProvider.available && window.walletProvider.available()) || [];
+       },
+       reachable(name) {
+         if (!window.walletProvider || !window.walletProvider.get) return false;
+         return !!window.walletProvider.get(name);
+       },
+       async signIn() {
+         if (this.connecting) return;
+         var name = this.provider;
+         if (!name) return this.openPicker();
+         if (!this.reachable(name)) {
+           this.providerMissing = true;
+           this.error = 'We could not reach your ' + (this.providerLabel || 'wallet') + ' in this browser.';
+           return;
+         }
+         if (typeof window.solanaConnectAndVerify !== 'function') {
+           this.error = 'Wallet sign-in is unavailable on this page.';
+           return;
+         }
+         this.connecting = true; this.error = '';
+         try {
+           var result = await window.solanaConnectAndVerify(name, { linkMode: false });
+           if (result && result.success) {
+             if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
+             // Reload rather than follow a redirect: the user was already
+             // somewhere, and the only thing that changed is that this session
+             // can now sign. Sending them to a post-login landing would move
+             // them off the page they were reading.
+             window.location.reload();
+             return;
+           }
+           this.error = (result && result.error) || 'Verification failed.';
+         } catch (e) {
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
+           this.error = msg;
+         }
+         this.connecting = false;
+       },
+       // Hand off to the host's brand picker. swap() rather than open() so the
+       // picker's back arrow returns HERE instead of stranding the user.
+       openPicker() {
+         if (this.connecting) return;
+         $store.<%= modal_store %>.swap('<%= picker_modal_id %>',
+           { backTo: '<%= modal_id %>', stepUpProps: this.props, returnUrl: window.location.href });
+       },
+       // Dismiss. Dispatched so the HOST knows this card is done and can release
+       // whatever it was holding — this partial never opens another modal.
+       dismiss() {
+         if (this.connecting) return;
+         window.dispatchEvent(new CustomEvent('<%= dismiss_event %>'));
+         $store.<%= modal_store %>.close();
+       }
+     }"
+     class="relative">
+
+  <%# Brand sprite — MUST live inside this card's single root so the host's
+      <template x-if> clones it along with the card. A sibling of the root is
+      dropped and the icon paints empty. %>
+  <%= render "studio/modals/blocks/wallet_brand_sprite" %>
+
+  <div class="relative mb-1">
+    <button @click="dismiss()" :disabled="connecting"
+            class="absolute top-0 right-0 -mr-1 text-secondary hover:text-heading text-xl leading-none disabled:opacity-50"
+            aria-label="Close">&times;</button>
+  </div>
+
+  <%= render "studio/modals/blocks/card_header", icon_emoji: "🔐", title: heading do %>
+    <p class="text-sm text-body"><%= subtext %></p>
+  <% end %>
+
+  <%# PRIMARY — THE STANDARD WEB3 AUTH BUTTON: a wallet row, not a filled CTA.
+      Same shape the connect picker uses — brand mark, the wallet's own name, an
+      Installed badge, chevron — so a wallet reads identically everywhere it is
+      offered and this card does not invent a third look for one action.
+
+      It carries `pulse-cta` (engine-motion) because it is the ONE target on the
+      card and the whole point of the card is that the user should press it. %>
+  <template x-if="canOneClick">
+    <div>
+      <button type="button" @click="signIn()" :disabled="connecting"
+              style="--pulse-cta-color: var(--color-primary); --pulse-cta-strength: 0.4; --pulse-cta-scale: 1.02"
+              class="pulse-cta w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left disabled:opacity-60 disabled:cursor-wait">
+        <span class="w-9 h-9 rounded-lg overflow-hidden flex items-center justify-center shrink-0">
+          <svg class="w-9 h-9" aria-hidden="true"><use :href="'#se-wallet-' + provider"></use></svg>
+        </span>
+        <span class="font-semibold text-heading" x-text="providerLabel"></span>
+        <span class="ml-auto flex items-center gap-2">
+          <span x-show="connecting" class="inline-flex items-center gap-1.5 text-xs text-secondary"><span class="spinner" aria-hidden="true"></span>Connecting&hellip;</span>
+          <span x-show="!connecting && detected" class="badge border-primary text-primary">Installed</span>
+          <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4 text-muted">
+            <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+          </svg>
+        </span>
+      </button>
+      <%# One line on what pressing it DOES. A signature prompt is alarming
+          without it, and "no funds move" is the difference between clicking and
+          bailing. The address rides here so the user can confirm the card is
+          asking for the wallet they think it is. %>
+      <p class="text-[11px] text-muted mt-1.5 px-1">
+        Signing proves the wallet is yours &mdash; it does not move any funds.
+        <template x-if="walletHint">
+          <span>Wallet <span class="font-mono text-secondary" x-text="walletHint"></span></span>
+        </template>
+      </p>
+    </div>
+  </template>
+
+  <%# No remembered brand — the same row shape with no mark to show, so the two
+      halves of this card look like one card. %>
+  <template x-if="!canOneClick">
+    <button type="button" @click="openPicker()" :disabled="connecting"
+            style="--pulse-cta-color: var(--color-primary); --pulse-cta-strength: 0.4; --pulse-cta-scale: 1.02"
+            class="pulse-cta w-full flex items-center gap-3 p-3 rounded-xl bg-surface-alt border border-strong hover:bg-surface transition text-left disabled:opacity-60">
+      <%# A neutral wallet mark, NOT an emoji. This tile sits inches from a real
+          brand mark, so a platform emoji (the first pass used U+1F45B PURSE)
+          reads as a pink handbag next to Phantom and is the one thing on the
+          card that belongs to no design system. Stroked in the same idiom as
+          the chevron beside it, on theme tokens.
+
+          A billfold: body plus clasp, and NO band across the top. The first
+          drawing had one and it read as a credit-card magstripe at 20px — the
+          wrong object on a card whose whole subject is a wallet. %>
+      <span class="w-9 h-9 rounded-lg bg-inset flex items-center justify-center shrink-0" aria-hidden="true">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" class="w-5 h-5 text-secondary">
+          <rect x="3" y="6.5" width="18" height="11" rx="2.5" />
+          <circle cx="16.6" cy="12" r="1.3" fill="currentColor" stroke="none" />
+        </svg>
+      </span>
+      <span class="font-semibold text-heading">Connect your wallet</span>
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="ml-auto w-4 h-4 text-muted">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+      </svg>
+    </button>
+  </template>
+
+  <template x-if="error">
+    <p class="text-red-400 text-sm mt-3 text-center" x-text="error"></p>
+  </template>
+
+  <%# SECONDARY — always reachable, so a user whose remembered wallet is the
+      wrong one is never cornered by our memory of it. %>
+  <template x-if="canOneClick">
+    <button type="button" @click="openPicker()" :disabled="connecting"
+            class="mt-3 block w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Use a different wallet
+    </button>
+  </template>
+
+  <div class="mt-4 pt-3 border-t border-strong">
+    <button type="button" @click="dismiss()" :disabled="connecting"
+            class="block w-full text-center text-sm text-secondary hover:text-heading disabled:opacity-50">
+      Not now
+    </button>
+    <%# THE ESCAPE HATCH. A self-custody wallet is the one credential a host
+        cannot reset for the user, so the card must not end without a way to
+        reach a human. Droppable only by passing help_url: nil, which is a
+        deliberate act at the callsite rather than an omission. %>
+    <% if help_url.present? %>
+      <p class="mt-2 text-center text-[11px] text-muted">
+        Can&rsquo;t access your wallet?
+        <a href="<%= help_url %>" class="underline hover:text-secondary"><%= help_label %></a>
+      </p>
+    <% end %>
+  </div>
+</div>

data/app/views/style/_modals.html.erb

@@ -340,6 +340,14 @@
         <template x-if="$store.dsModals.current().id === 'wallet-connect'">
           <div><%= render "style/modals/wallet_connect" %></div>
         </template>
+        <%# web3-step-up — the REAL shared partial, not a style-guide specimen.
+            The other Web3 cards here render style/modals/* demos while each app
+            keeps its own live modal; this one renders studio/modals/* — the
+            same file a host renders in production — so what is reviewed here IS
+            the shipped card. modal_store mounts it on this page's own host. %>
+        <template x-if="$store.dsModals.current().id === 'web3-step-up'">
+          <div><%= render "studio/modals/web3_step_up", modal_store: "dsModals" %></div>
+        </template>
         <template x-if="$store.dsModals.current().id === 'onchain-tx'">
           <div><%= render "style/modals/onchain_tx" %></div>
         </template>
@@ -796,6 +804,16 @@
         marks inline from the engine</strong>
         (<code class="font-mono text-2xs">studio/modals/blocks/_wallet_brand_sprite</code>),
         so every app inherits them with no per-app icon files.
+        The two <strong>Web3 step-up</strong> cards are a different kind of thing
+        from the rest of this section: they render
+        <code class="font-mono text-2xs">studio/modals/_web3_step_up</code> &mdash;
+        the <strong>REAL shared partial a host renders in production</strong>,
+        not a style-guide copy of it &mdash; so what you review here is the
+        shipped card, and it cannot drift from what users see. They also carry the
+        <strong>standard web3 auth button</strong>: a wallet row (brand mark, the
+        wallet&rsquo;s own name, Installed badge, chevron) rather than a filled
+        CTA, glowing via <code class="font-mono text-2xs">pulse-cta</code> because
+        it is the one thing to press.
       </p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
@@ -856,6 +874,36 @@
         </div>
       <% end %>
 
+      <%# Web3 step-up — the web2-session-on-a-wallet-account card. NOT part of
+          the three-card walk above: that walk is one on-chain transaction, this
+          is an AUTH state that precedes any of it. Two specimens because the
+          card has exactly two shapes, and the second is what every wallet linked
+          before a host recorded brands will see. %>
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Web3 step-up (remembered wallet)",
+            reference: %(the Web3 Contest "Web3 step-up" card (studio/modals/_web3_step_up — the REAL shared partial, not a specimen copy) — shown to an account that holds a self-custody wallet but authenticated this session with a web2 credential. One wallet row, glowing, because it is the only thing to press. Open with $store.dsModals.open('web3-step-up', { provider: 'phantom', providerLabel: 'Phantom', walletHint: '7xKp…JZ2Q' })),
+            open_expr: "$store.dsModals.open('web3-step-up', { provider: 'phantom', providerLabel: 'Phantom', walletHint: '7xKp…JZ2Q' })",
+            glow_when: ds_glow.call("web3-step-up"),
+            disabled: !web3_on, openable: true } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
+          <div class="text-2xl leading-none">🔐</div>
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-7 w-full rounded-lg border" style="border-color: var(--color-border-strong)"></span>
+        </div>
+      <% end %>
+
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Web3 step-up (no remembered wallet)",
+            reference: %(the Web3 Contest "Web3 step-up" card with NO remembered brand (studio/modals/_web3_step_up) — every wallet linked before a host recorded brands lands here, so it is a live population and not a defensive branch. The row falls back to the picker rather than dead-ending. Open with $store.dsModals.open('web3-step-up', {})),
+            open_expr: "$store.dsModals.open('web3-step-up', {})",
+            disabled: !web3_on, openable: true } do %>
+        <div class="pointer-events-none w-40 rounded-lg bg-surface border border-subtle shadow p-4 text-center space-y-2">
+          <div class="text-2xl leading-none">🔐</div>
+          <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-7 w-full rounded-lg border border-dashed" style="border-color: var(--color-border-strong)"></span>
+        </div>
+      <% end %>
+
       <%# Wallet deposit — standalone top-up card (not part of the walk). %>
       <%= render layout: "style/modal_specimen", locals: {
             label:     "Wallet deposit",

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.58.1"
+  VERSION = "0.60.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.58.1
+  version: 0.60.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
+date: 2026-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -378,6 +378,7 @@ files:
 - app/views/components/_emoji_swap.html.erb
 - app/views/components/_empty_state.html.erb
 - app/views/components/_geo_badge.html.erb
+- app/views/components/_geo_signpost.html.erb
 - app/views/components/_google_logo.html.erb
 - app/views/components/_input.html.erb
 - app/views/components/_json_debug.html.erb
@@ -443,6 +444,7 @@ files:
 - app/views/studio/modals/_load_convention.html.erb
 - app/views/studio/modals/_saving.html.erb
 - app/views/studio/modals/_scoped_host.html.erb
+- app/views/studio/modals/_web3_step_up.html.erb
 - app/views/studio/modals/auth/_resend_footer.html.erb
 - app/views/studio/modals/blocks/_age_verify.html.erb
 - app/views/studio/modals/blocks/_card_header.html.erb