studio-engine 0.77.4 → 0.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9497ed872cea58d146d2859f8220ad71e3979b2b1603fb263622081c29e3144e
-  data.tar.gz: 7de61f4d57e71e09bf6d5fa32acd0309625e547d52b0d4bbfc45c94f7bd60328
+  metadata.gz: 1a41688fc9d2fd9a08b96ea00d90e971d3be7618577acf83887d7c64b71076d3
+  data.tar.gz: 6930fd3598433185b2c578ebc2f287a54c972828ab73f068800521f76793a82a
 SHA512:
-  metadata.gz: d443cc7d3b914255adef0e681d926c4bb88c92dd1cbe4814195a5a6c55132e95e58550ddb14d6277b717bf6a7778823620c87ab7aa3bba0499373b0db33063b3
-  data.tar.gz: e4e6df7c16f17a790b9058030d2f3b1b519ca882ac13069ea69f641b76974ca9fabd47a0de8ec89d9e8333dfbd428a2fdbdf46334c5d4e046ba4ba737ee2c2fe
+  metadata.gz: c089670e6c2ba85bac8a7851f13f4fa033801e738583974d7207d1960ebccf181530feec5ef3c4cd8f4ae5300d793b5d54eaeb91f46cd9732287f2d44d31ab13
+  data.tar.gz: c6e24cd7de1298e73e58309da359ffcdae06d150e0b13afba52f90f8864782d6c197b22cf7b61279d88a1d98e52b562eafb7f4e76cd968f6088bb77c3fb3b011

data/CHANGELOG.md

@@ -4,6 +4,43 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.79.0 — 2026-09-30
+
+### Changed
+
+- **The signed-in user nav fits a phone.** `components/_user_nav` draws its theme
+  toggle from `md` up only (the navbar's phone row already has one, so phones
+  showed two), and the name and avatar are now ONE link to the account page, one
+  tab stop, where they were two links to the same place. Below `md` the avatar
+  stands alone and the name is screen-reader text. The desktop sidebar button
+  passed as `extra_icons_html`, the admin menu, the account destination, the
+  second row and the banners are unchanged. From `md` up the name now sits beside
+  the avatar, centred on it, rather than on the top row. Apps that shadow the
+  partial (mcritchie-studio, turf-monster, cyvasse) are unaffected until they
+  drop their copy.
+- **Default button fills clear WCAG AA under their white label.** The default
+  success green is `#367E3A` (5.0:1 under white), was `#4BAF50` (2.78:1); a
+  configured success colour paints as before. While an app leaves its primary
+  at the engine default `#8E82FE` (3.1:1), the resolver emits `--color-cta-fill`
+  (`#7268CB`), which `btn-primary`, `btn-outline`'s hover and the user nav's
+  level bar paint; `--color-cta` stays the violet, because apps also paint it
+  as text on dark surfaces. A configured primary emits no fill, so those fall
+  back to the app's own `--color-cta` as before. `--color-cta-hover` is held to
+  AA too, unchanged wherever `darken(primary, 0.30)` already passes. Engine views
+  that painted text or icons with the raw `--color-success` now read
+  `--color-success-ink` (the darker default green is 3.49:1 as text on the dark
+  page).
+
+## 0.78.0 — 2026-09-29
+
+### Added
+
+- **`Studio.navbar_links` puts app links in the engine navbar.** An Array, or a
+  callable receiving the view, of `{ label:, href:, active:, badge: }` renders in
+  the desktop bar and the phone row, with `aria-current` on the active link and
+  an optional badge such as `"#12"`. An app that registers nothing renders the
+  same navbar bytes as before. See the README, *Navigation*.
+
 ## 0.77.4 — 2026-09-28
 
 ### Fixed

data/README.md

@@ -583,6 +583,34 @@ undefined, so mount `studio/modals/host` before writing a trigger.
 Full contract, including what the partial may assume: the doc comment at the top
 of `app/views/style/_host.html.erb`.
 
+### Navigation — `Studio.sidebar_sections` and `Studio.navbar_links`
+
+Two seams, both empty by default, so the navbar is unchanged until an app opts in.
+
+- `sidebar_sections` fills the slide-out link sidebar (the cog trigger in the icon
+  rail). Rules: `lib/studio/sidebar_sections.rb`.
+- `navbar_links` fills the navbar's own link slots: the desktop bar beside the
+  logo and the phone row under it. Rules: `lib/studio/navbar_links.rb`.
+
+```ruby
+Studio.configure do |config|
+  # An Array, or a callable receiving the view (so a badge can read current_user).
+  config.navbar_links = ->(view) {
+    [ { label: "Contests", href: view.contests_path, active: %r{\A/contests} },
+      { label: "Rank", href: "/rank",
+        badge: (view.logged_in? ? "##{view.current_user.rank}" : nil) } ]
+  }
+end
+```
+
+- `label:` and `href:` are required; both are escaped.
+- `active:` is `true`/`false`, a Regexp, or a callable taking `request.path`.
+  Omitted, a link is active when the path equals its href's path. The active
+  link gets `aria-current="page"` and the primary tone.
+- `badge:` is optional short text, such as `"#12"`, shown as a pill in the link.
+- A bad entry raises `Studio::NavbarLinks::InvalidLink` naming its index: at
+  assignment for a static Array, at render for a callable.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

data/app/assets/tailwind/studio_engine/engine.css

@@ -230,9 +230,12 @@ body.modal-open .studio-app-banner {
    @utility with unlayered overrides. Defaults resolve to the same white as
    before (a literal #fff — the engine's both-modes guard bars raw
    --color-white references, which only exist in Tailwind's compiled theme). */
+/* The fill is --color-cta-fill when the resolver emits one — only while the
+   app leaves its primary at the engine default, whose own hex is 3.1:1 under
+   white — and otherwise the app's --color-cta, as it always was. */
 @utility btn-primary {
   color: var(--btn-primary-fg, #fff);
-  background-color: var(--color-cta);
+  background-color: var(--color-cta-fill, var(--color-cta));
   &:hover {
     color: var(--btn-primary-fg-hover, var(--btn-primary-fg, #fff));
     background-color: var(--color-cta-hover);
@@ -258,7 +261,7 @@ body.modal-open .studio-app-banner {
   border-color: var(--color-cta);
   &:hover {
     @apply text-white;
-    background-color: var(--color-cta);
+    background-color: var(--color-cta-fill, var(--color-cta));
   }
 }
 

data/app/helpers/studio_navbar_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The navbar-links view seam. Links resolve once per render pass, since the
+# host lambda may read current_user or the database.
+module StudioNavbarHelper
+  NAVBAR_LINK_CLASS = "inline-flex items-center gap-1.5 whitespace-nowrap font-medium transition"
+  NAVBAR_BADGE_CLASS = "rounded-full border border-subtle px-1.5 py-0.5 text-[10px] leading-none " \
+                       "font-semibold text-muted tabular-nums"
+
+  def studio_navbar_links
+    @studio_navbar_links ||= Studio.navbar_links_for(self)
+  end
+
+  # One resolved link. size is the text utility: text-sm on desktop, text-xs
+  # in the phone row, matching the links apps hand-wrote in forked navbars.
+  def studio_navbar_link_tag(link, size:)
+    tone = link[:active] ? "text-primary" : "text-secondary hover:text-primary"
+    link_to link[:href], class: "#{NAVBAR_LINK_CLASS} #{size} #{tone}",
+                         aria: { current: ("page" if link[:active]) } do
+      badge = content_tag(:span, link[:badge], class: NAVBAR_BADGE_CLASS) if link[:badge]
+      safe_join([link[:label], badge].compact)
+    end
+  end
+end

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

@@ -40,7 +40,7 @@
      end
    end %>
 
-<%# Where the username and the avatar point — resolved ONCE, used by both.
+<%# Where the account link (the username and the avatar, one link) points.
 
     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
@@ -69,16 +69,14 @@
 
 <div class="flex gap-2">
   <% if logged_in? %>
-    <%# Left column: Div 1 + Div 2 stacked %>
-    <%# min-w-0 belongs HERE, on the flex item of the outer row. A flex item
-        defaults to min-width auto, so without it this column refuses to
-        shrink below its content and the username overflows instead of
-        truncating. Div 1 below is a block child of this column, not a flex
-        item of the outer row, so min-w-0 there has no effect on shrinking.
-        The username link truncates on its own: overflow-hidden gives it an
-        automatic minimum size of zero inside Div 1. %>
+    <%# Left column: Div 1 + Div 2 stacked.
+        min-w-0 belongs HERE, on the flex item of the nav root: a flex item
+        defaults to min-width auto, and without it this column refuses to
+        shrink below balance + icons. On a 320px phone with a balance the
+        reserved column is 147px, and a column that will not give pushed the
+        avatar 17px past the screen edge (e2e/header_phone_width.spec.js). %>
     <div class="flex-1 min-w-0">
-      <%# Div 1 (Bigger): balance + icons + username. %>
+      <%# Div 1 (Bigger): balance + icons. %>
       <div class="flex items-center gap-2 leading-none" :style="'padding: 0 6px;' + ($store.devMode ? 'background: cornflowerblue;' : '')">
         <%= studio_nav_slot.call(balance_slot, balance_html) %>
         <div class="flex items-center gap-2 ml-auto self-end">
@@ -86,14 +84,11 @@
           <%# Skipped when the link sidebar carries the admin menu — two cog
               glyphs side by side read as a double gear. %>
           <%= render "components/admin_dropdown" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
-          <%= render "components/theme_toggle_morph" %>
+          <%# Desktop only. Below md the engine navbar's phone row draws the
+              theme toggle, so a second one here put two on every phone. The
+              signed-out bar has always done it this way (layouts/_navbar). %>
+          <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
         </div>
-        <% 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) %>
       <% server_level = current_user.respond_to?(:level) && current_user.level.present? ? current_user.level : nil %>
@@ -154,7 +149,7 @@
              @navbar-seeds-update.window="handleSeedsUpdate($event.detail)"
              class="relative mt-0.5" style="height: 14px;">
           <%# Fill bar %>
-          <div class="absolute inset-y-0 left-0 rounded z-0" style="background: var(--color-cta); transition: width 1.2s cubic-bezier(0.16, 1, 0.3, 1);" :style="{ width: barWidth + '%' }"></div>
+          <div class="absolute inset-y-0 left-0 rounded z-0" style="background: var(--color-cta-fill, var(--color-cta)); transition: width 1.2s cubic-bezier(0.16, 1, 0.3, 1);" :style="{ width: barWidth + '%' }"></div>
           <%# Text layer 1: muted (visible outside bar) %>
           <div class="absolute inset-0 flex items-center justify-between px-1.5 font-mono text-muted z-[1] nav-bar-text">
             <span>
@@ -196,19 +191,33 @@
         </style>
       <% end %>
     </div>
-    <%# Div 3 (Avatar): spans both rows %>
-    <% 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'">
+    <%# Div 3 (Account): the name and the avatar are ONE link to the account
+        page, one tab stop — they used to be two links to the same place.
+        Below md the name is screen-reader text and the avatar stands alone,
+        so a phone never shows the name truncated to "Guest 55…"; from md up
+        it shows beside the avatar and truncates when the row is tight.
+
+        The link never shrinks (the avatar must stay on screen); the icon
+        column beside it is what gives way. So the name cannot truncate by
+        flex shrinking: from md up its box carries a max width instead, and
+        the name ellipsizes inside it. The avatar is aria-hidden: the name is
+        the link's accessible name. %>
+    <% account_classes = "group flex items-center gap-2 flex-shrink-0" %>
+    <% account_inner = capture do %>
+      <span class="sr-only md:not-sr-only md:max-w-40"><span class="block truncate text-right text-heading font-semibold text-base leading-none transition<%= " group-hover:text-primary" if studio_nav_destination %>" data-nav-name><%= current_user.display_name %></span></span>
+      <span class="flex-shrink-0 flex items-center" aria-hidden="true">
         <%= render "components/avatar", user: current_user, size: "nav" %>
       </span>
     <% end %>
+    <% if studio_nav_destination %>
+      <%= link_to account_inner, studio_nav_destination, class: "#{account_classes} hover:opacity-80 transition", "data-nav-account": "", "x-bind:style": "$store.devMode && 'background: lightgreen'" %>
+    <% else %>
+      <span class="<%= account_classes %>" data-nav-account x-bind:style="$store.devMode && 'background: lightgreen'"><%= account_inner %></span>
+    <% end %>
   <% else %>
     <%= render "components/admin_dropdown" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
-    <%= render "components/theme_toggle_morph" %>
+    <%# Desktop only, as above: the phone row carries the toggle below md. %>
+    <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <div class="flex items-center gap-3 ml-auto">
       <%= link_to "Log in", login_path, class: "text-heading hover:text-primary text-sm font-semibold transition" %>
       <%= link_to "Sign up", signup_path, class: "btn btn-primary btn-sm" %>

data/app/views/layouts/_navbar.html.erb

@@ -26,6 +26,9 @@
     Preview renders skip it too: the /admin/navbar page renders this partial
     repeatedly and the panels carry page-unique ids. %>
 <% sidebar_active = !is_preview && respond_to?(:studio_sidebar?) && studio_sidebar? %>
+<%# Studio.navbar_links: links for the desktop bar and phone row.
+    Empty by default, which renders the same bytes as before. %>
+<% navbar_links = respond_to?(:studio_navbar_links) ? studio_navbar_links : [] %>
 <% if sidebar_active %>
   <% sidebar_trigger_desktop = capture { render "components/link_sidebar_trigger", class_name: "hidden md:inline-flex" } %>
   <% extra_icons_html = safe_join([extra_icons_html, sidebar_trigger_desktop].compact) %>
@@ -141,8 +144,11 @@
               spans drawing outside it, which is the bug rather than the fix. %>
           <h1 class="nav-title font-extrabold text-heading tracking-tight min-w-0"><span class="truncate"><%= prefix %></span><span class="text-primary truncate"><%= last_word %></span></h1>
         <% end %>
-        <%# Desktop nav — apps should override this partial to add links here %>
-        <nav class="hidden md:flex items-center gap-4">
+        <%# Desktop nav — Studio.navbar_links %>
+        <nav class="hidden md:flex items-center gap-4"<%= ' aria-label="Main"'.html_safe if navbar_links.any? %>>
+          <% navbar_links.each do |link| %>
+          <%= studio_navbar_link_tag(link, size: "text-sm") %>
+          <% end %>
         </nav>
       </div>
     </div>
@@ -161,8 +167,15 @@
       <% end %>
     </div>
   </div>
-  <%# Mobile sub-navbar: compact row hidden on desktop — apps should override to add links %>
+  <%# Mobile sub-navbar: compact row hidden on desktop — Studio.navbar_links on the left %>
   <div class="flex md:hidden items-center gap-3 px-4 py-1.5 border-t border-subtle bg-surface-alt">
+    <% if navbar_links.any? %>
+    <nav aria-label="Main" class="flex items-center gap-3 overflow-x-auto">
+      <% navbar_links.each do |link| %>
+      <%= studio_navbar_link_tag(link, size: "text-xs") %>
+      <% end %>
+    </nav>
+    <% end %>
     <span class="ml-auto flex items-center gap-3">
       <%= render "components/link_sidebar_trigger" if sidebar_active %>
       <%= render "components/admin_dropdown" unless sidebar_active && studio_sidebar_replaces_admin_menu? %>

data/app/views/layouts/studio/_flash.html.erb

@@ -121,7 +121,7 @@
         </template>
         <template x-if="!toast.image">
           <div class="w-10 h-10 rounded-full flex items-center justify-center bg-inset shrink-0" style="margin-top: 2px;">
-            <svg x-show="toast.type === 'notice'" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" style="color: var(--color-success)" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+            <svg x-show="toast.type === 'notice'" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" style="color: var(--color-success-ink)" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
               <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z" />
             </svg>
             <svg x-show="toast.type !== 'notice'" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" style="color: var(--color-danger)" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">

data/app/views/studio/board/_board.html.erb

@@ -226,7 +226,7 @@
              x-transition:leave-end="opacity-0 translate-x-8"
              class="bg-surface border rounded-lg px-4 py-2.5 text-sm font-medium shadow-lg backdrop-blur-sm"
              :style="toast.type === 'success'
-                       ? 'border-color: var(--color-success); color: var(--color-success)'
+                       ? 'border-color: var(--color-success); color: var(--color-success-ink)'
                        : 'border-color: var(--color-danger); color: var(--color-danger)'">
           <span x-text="toast.message"></span>
         </div>

data/app/views/studio/modals/shared/_email_field.html.erb

@@ -58,7 +58,7 @@
     <div class="absolute right-3 top-1/2 -translate-y-1/2 pointer-events-none">
       <span x-show="status === 'loading'" x-cloak class="spinner text-secondary" aria-hidden="true"></span>
       <svg x-show="status === 'valid'" x-cloak xmlns="http://www.w3.org/2000/svg" class="w-5 h-5"
-           style="color: var(--color-success)" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true">
+           style="color: var(--color-success-ink)" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true">
         <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z" />
       </svg>
       <svg x-show="status === 'invalid'" x-cloak xmlns="http://www.w3.org/2000/svg" class="w-5 h-5"

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

@@ -95,7 +95,7 @@
         <svg x-show="!copiedRef" class="w-3 h-3 shrink-0" fill="none" stroke="currentColor" stroke-width="1.8" viewBox="0 0 24 24" aria-hidden="true">
           <path stroke-linecap="round" stroke-linejoin="round" d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2"/>
         </svg>
-        <svg x-show="copiedRef" x-cloak class="w-3 h-3 shrink-0" style="color: var(--color-success)" fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24" aria-hidden="true">
+        <svg x-show="copiedRef" x-cloak class="w-3 h-3 shrink-0" style="color: var(--color-success-ink)" fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24" aria-hidden="true">
           <path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/>
         </svg>
         <span class="sr-only" x-text="copiedRef ? 'Copied' : ''"></span>

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

@@ -868,7 +868,7 @@
       <div class="flex flex-wrap items-center gap-3">
         <h3 class="text-xl font-bold text-heading">Profile Leveling</h3>
         <% if leveling_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">leveling on</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">leveling on</span>
         <% else %>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">leveling off</span>
         <% end %>
@@ -958,7 +958,7 @@
             glow_when: ds_glow.call("join-newsletter", celebrate: 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="mx-auto w-7 h-7 rounded-full flex items-center justify-center" style="background: color-mix(in srgb, var(--color-success) 15%, transparent)">
-            <svg class="w-4 h-4" style="color: var(--color-success)" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/></svg>
+            <svg class="w-4 h-4" style="color: var(--color-success-ink)" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/></svg>
           </div>
           <div x-show="opts.leveling" class="flex gap-1">
             <span class="flex-1 h-2 rounded" style="background: var(--color-cta)"></span>
@@ -1022,7 +1022,7 @@
       <div class="flex flex-wrap items-center gap-3">
         <h3 class="text-xl font-bold text-heading">Web3</h3>
         <% if web3_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">enabled on this app</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">enabled on this app</span>
         <% else %>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">disabled on this app</span>
         <% end %>
@@ -1192,7 +1192,7 @@
       <div class="flex flex-wrap items-center gap-3">
         <h3 class="text-xl font-bold text-heading">Contest entry &amp; eligibility</h3>
         <% if age_gate_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">age gate on</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">age gate on</span>
         <% else %>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">age gate off</span>
         <% end %>
@@ -1312,7 +1312,7 @@
             open_expr: "$store.dsModals.open('ds-success')" } 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="mx-auto w-7 h-7 rounded-full flex items-center justify-center" style="background: color-mix(in srgb, var(--color-success) 15%, transparent)">
-            <svg class="w-4 h-4" style="color: var(--color-success)" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/></svg>
+            <svg class="w-4 h-4" style="color: var(--color-success-ink)" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/></svg>
           </div>
           <span class="block h-2 w-24 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
           <span class="block h-4 w-full rounded" style="background: var(--color-cta)"></span>
@@ -1441,7 +1441,7 @@
       <div class="flex flex-wrap items-center gap-3">
         <h3 class="text-xl font-bold text-heading">Rewards</h3>
         <% if leveling_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">enabled on this app</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">enabled on this app</span>
         <% else %>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">disabled on this app</span>
         <% end %>

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

@@ -85,7 +85,7 @@
   <%= render "studio/board_assets" %>
   <div class="space-y-3">
     <div class="flex items-center gap-2">
-      <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">Live</span>
+      <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">Live</span>
       <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; demo &mdash; drag a card between columns</p>
     </div>
     <%= render "studio/board/board",
@@ -268,7 +268,7 @@
   <div class="grid gap-4 sm:grid-cols-2">
     <div class="card p-5 space-y-2">
       <div class="flex items-center gap-2">
-        <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">Shared</span>
+        <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">Shared</span>
         <p class="text-heading font-semibold text-sm">What every board inherits</p>
       </div>
       <ul class="text-secondary text-sm space-y-1 list-disc list-inside">

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

@@ -183,12 +183,13 @@
     function dsThemeEditor(seed) {
       return {
         colors: Object.assign({ primary: '#000', dark: '#0f172a', light: '#ffffff',
-                                success: '#4BAF50', warning: '#FF7C47', danger: '#EF4444',
+                                success: '#367E3A', warning: '#FF7C47', danger: '#EF4444',
                                 accent: '#6366F1' }, seed || {}),
         saving: false,
         updatePreview() {
           var d = document.documentElement.style;
           d.setProperty('--color-cta', this.colors.primary);
+          d.setProperty('--color-cta-fill', this.colors.primary);
           if (this.colors.success) d.setProperty('--color-success', this.colors.success);
           if (this.colors.warning) d.setProperty('--color-warning', this.colors.warning);
           if (this.colors.danger)  d.setProperty('--color-danger', this.colors.danger);

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

@@ -90,7 +90,7 @@
             locals: { klass: ".badge", usage: %(<span class="badge">Neutral</span>) } do %>
         <div class="flex flex-wrap items-center justify-center gap-2">
           <span class="badge text-body">Neutral</span>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">Success</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">Success</span>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">Warning</span>
           <span class="badge" style="color: var(--color-danger); border-color: var(--color-danger)">Danger</span>
         </div>
@@ -174,7 +174,7 @@
       <%= render layout: "style/specimen",
             locals: { klass: "in a status badge",
                       usage: %(<span class="badge">Shipped ) + erb.call("at_time_tag(release.shipped_at)") + "</span>" } do %>
-        <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">Shipped <%= at_time_tag(42.minutes.ago) %></span>
+        <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">Shipped <%= at_time_tag(42.minutes.ago) %></span>
       <% end %>
     </div>
   </section>
@@ -442,7 +442,7 @@
       <div class="flex flex-wrap items-center gap-3">
         <h3 class="text-xl font-bold text-heading">Leveling</h3>
         <% if leveling_on %>
-          <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">enabled on this app</span>
+          <span class="badge" style="color: var(--color-success-ink); border-color: var(--color-success)">enabled on this app</span>
         <% else %>
           <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">disabled on this app</span>
         <% end %>

data/app/views/theme_settings/edit.html.erb

@@ -71,13 +71,13 @@
               <p class="text-sm mb-3" :style="{ color: '#94a3b8' }">Card on surface with secondary text.</p>
               <div class="flex gap-2">
                 <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.primary }">Primary</button>
-                <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.success || '#4BAF50' }">Accent</button>
+                <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.success || '#367E3A' }">Accent</button>
                 <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.danger || '#EF4444' }">Danger</button>
               </div>
             </div>
             <div class="flex gap-2">
               <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: colors.primary + '33', color: colors.primary, border: '1px solid ' + colors.primary + '55' }">Badge</span>
-              <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: (colors.success || '#4BAF50') + '33', color: colors.success || '#4BAF50', border: '1px solid ' + (colors.success || '#4BAF50') + '55' }">Success</span>
+              <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: (colors.success || '#367E3A') + '33', color: colors.success || '#367E3A', border: '1px solid ' + (colors.success || '#367E3A') + '55' }">Success</span>
             </div>
           </div>
         </div>
@@ -94,13 +94,13 @@
               <p class="text-sm mb-3" :style="{ color: '#64748b' }">Card on surface with secondary text.</p>
               <div class="flex gap-2">
                 <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.primary }">Primary</button>
-                <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.success || '#4BAF50' }">Accent</button>
+                <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.success || '#367E3A' }">Accent</button>
                 <button class="btn btn-sm text-white rounded-lg px-3 py-1.5 text-xs font-bold" :style="{ backgroundColor: colors.danger || '#EF4444' }">Danger</button>
               </div>
             </div>
             <div class="flex gap-2">
               <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: colors.primary + '33', color: colors.primary, border: '1px solid ' + colors.primary + '55' }">Badge</span>
-              <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: (colors.success || '#4BAF50') + '33', color: colors.success || '#4BAF50', border: '1px solid ' + (colors.success || '#4BAF50') + '55' }">Success</span>
+              <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium" :style="{ backgroundColor: (colors.success || '#367E3A') + '33', color: colors.success || '#367E3A', border: '1px solid ' + (colors.success || '#367E3A') + '55' }">Success</span>
             </div>
           </div>
         </div>

data/lib/studio/navbar_links.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Resolves Studio.navbar_links, the links the engine navbar renders in its
+# desktop bar and phone row. Pure Ruby, so the unit suite covers it without
+# the dummy app.
+#
+# Declared as an Array or a callable (receives the view context, so a badge can
+# read current_user). Each entry resolves to:
+#
+#   { label: "Contests", href: "/contests", active: true, badge: "#12" }
+#
+# `active` may be true/false, a Regexp or a callable matched against
+# request.path; omitted, it is true when the path equals the href's path.
+# `badge` is optional short text. A bad entry raises InvalidLink by index.
+module Studio
+  module NavbarLinks
+    class InvalidLink < ArgumentError; end
+
+    KEYS = %i[label href active badge].freeze
+
+    module_function
+
+    def resolve(declared, view)
+      links = declared.respond_to?(:call) ? declared.call(view) : declared
+      path = request_path(view)
+      entries(links).each_with_index.map do |link, index|
+        link = check!(link, index)
+        { label: link[:label].to_s, href: link[:href].to_s,
+          active: active?(link, path), badge: badge(link[:badge]) }
+      end
+    end
+
+    # Shape check without a request: a static list fails at boot, not on the
+    # first page render. A callable is checked when it resolves.
+    def validate!(declared)
+      return nil if declared.respond_to?(:call)
+
+      entries(declared).each_with_index { |link, index| check!(link, index) }
+      nil
+    end
+
+    def entries(links)
+      return [] if links.nil?
+      return links if links.is_a?(Array)
+
+      raise InvalidLink, "Studio.navbar_links must be an Array or a callable returning an Array " \
+                         "(got #{links.class})"
+    end
+
+    def check!(link, index)
+      where = "Studio.navbar_links[#{index}]"
+      raise InvalidLink, "#{where} must be a Hash (got #{link.class})" unless link.is_a?(Hash)
+
+      link = link.to_h { |key, value| [key.to_sym, value] }
+      unknown = link.keys - KEYS
+      raise InvalidLink, "#{where} has unknown key :#{unknown.first}" if unknown.any?
+
+      %i[label href].each do |key|
+        raise InvalidLink, "#{where} needs a :#{key}" if link[key].to_s.strip.empty?
+      end
+      unless [nil, true, false].include?(link[:active]) || link[:active].is_a?(Regexp) ||
+             link[:active].respond_to?(:call)
+        raise InvalidLink, "#{where} :active must be true, false, a Regexp or a callable"
+      end
+      unless link[:badge].nil? || [String, Symbol, Numeric].any? { |type| link[:badge].is_a?(type) }
+        raise InvalidLink, "#{where} :badge must be short text"
+      end
+
+      link
+    end
+
+    def active?(link, path)
+      case (rule = link[:active])
+      when true, false then rule
+      when nil then !path.nil? && path == link[:href].to_s.split(/[?#]/).first
+      when Regexp then !path.nil? && rule.match?(path)
+      else !path.nil? && rule.call(path) ? true : false
+      end
+    end
+
+    def badge(value)
+      text = value.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    def request_path(view)
+      return nil unless view.respond_to?(:request)
+
+      view.request&.path
+    end
+  end
+end

data/lib/studio/theme_resolver.rb

@@ -2,6 +2,18 @@ module Studio
   class ThemeResolver
     ROLES = %i[primary dark light success warning danger accent].freeze
 
+    # The engine's default role colours — the resolver's fallbacks, and the
+    # same values lib/studio.rb ships as its theme_* defaults.
+    DEFAULT_PRIMARY = "#8E82FE"
+    # #367E3A, not the #4BAF50 it was until engine-navbar-phone-polish: the old
+    # green measured 2.78:1 under the white label btn-success draws on it. This
+    # is the same hue at 5.0:1 (the shade cyvasse chose for its own success).
+    DEFAULT_SUCCESS = "#367E3A"
+
+    # WCAG AA for normal-size text. Every filled button draws a 14px bold white
+    # label, which is not "large" text, so its fill owes 4.5:1 against white.
+    WHITE_LABEL_TARGET = 4.5
+
     attr_reader :colors
 
     # colors: hash of role => hex string (e.g. { primary: "#8E82FE", dark: "#1A1535", ... })
@@ -29,9 +41,9 @@ module Studio
 
     def dark_mode_vars
       dark_base   = colors[:dark] || "#1A1535"
-      primary     = colors[:primary] || "#8E82FE"
+      primary     = colors[:primary] || DEFAULT_PRIMARY
       border_rgb  = ColorScale.lighten(dark_base, 0.30)
-      success     = colors[:success] || "#4BAF50"
+      success     = colors[:success] || DEFAULT_SUCCESS
       warning     = colors[:warning] || "#FF7C47"
       danger      = colors[:danger] || "#EF4444"
       surfaces    = dark_surfaces(dark_base)
@@ -69,8 +81,11 @@ module Studio
         "--color-border"         => ColorScale.with_opacity(border_rgb, 0.2),
         "--color-border-strong"  => ColorScale.with_opacity(border_rgb, 0.4),
         "--color-shadow"         => "transparent",
+        # --color-cta stays the brand colour: apps also paint it as TEXT on
+        # dark surfaces, where a darker shade would lose contrast. The button
+        # fill under a white label is a separate, derived var: see #fill_vars.
         "--color-cta"            => primary,
-        "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
+        "--color-cta-hover"      => cta_hover(primary),
         "--color-success"        => success,
         "--color-warning"        => warning,
         "--color-danger"         => danger,
@@ -99,7 +114,7 @@ module Studio
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :lighten),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :lighten),
         "--color-accent"         => colors[:accent] || "#F72585"
-      }
+      }.merge(fill_vars(primary, success))
     end
 
     # Every dark-mode background a text var can sit on (page, surface,
@@ -166,6 +181,38 @@ module Studio
       contrast_ink(role, direction: direction, start: 0.0, target: 4.5, against: surfaces + tints)
     end
 
+    # The lightest shade of `color` that carries a white label at AA: the
+    # colour itself when it already passes, otherwise the same hue darkened in
+    # 0.02 steps until it does. A fill shade, derived the way the text inks are.
+    def white_label_fill(color)
+      contrast_ink(color, direction: :darken, start: 0.0, target: WHITE_LABEL_TARGET, against: ["#ffffff"])
+    end
+
+    # --color-cta-fill: the fill btn-primary, btn-outline's hover and the user
+    # nav's level bar paint under a white label (the same in both modes).
+    # Emitted ONLY while the app leaves its primary at the engine default
+    # (#8E82FE, 3.1:1 under white), which is the engine's to make accessible.
+    # A CONFIGURED primary emits no fill, so those rules fall back to
+    # var(--color-cta), the app's own choice: mcritchie-industries pairs a navy
+    # label with its orange (a darkened fill would drop it to 3.3:1), and
+    # cyvasse sets --color-cta itself.
+    #
+    # Success needs no fill var: its DEFAULT is already AA under white
+    # (DEFAULT_SUCCESS), and a configured success colour is the app's own —
+    # turf-monster's suite pins that a configured #4BAF50 still paints as-is.
+    def fill_vars(primary, _success)
+      return {} unless primary.to_s.casecmp?(DEFAULT_PRIMARY)
+
+      { "--color-cta-fill" => white_label_fill(primary) }
+    end
+
+    # The hover fill is always derived, so it is always held to AA under white:
+    # darken(primary, 0.30) as before when that passes (every consumer palette
+    # today), darker only for a primary so light that 0.30 is not enough.
+    def cta_hover(primary)
+      contrast_ink(primary, direction: :darken, start: 0.30, target: WHITE_LABEL_TARGET, against: ["#ffffff"])
+    end
+
     # Bounded, clamped search: raise the blend amount from `start` until the
     # ink clears `target` contrast against every background in `against`.
     # Clamps at 1.0 (pure white/black), so a pathological base degrades to the
@@ -182,7 +229,7 @@ module Studio
 
     # Generate --color-primary-{50..900} + RGB variants for Tailwind opacity support
     def primary_palette_vars
-      primary = colors[:primary] || "#8E82FE"
+      primary = colors[:primary] || DEFAULT_PRIMARY
       scale = ColorScale.generate(primary)
       vars = {}
 
@@ -202,8 +249,8 @@ module Studio
 
     def light_mode_vars
       light_base = colors[:light] || "#f8fafc"
-      primary    = colors[:primary] || "#8E82FE"
-      success    = colors[:success] || "#4BAF50"
+      primary    = colors[:primary] || DEFAULT_PRIMARY
+      success    = colors[:success] || DEFAULT_SUCCESS
       warning    = colors[:warning] || "#FF7C47"
       danger     = colors[:danger] || "#EF4444"
       surfaces   = light_surfaces(light_base)
@@ -231,7 +278,7 @@ module Studio
         "--color-border-strong"  => ColorScale.darken(light_base, 0.15),
         "--color-shadow"         => "rgba(0,0,0,0.05)",
         "--color-cta"            => primary,
-        "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
+        "--color-cta-hover"      => cta_hover(primary),
         "--color-success"        => success,
         "--color-warning"        => warning,
         "--color-danger"         => danger,
@@ -256,7 +303,7 @@ module Studio
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :darken),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :darken),
         "--color-accent"         => colors[:accent] || "#F72585"
-      }
+      }.merge(fill_vars(primary, success))
     end
   end
 end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.77.4"
+  VERSION = "0.79.0"
 end

data/lib/studio.rb

@@ -12,6 +12,7 @@ require "studio/js_literal"
 require "studio/js_identifier"
 require "studio/partial_block"
 require "studio/sidebar_sections"
+require "studio/navbar_links"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
@@ -174,6 +175,23 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
+  # ---- Navbar links ----
+  # Links for the engine navbar's desktop bar and phone row. The default []
+  # renders nothing, so the navbar stays byte-identical until an app opts in.
+  # An Array, or a callable receiving the view, of
+  # { label:, href:, active: (bool, Regexp or ->(path)), badge: (optional) }.
+  # Rules: lib/studio/navbar_links.rb.
+  #
+  #   config.navbar_links = ->(view) {
+  #     [ { label: "Contests", href: view.contests_path, active: %r{\A/contests} },
+  #       { label: "Rank", href: "/rank", badge: ("#12" if view.logged_in?) } ] }
+  mattr_reader :navbar_links, default: []
+
+  def self.navbar_links=(links)
+    NavbarLinks.validate!(links)
+    @@navbar_links = links
+  end
+
   # ---- The shared profile page (/profile) ----
   # The rows that make up /profile. `nil` — the default — means "the engine's
   # standard page", NOT "no rows": a brand-new app with an empty initializer gets
@@ -589,7 +607,9 @@ module Studio
   mattr_accessor :theme_primary,  default: "#8E82FE"
   mattr_accessor :theme_dark,     default: "#1A1535"
   mattr_accessor :theme_light,    default: "#f8fafc"
-  mattr_accessor :theme_success,  default: "#4BAF50"
+  # #367E3A: the default green's AA shade under a white label (5.0:1). The old
+  # #4BAF50 measured 2.78:1 on btn-success. Studio::ThemeResolver::DEFAULT_SUCCESS.
+  mattr_accessor :theme_success,  default: "#367E3A"
   mattr_accessor :theme_warning,  default: "#FF7C47"
   mattr_accessor :theme_danger,   default: "#EF4444"
   mattr_accessor :theme_accent,   default: "#F72585"
@@ -877,6 +897,11 @@ module Studio
     SidebarSections.resolve(sidebar_sections, view)
   end
 
+  # Navbar links resolved for a view context (lib/studio/navbar_links.rb).
+  def self.navbar_links_for(view)
+    NavbarLinks.resolve(navbar_links, view)
+  end
+
   # The engine's standard /profile rows. Hosts compose against this rather than
   # restating a literal list, so a later release that adds a standard row
   # delivers it to every app that used the seam as intended.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.77.4
+  version: 0.79.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -345,6 +345,7 @@ files:
 - app/helpers/studio/fizz_helper.rb
 - app/helpers/studio/geo_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
+- app/helpers/studio_navbar_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
@@ -572,6 +573,7 @@ files:
 - lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb
+- lib/studio/navbar_links.rb
 - lib/studio/newsletter.rb
 - lib/studio/oauth_identity.rb
 - lib/studio/partial_block.rb