studio-engine 0.77.3 → 0.78.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cc769a784287a588fc4d2c8301ffd284d11bba8dd66e849ccf684a9ab8360b1
-  data.tar.gz: 633a853e6754e83e08689d2aaadb376359b83f3a33f3a70479d36350d53d4094
+  metadata.gz: 12e1056052d4d49cd70e0ca81e8a39fc4f1c370166d73ea319315337fc648f5f
+  data.tar.gz: 0d94f90bff68c27a6c86d07ad53904b330a3717121f5f944244d0153a2e53a63
 SHA512:
-  metadata.gz: 33b9ede51a13dd085c889dc60eff98c7bf1b8c8823e8c35793b486137c803f8e32d73d931c5a3baa0cbbb971fd6023f0d623fc070473df6b8f6272878a79326b
-  data.tar.gz: ae87c5d5959476e748e5a957937d6568667f0b8831281eeef6b5ef46570b6e8e3b4ef8a7d296dea624af6bda3c1c3a2eb1d09893e2078f0bf013ba62d5625124
+  metadata.gz: cb929bb288de471829b57f90cfbf01fff7d4e51d68607da51b32df832ad4946662a0617a85002ec6244c23fb3d3d17db069528b090690378ba68a7f53669141a
+  data.tar.gz: bb9eb9c389d8d89887ba72b0bff91b080944b501c3564aed06b26b317f013445f6fd9636d327ba20e70cfd7e4d3065928b6d091eed8c22160e6b819de69825ba

data/CHANGELOG.md

@@ -4,6 +4,35 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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
+
+- **An email banner stored on R2 with no public URL no longer breaks sign-in.**
+  With `Studio::S3` on an S3-compatible endpoint (Cloudflare R2) and no
+  `s3_public_url`, a banner upload on `/admin/emails` used to succeed, after which
+  `ImageCache#url` raised `NotConfigured` on every read: the magic-link sign-in
+  email, the newsletter and profile emails, and the orphan page all failed.
+  - `Studio::EmailCatalog.uploads_available?` is now false in that state, and the
+    new `uploads_blocked_reason` (`:no_storage` or `:no_public_url`) lets the page
+    name the setting that fixes it: `s3_public_url`, not `s3_bucket_prefix`.
+  - `EmailCatalog.url` degrades to `nil` when a stored image cannot be served, so
+    `resolved_url` and every host's `url(...) || its_own_asset` fall back to the
+    default banner. Other errors still raise, and `ImageCache#url` stays loud
+    everywhere else.
+  - The orphan page previews through the same safe read.
+  Apps on AWS, or on R2 with `s3_public_url` set, behave exactly as before.
+
 ## 0.77.3 — 2026-09-28
 
 ## 0.77.2 — 2026-09-28

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/controllers/studio/emails_controller.rb

@@ -23,6 +23,7 @@ module Studio
     def index
       @entries = Studio::EmailCatalog.entries
       @uploads_available = Studio::EmailCatalog.uploads_available?
+      @uploads_blocked_reason = Studio::EmailCatalog.uploads_blocked_reason
 
       # The list renders every banner and subject AS THEY WOULD ARRIVE, which has
       # no answer until someone is receiving them.
@@ -44,6 +45,7 @@ module Studio
       @subject = Studio::EmailCatalog.preview_subject(@key)
       @preview_error = Studio::EmailCatalog.preview_error(@key)
       @uploads_available = Studio::EmailCatalog.uploads_available?
+      @uploads_blocked_reason = Studio::EmailCatalog.uploads_blocked_reason
 
       # WHO this is previewed as. The banner greets by name, so "what does this
       # email look like" has no answer until someone is receiving it — and the
@@ -241,8 +243,12 @@ module Studio
     def require_uploads
       return if Studio::EmailCatalog.uploads_available?
 
-      redirect_to admin_emails_path, status: :see_other,
-                  alert: "This app has no object storage configured, so email images can't be changed here yet."
+      alert = if Studio::EmailCatalog.uploads_blocked_reason == :no_public_url
+                "This app's storage has no public URL yet, so email images can't be changed here."
+              else
+                "This app has no object storage configured, so email images can't be changed here yet."
+              end
+      redirect_to admin_emails_path, status: :see_other, alert: alert
     end
 
     # Shown INSIDE the preview iframe when the builder is missing or raised.

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/services/studio/email_catalog.rb

@@ -712,6 +712,13 @@ module Studio
     # caller keeps the behavior it was written against until its app adopts.
     def url(key)
       record(key)&.url
+    rescue Studio::S3::NotConfigured => e
+      # A stored override this app can no longer serve publicly (Studio::S3 on
+      # an S3-compatible endpoint with no s3_public_url). Every caller already
+      # treats nil as "use the default", so degrade to that instead of raising
+      # out of a mailer: this method feeds the magic-link sign-in email.
+      warn_unservable(key, e)
+      nil
     end
 
     # What ACTUALLY SHIPS on this email — the two-layer resolution. Absolute, so
@@ -845,13 +852,31 @@ module Studio
       host ? "#{host}#{path}" : path
     end
 
+    def warn_unservable(key, error)
+      message = "[email_catalog] #{key}: stored image not publicly servable, using default (#{error.message})"
+      defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger ? Rails.logger.warn(message) : warn(message)
+    end
+
     # --- Upload ------------------------------------------------------------
 
     # Whether THIS app can accept an upload. False when the host never set
     # Studio.s3_bucket_prefix — /admin/emails then shows inherited defaults
     # read-only rather than 500ing on the first upload.
     def uploads_available?
-      Studio::S3.configured? && table_ready?
+      uploads_blocked_reason.nil?
+    end
+
+    # Why uploads are off, or nil when they are on:
+    #   :no_storage     the host never set Studio.s3_bucket_prefix (or the table
+    #                   is not migrated yet)
+    #   :no_public_url  storage is an S3-compatible endpoint (Cloudflare R2) with
+    #                   no Studio.s3_public_url, so an uploaded image could be
+    #                   stored but never served to an inbox
+    def uploads_blocked_reason
+      return :no_storage unless Studio::S3.configured? && table_ready?
+      return :no_public_url unless Studio::S3.public_url?
+
+      nil
     end
 
     # Upload bytes to this app's bucket + upsert its ImageCache row (replacing

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/studio/emails/index.html.erb

@@ -76,14 +76,25 @@
   <% unless @uploads_available %>
     <div class="mb-6 rounded-xl border border-subtle bg-inset px-4 py-3">
       <p class="text-sm font-semibold text-heading">Read-only on this app</p>
-      <p class="text-sm text-body mt-1">
-        <%= Studio.app_name %> has no object storage configured, so the images below
-        can be viewed but not replaced yet. They are the shared defaults that ship
-        with the engine, and they are what this app is sending right now. Set
-        <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config.s3_bucket_prefix</code>
-        in <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config/initializers/studio.rb</code>
-        to turn on uploads.
-      </p>
+      <% if @uploads_blocked_reason == :no_public_url %>
+        <p class="text-sm text-body mt-1">
+          <%= Studio.app_name %> stores files where they cannot be served to an inbox yet,
+          so the images below can be viewed but not replaced. They are what this app is
+          sending right now. Set
+          <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config.s3_public_url</code>
+          in <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config/initializers/studio.rb</code>
+          to turn on uploads.
+        </p>
+      <% else %>
+        <p class="text-sm text-body mt-1">
+          <%= Studio.app_name %> has no object storage configured, so the images below
+          can be viewed but not replaced yet. They are the shared defaults that ship
+          with the engine, and they are what this app is sending right now. Set
+          <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config.s3_bucket_prefix</code>
+          in <code class="font-mono text-2xs bg-surface px-1.5 py-0.5 rounded">config/initializers/studio.rb</code>
+          to turn on uploads.
+        </p>
+      <% end %>
     </div>
   <% end %>
 

data/app/views/studio/emails/orphan.html.erb

@@ -28,9 +28,13 @@
     </p>
 
     <% if (record = Studio::EmailCatalog.record(@key)) %>
-      <div class="rounded-lg overflow-hidden border border-subtle w-56 mt-4">
-        <%= image_tag record.url, class: "w-full h-auto", alt: "Stored artwork for #{@key}" %>
-      </div>
+      <%# EmailCatalog.url, not record.url: it degrades to nil when the stored image
+          cannot be served publicly (R2 with no s3_public_url) instead of 500ing. %>
+      <% if (preview = Studio::EmailCatalog.url(@key)) %>
+        <div class="rounded-lg overflow-hidden border border-subtle w-56 mt-4">
+          <%= image_tag preview, class: "w-full h-auto", alt: "Stored artwork for #{@key}" %>
+        </div>
+      <% end %>
       <p class="font-mono text-2xs text-muted mt-2 break-all"><%= record.s3_key %></p>
     <% end %>
 

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/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.77.3"
+  VERSION = "0.78.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
@@ -877,6 +895,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.3
+  version: 0.78.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-09-29 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