studio-engine 0.113.0 → 0.114.0

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

@@ -345,6 +345,37 @@
           </div>
         </template>
 
+        <%# The blocks' consumer locals (engine-modal-blocks-carry-consumer): the
+            error card's Retry-After countdown and close, the success card's
+            message slot and close, and the username card's locked state. Each
+            closes THIS store, never the host's. %>
+        <template x-if="$store.dsModals.current().id === 'ds-error-countdown'">
+          <div><%= render "studio/modals/blocks/error_card",
+                    title: "Easy there", icon_emoji: "✋",
+                    message: "You are going a bit fast.",
+                    countdown_key: "$store.dsModals.current().props.secondsLeft",
+                    modal_store: "dsModals",
+                    secondary_label: "Dismiss", secondary_close: true %></div>
+        </template>
+        <template x-if="$store.dsModals.current().id === 'ds-success-close'">
+          <div><%= render layout: "studio/modals/blocks/success_card",
+                    locals: { title: "Confirm your email change", icon_emoji: "📬",
+                              slot_position: :message, modal_store: "dsModals",
+                              cta_label: "Got it", cta_close: true } do %>
+            We sent a confirmation link to <span class="text-heading font-medium">pat@example.com</span>
+            (your current address). Click it to change your email to
+            <span class="text-heading font-medium">pat@newmail.com</span>.
+          <% end %></div>
+        </template>
+        <template x-if="$store.dsModals.current().id === 'ds-username-locked'">
+          <div><%= render "studio/modals/blocks/change_username",
+                    current_username: "turfmonster", submit_url: "#demo-change-username",
+                    modal_store: "dsModals",
+                    locked: { title: "Enter Contest First",
+                              subtitle: "Your username is locked until you've played one contest.",
+                              cta_label: "Browse Contests", cta_href: "#modals" } %></div>
+        </template>
+
         <%# --- Templates (copy-from archetypes) --- %>
         <template x-if="$store.dsModals.current().id === 'template-wizard'">
           <div><%= render "studio/modals/templates/wizard", modal_store: "dsModals" %></div>
@@ -1157,6 +1188,40 @@
         </div>
       <% end %>
 
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Error countdown",
+            reference: %(the "Error" card block with its countdown (studio/modals/blocks/_error_card with countdown_key:) — the wait is read once from the expression the host names, a 429's Retry-After, counts down by studio/modal_countdown, reads in minutes above 90 seconds, and closes the store at zero; secondary_close: makes Dismiss close it by hand. Open with $store.dsModals.open('ds-error-countdown', { secondsLeft: 10 })),
+            open_expr: "$store.dsModals.open('ds-error-countdown', { secondsLeft: 10 })" } 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-20 mx-auto rounded" style="background: var(--color-text); opacity: .18"></span>
+          <span class="block h-1.5 w-16 mx-auto rounded" style="background: var(--color-text); opacity: .3"></span>
+        </div>
+      <% end %>
+
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Success, closes",
+            reference: %(the "Success" card block with its message slot and a closing CTA (studio/modals/blocks/_success_card with slot_position: :message and cta_close:) — the caller's block takes the message's place, for copy richer than one string, and the CTA closes the store rather than following a link. Open with $store.dsModals.open('ds-success-close')),
+            open_expr: "$store.dsModals.open('ds-success-close')" } 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-1.5 w-28 mx-auto rounded" style="background: var(--color-text); opacity: .12"></span>
+          <span class="block h-4 w-full rounded" style="background: var(--color-cta)"></span>
+        </div>
+      <% end %>
+
+      <%= render layout: "style/modal_specimen", locals: {
+            label:     "Username locked",
+            reference: %(the change-username block's locked state (studio/modals/blocks/_change_username with locked:) — the app decides the rename is not open yet and the card says why, with a link to where it unlocks and a Dismiss, in place of the input. Open with $store.dsModals.open('ds-username-locked')),
+            open_expr: "$store.dsModals.open('ds-username-locked')" } 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" style="background: color-mix(in srgb, var(--color-danger) 15%, transparent)"></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>
+        </div>
+      <% end %>
+
       <%# rate-limit-general — the SOFT cap. Dismissible, apologetic, and it
           auto-closes when the wait elapses rather than making anyone
           acknowledge a penalty for clicking too fast. %>

data/lib/studio/navbar_account_sidebar.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Resolves Studio.navbar_account_sidebar: the host sidebar the signed-in user
+# nav's account control (the name and the avatar, one control) opens, in place
+# of linking to the account page or opening the engine's link sidebar. Pure
+# Ruby, so the unit suite covers it without the dummy app.
+#
+# Studio.navbar_account_sidebar is one of:
+#
+#   nil                     the default: the account control links to the
+#                           account page or opens the link sidebar, as before
+#   { flag: "gearOpen",     the control is a button that toggles
+#     store: "sidebars",    $store.<store>.<flag> (store defaults to "sidebars")
+#     controls: "gear-sidebar gear-sidebar-mobile" }
+#                           and names the panels it opens in aria-controls
+#                           (a String of ids or an Array of them)
+#   ->(view) { ... }        a callable receiving the view; nil keeps the default
+#
+# The toggle expression is the engine's, built from these names, which must be
+# plain JavaScript identifiers; no host JavaScript reaches the page as a string.
+# :controls may not name the engine's own link sidebar (studio-link-sidebar,
+# studio-link-sidebar-mobile): studio/link_sidebar would claim the click.
+# The button also carries data-profile-image-toggle, so a host's capture-phase
+# handler that claims its sidebar's triggers before Alpine binds (as
+# studio/link_sidebar does for the link sidebar) claims this one too.
+#
+# A bad static Hash raises InvalidConfig at assignment; a callable's answer is
+# checked when it resolves. A callable that RAISES renders the default and is
+# reported once per process per error class, so a layout never 500s.
+module Studio
+  module NavbarAccountSidebar
+    class InvalidConfig < ArgumentError; end
+
+    SETTING = "Studio.navbar_account_sidebar"
+    KEYS = %i[flag store controls].freeze
+    IDENTIFIER = /\A[A-Za-z_$][\w$]*\z/
+    DOM_ID = /\A[A-Za-z][\w:.-]*\z/
+    # The engine's link sidebar panels: components/_link_sidebar renders them, and
+    # app/javascript/studio/link_sidebar.js (LINK_SIDEBAR_PANELS) is the source of
+    # truth; test/lib/navbar_account_sidebar_test.rb holds this list to it.
+    # studio/link_sidebar claims a click on any trigger whose aria-controls names
+    # them, so a host sidebar control that named one would open the engine's
+    # panel, not the host's.
+    ENGINE_LINK_SIDEBAR_IDS = %w[studio-link-sidebar studio-link-sidebar-mobile].freeze
+
+    @reported = {}
+    @reported_lock = Mutex.new
+
+    module_function
+
+    # The sidebar for one render, as { store:, flag:, controls: } with plain
+    # Strings, or nil for the default account control.
+    def resolve(config, view)
+      return nil if config.nil?
+      return normalize(config) unless config.respond_to?(:call)
+
+      begin
+        answer = config.call(view)
+      rescue StandardError => e
+        report_once(e)
+        return nil
+      end
+      answer.nil? ? nil : normalize(answer)
+    end
+
+    def validate!(config)
+      normalize(config) unless config.nil? || config.respond_to?(:call)
+      nil
+    end
+
+    def normalize(config)
+      unless config.is_a?(Hash)
+        raise InvalidConfig, "#{SETTING} must be nil, a Hash { flag:, store:, controls: } " \
+                             "or a callable returning one (got #{config.class})"
+      end
+
+      config = config.to_h { |key, value| [key.to_sym, value] }
+      unknown = config.keys - KEYS
+      raise InvalidConfig, "#{SETTING} has unknown key :#{unknown.first}" if unknown.any?
+
+      { store: identifier(config.fetch(:store, nil) || "sidebars", :store),
+        flag: identifier(config[:flag], :flag),
+        controls: controls(config[:controls]) }
+    end
+
+    def identifier(value, key)
+      name = value.to_s
+      unless (value.is_a?(String) || value.is_a?(Symbol)) && name.match?(IDENTIFIER)
+        raise InvalidConfig, "#{SETTING} :#{key} must be a plain JavaScript name (got #{value.inspect})"
+      end
+
+      String.new(name)
+    end
+
+    def controls(value)
+      ids = value.is_a?(Array) ? value : value.to_s.split
+      ids = ids.map { |id| id.is_a?(Symbol) ? id.to_s : id }
+      if ids.empty? || !ids.all? { |id| id.is_a?(String) && id.match?(DOM_ID) }
+        raise InvalidConfig, "#{SETTING} :controls must name the panel ids it opens (got #{value.inspect})"
+      end
+      if (engine = ids & ENGINE_LINK_SIDEBAR_IDS).any?
+        raise InvalidConfig, "#{SETTING} :controls names #{engine.join(' and ')}, the engine's link sidebar: " \
+                             "studio/link_sidebar would take the click and open its panel, not the host's. " \
+                             "Name the host's own panel ids, or leave the setting nil to keep the link sidebar"
+      end
+
+      ids.join(" ")
+    end
+
+    def reset_reported!
+      @reported_lock.synchronize { @reported.clear }
+    end
+
+    def report_once(error)
+      first = @reported_lock.synchronize { @reported[error.class.name] ? false : (@reported[error.class.name] = true) }
+      return unless first
+
+      if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+        ::ErrorLog.capture!(error)
+      elsif defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger.warn("[studio-navbar] #{SETTING} failed, rendering the default account control: " \
+                            "#{error.class}: #{error.message}")
+      end
+    rescue StandardError
+      nil # reporting is best-effort: the navbar still renders
+    end
+  end
+end

data/lib/studio/navbar_brand.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Studio.navbar_brand: the engine navbar's logo image and title words, for an
+# app whose brand is not "the Navbar Logo theme image plus app_name with the
+# last word in text-primary". Pure Ruby, so the unit suite covers it without
+# the dummy app.
+#
+# nil, the default, renders the navbar byte-identical to before. A Hash:
+#
+#   config.navbar_brand = {
+#     logo: "/icon-192.png",            # the image (default: Studio.logo_for("Navbar Logo"))
+#     logo_size: 48,                    # width and height attributes, in px (optional)
+#     alt: "Turf Monster",              # the image's alt (default: Studio.app_name)
+#     words: [{ text: "Turf", class: "text-heading" },
+#             { text: "Monster", class: "tm-wordmark" }]   # the title, one span each
+#   }
+#
+# Every key is optional. words replaces the app_name split: each word is a
+# String or { text:, class: }, drawn as its own truncating span in the title
+# with the host's class and nothing else (no text-primary), so a split
+# wordmark styles each half. Studio.navbar_wordmark, a one-piece lockup image,
+# wins over this when both are set.
+module Studio
+  module NavbarBrand
+    class InvalidConfig < ArgumentError; end
+
+    SETTING = "Studio.navbar_brand"
+    KEYS = %i[logo logo_size alt words].freeze
+    WORD_KEYS = %i[text class].freeze
+
+    module_function
+
+    # The config as a Hash with only the keys given, or nil when unset.
+    def normalize(config)
+      return nil if config.nil?
+      raise InvalidConfig, "#{SETTING} must be nil or a Hash (got #{config.class})" unless config.is_a?(Hash)
+
+      config = config.to_h { |key, value| [key.to_sym, value] }
+      unknown = config.keys - KEYS
+      raise InvalidConfig, "#{SETTING} has unknown key :#{unknown.first}" if unknown.any?
+
+      brand = {}
+      brand[:logo] = text(config[:logo], "#{SETTING}[:logo]") unless config[:logo].nil?
+      brand[:alt] = text(config[:alt], "#{SETTING}[:alt]") unless config[:alt].nil?
+      unless config[:logo_size].nil?
+        size = config[:logo_size]
+        unless size.is_a?(Integer) && size.positive?
+          raise InvalidConfig, "#{SETTING}[:logo_size] must be a positive Integer of px (got #{size.inspect})"
+        end
+
+        brand[:logo_size] = size
+      end
+      brand[:words] = words(config[:words]) unless config[:words].nil?
+      brand.freeze
+    end
+
+    def words(list)
+      unless list.is_a?(Array) && list.any?
+        raise InvalidConfig, "#{SETTING}[:words] must be a non-empty Array (got #{list.inspect})"
+      end
+
+      list.each_with_index.map do |word, index|
+        where = "#{SETTING}[:words][#{index}]"
+        word = { text: word } if word.is_a?(String)
+        raise InvalidConfig, "#{where} must be a String or a Hash { text:, class: } (got #{word.class})" unless word.is_a?(Hash)
+
+        word = word.to_h { |key, value| [key.to_sym, value] }
+        unknown = word.keys - WORD_KEYS
+        raise InvalidConfig, "#{where} has unknown key :#{unknown.first}" if unknown.any?
+
+        { text: text(word[:text], "#{where}[:text]"),
+          class: word[:class].nil? ? nil : text(word[:class], "#{where}[:class]") }.freeze
+      end.freeze
+    end
+
+    # A non-blank String, stripped. String.new drops an html_safe flag, so ERB
+    # escapes whatever came back.
+    def text(value, where)
+      raise InvalidConfig, "#{where} must be a non-blank String (got #{value.inspect})" unless value.is_a?(String) && !value.strip.empty?
+
+      String.new(value).strip.freeze
+    end
+  end
+end

data/lib/studio/navbar_signed_out_cta.rb

@@ -15,6 +15,21 @@
 #   ->(view) { { label:, path: } }   a callable receiving the view; answering nil
 #                                    keeps the default for that render
 #
+# Three optional keys (each absent, the CTA renders as it did in 0.113.0):
+#
+#   modal:         "auth", or { id: "auth", props: { step: "credentials" } }.
+#                  The button opens that modal on the engine's modal host
+#                  ($store.modals.open(id, props)), carries
+#                  aria-haspopup="dialog", and path stays its href, the
+#                  fallback with no script or no modal host. The expression is
+#                  the engine's, built from this data: the id is a plain name
+#                  and props must be JSON (strings, numbers, booleans, nil,
+#                  arrays and hashes of them), so no host JavaScript reaches the
+#                  page as a string.
+#   sign_in_link:  false drops the quiet sign-in text link (desktop and phone
+#                  row), for an app whose CTA IS its sign-in. Default true.
+#   sign_in_path:  where the sign-in text link points. Default login_path.
+#
 # It is separate from Studio.sign_in_label on purpose: that label also words the
 # engine's own auth pages (lib/studio/auth_labels.rb), so it cannot be bent into
 # a marketing CTA. The sign-in link always keeps it.
@@ -29,6 +44,9 @@ module Studio
     class InvalidConfig < ArgumentError; end
 
     KEYS = %i[label path].freeze
+    OPTIONAL_KEYS = %i[modal sign_in_link sign_in_path].freeze
+    MODAL_ID = /\A[A-Za-z_][\w-]*\z/
+    SETTING = "Studio.navbar_signed_out_cta"
 
     @reported = {}
     @reported_lock = Mutex.new
@@ -66,17 +84,68 @@ module Studio
       end
 
       config = config.to_h { |key, value| [key.to_sym, value] }
-      unknown = config.keys - KEYS
-      raise InvalidConfig, "Studio.navbar_signed_out_cta has unknown key :#{unknown.first}" if unknown.any?
+      unknown = config.keys - KEYS - OPTIONAL_KEYS
+      raise InvalidConfig, "#{SETTING} has unknown key :#{unknown.first}" if unknown.any?
 
-      KEYS.to_h do |key|
-        value = config[key]
-        unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
-          raise InvalidConfig, "Studio.navbar_signed_out_cta needs a non-blank :#{key} (got #{value.inspect})"
+      cta = KEYS.to_h { |key| [key, text(config[key], key)] }
+      cta[:modal] = modal(config[:modal]) if config.key?(:modal) && !config[:modal].nil?
+      if config.key?(:sign_in_link)
+        unless [true, false].include?(config[:sign_in_link])
+          raise InvalidConfig, "#{SETTING} :sign_in_link must be true or false (got #{config[:sign_in_link].inspect})"
         end
 
-        # String.new drops an html_safe flag, so ERB escapes whatever came back.
-        [key, String.new(value.to_s).strip]
+        cta[:sign_in_link] = config[:sign_in_link]
+      end
+      cta[:sign_in_path] = text(config[:sign_in_path], :sign_in_path) if config.key?(:sign_in_path) && !config[:sign_in_path].nil?
+      cta
+    end
+
+    # A non-blank String or Symbol, as a plain stripped String. String.new drops
+    # an html_safe flag, so ERB escapes whatever came back.
+    def text(value, key)
+      unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+        raise InvalidConfig, "#{SETTING} needs a non-blank :#{key} (got #{value.inspect})"
+      end
+
+      String.new(value.to_s).strip
+    end
+
+    # The modal to open, as { id: String, props: Hash }.
+    def modal(value)
+      value = { id: value } if value.is_a?(String) || value.is_a?(Symbol)
+      unless value.is_a?(Hash)
+        raise InvalidConfig, "#{SETTING} :modal must be a modal id or a Hash { id:, props: } (got #{value.class})"
+      end
+
+      value = value.to_h { |key, entry| [key.to_sym, entry] }
+      unknown = value.keys - %i[id props]
+      raise InvalidConfig, "#{SETTING} :modal has unknown key :#{unknown.first}" if unknown.any?
+
+      id = value[:id].to_s
+      unless (value[:id].is_a?(String) || value[:id].is_a?(Symbol)) && id.match?(MODAL_ID)
+        raise InvalidConfig, "#{SETTING} :modal needs an :id that is a plain name (got #{value[:id].inspect})"
+      end
+
+      props = value.fetch(:props, nil) || {}
+      raise InvalidConfig, "#{SETTING} :modal :props must be a Hash (got #{props.class})" unless props.is_a?(Hash)
+
+      { id: String.new(id), props: json(props, "#{SETTING} :modal :props") }
+    end
+
+    # A JSON value: strings, numbers, booleans, nil, and arrays and hashes of
+    # them. Hash keys become Strings.
+    def json(value, where)
+      case value
+      when Hash
+        value.to_h do |key, entry|
+          raise InvalidConfig, "#{where} keys must be Strings or Symbols (got #{key.inspect})" unless key.is_a?(String) || key.is_a?(Symbol)
+
+          [String.new(key.to_s), json(entry, "#{where}[#{key.inspect}]")]
+        end
+      when Array then value.each_with_index.map { |entry, index| json(entry, "#{where}[#{index}]") }
+      when String, Symbol then String.new(value.to_s)
+      when Integer, Float, true, false, nil then value
+      else raise InvalidConfig, "#{where} must be JSON: strings, numbers, booleans, nil, arrays, hashes (got #{value.class})"
       end
     end
 

data/lib/studio/navbar_slots.rb

@@ -7,6 +7,12 @@
 #                               the desktop bar AND the phone row
 #   Studio.navbar_avatar_badge  one partial rendered over the signed-in avatar's
 #                               upper-left corner (components/_user_nav, Div 3)
+#   Studio.navbar_header_bars   partials rendered INSIDE the pinned header, above
+#                               its row, so they never scroll away (a control
+#                               bar such as an impersonation escape)
+#   Studio.navbar_menu_trigger  one partial the icon rail and the phone row
+#                               render in place of the admin dropdown; it is
+#                               rendered twice, so it carries no ids
 #
 # A partial spec is one of:
 #
@@ -14,7 +20,8 @@
 #   { partial: "shared/wallet_signal",              a path with locals
 #     locals: { tone: "muted" } }
 #
-# navbar_items is an Array of specs, navbar_avatar_badge one spec or nil, and
+# navbar_items and navbar_header_bars are Arrays of specs, navbar_avatar_badge
+# and navbar_menu_trigger one spec or nil, and
 # either may instead be a callable receiving the view that answers the same
 # (nil meaning nothing for that render). Both defaults render nothing, so the
 # navbar stays byte-identical until an app opts in.
@@ -31,6 +38,8 @@ module Studio
     SPEC_KEYS = %i[partial locals].freeze
     ITEMS = "Studio.navbar_items"
     BADGE = "Studio.navbar_avatar_badge"
+    HEADER_BARS = "Studio.navbar_header_bars"
+    MENU_TRIGGER = "Studio.navbar_menu_trigger"
 
     @reported = {}
     @reported_lock = Mutex.new
@@ -38,37 +47,50 @@ module Studio
     module_function
 
     # The item specs for one render, in order; [] renders nothing.
-    def resolve_items(config, view)
-      answer = call(config, view, ITEMS) { return [] }
-      items(answer)
+    def resolve_items(config, view, setting = ITEMS)
+      answer = call(config, view, setting) { return [] }
+      items(answer, setting)
     end
 
     # The badge spec for one render, or nil for no badge.
-    def resolve_badge(config, view)
-      answer = call(config, view, BADGE) { return nil }
-      answer.nil? ? nil : spec(answer, BADGE)
+    def resolve_badge(config, view, setting = BADGE)
+      answer = call(config, view, setting) { return nil }
+      answer.nil? ? nil : spec(answer, setting)
+    end
+
+    # The header bar specs for one render, in order; [] renders nothing.
+    def resolve_header_bars(config, view)
+      resolve_items(config, view, HEADER_BARS)
+    end
+
+    # The menu trigger spec for one render, or nil for the admin dropdown.
+    def resolve_menu_trigger(config, view)
+      resolve_badge(config, view, MENU_TRIGGER)
     end
 
     # Shape checks without a view: a static setting fails at boot, not on the
     # first page render. A callable is checked when it resolves.
-    def validate_items!(config)
-      items(config) unless config.respond_to?(:call)
+    def validate_items!(config, setting = ITEMS)
+      items(config, setting) unless config.respond_to?(:call)
       nil
     end
 
-    def validate_badge!(config)
-      spec(config, BADGE) unless config.nil? || config.respond_to?(:call)
+    def validate_badge!(config, setting = BADGE)
+      spec(config, setting) unless config.nil? || config.respond_to?(:call)
       nil
     end
 
-    def items(list)
+    def validate_header_bars!(config) = validate_items!(config, HEADER_BARS)
+    def validate_menu_trigger!(config) = validate_badge!(config, MENU_TRIGGER)
+
+    def items(list, setting = ITEMS)
       return [] if list.nil?
       unless list.is_a?(Array)
-        raise InvalidConfig, "#{ITEMS} must be an Array of partial specs or a callable returning one " \
+        raise InvalidConfig, "#{setting} must be an Array of partial specs or a callable returning one " \
                              "(got #{list.class})"
       end
 
-      list.each_with_index.map { |entry, index| spec(entry, "#{ITEMS}[#{index}]") }
+      list.each_with_index.map { |entry, index| spec(entry, "#{setting}[#{index}]") }
     end
 
     # One spec, as { partial: String, locals: Hash }.

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.113.0"
+  VERSION = "0.114.0"
 end

data/lib/studio.rb

@@ -35,8 +35,10 @@ require "studio/booking"
 require "studio/navbar_links"
 require "studio/navbar_signed_out_cta"
 require "studio/navbar_slots"
+require "studio/navbar_account_sidebar"
 require "studio/navbar_identity"
 require "studio/navbar_wordmark"
+require "studio/navbar_brand"
 require "studio/auth_labels"
 require "studio/profile_sections"
 require "studio/profile_image"
@@ -335,6 +337,117 @@ module Studio
     @@navbar_avatar_badge = config
   end
 
+  # ---- Navbar header bars ----
+  # Partials the engine navbar renders INSIDE its pinned header, above the row,
+  # so they stay on screen while the page scrolls: a control an admin must not
+  # lose, such as an impersonation bar's "Return to <admin>" button. The bar
+  # stack (studio/banners/_stack) is the place for an ambient label; it renders
+  # above the header and scrolls away. Skipped on a preview render. The default
+  # [] renders byte-identical to before. An Array, or a callable receiving the
+  # view, of partial specs. Rules: lib/studio/navbar_slots.rb.
+  #
+  #   config.navbar_header_bars = ->(view) { view.impersonating? ? ["shared/impersonation_banner"] : [] }
+  mattr_reader :navbar_header_bars, default: []
+
+  def self.navbar_header_bars=(config)
+    NavbarSlots.validate_header_bars!(config)
+    NavbarSlots.reset_reported!
+    @@navbar_header_bars = config
+  end
+
+  # ---- Navbar menu trigger ----
+  # One partial the signed-in user nav's icon rail (from md) and the navbar's
+  # phone row render in place of the admin dropdown: the control that opens a
+  # host's own menu, such as Turf Monster's gear sidebar trigger. nil, the
+  # default, keeps the admin dropdown, byte-identical to before. A partial spec,
+  # or a callable receiving the view. Rules: lib/studio/navbar_slots.rb.
+  #
+  #   config.navbar_menu_trigger = "components/gear_sidebar_trigger"
+  mattr_reader :navbar_menu_trigger, default: nil
+
+  def self.navbar_menu_trigger=(config)
+    NavbarSlots.validate_menu_trigger!(config)
+    NavbarSlots.reset_reported!
+    @@navbar_menu_trigger = config
+  end
+
+  # ---- Navbar account sidebar ----
+  # The host sidebar the signed-in user nav's account control (name and
+  # avatar, one control) opens: a button toggling $store.<store>.<flag>, its
+  # aria-controls naming the panels. nil, the default, keeps the account link
+  # (or the link sidebar), byte-identical to before. A Hash, or a callable
+  # receiving the view. Pair it with Studio.navbar_menu_trigger for the gear.
+  # Rules: lib/studio/navbar_account_sidebar.rb.
+  #
+  #   config.navbar_account_sidebar = { flag: "gearOpen", controls: %w[gear-sidebar gear-sidebar-mobile] }
+  mattr_reader :navbar_account_sidebar, default: nil
+
+  def self.navbar_account_sidebar=(config)
+    NavbarAccountSidebar.validate!(config)
+    NavbarAccountSidebar.reset_reported!
+    @@navbar_account_sidebar = config
+  end
+
+  # ---- Navbar phone name ----
+  # true shows the signed-in name beside the avatar below md too, capped at
+  # 4.5rem (6rem from 400px) and fading out at its right edge when it does not
+  # fit, instead of hiding it as screen-reader text. The fade is CSS only
+  # (engine.css, THE PHONE NAME): it runs on the name's own scroll timeline,
+  # which is inactive when the name fits, so a short name never fades. A
+  # browser without scroll timelines clips the name. false, the default,
+  # renders byte-identical to before.
+  #
+  #   config.navbar_phone_name = true
+  mattr_reader :navbar_phone_name, default: false
+
+  def self.navbar_phone_name=(value)
+    @@navbar_phone_name = navbar_boolean!(:navbar_phone_name, value)
+  end
+
+  # ---- Navbar brand ----
+  # The navbar's logo image and title words, for an app whose brand is not the
+  # "Navbar Logo" image plus app_name with its last word in text-primary: a
+  # logo path and size, its alt, and the title as words, each its own span
+  # with the host's class (a split wordmark). nil, the default, renders
+  # byte-identical to before; every key is optional. navbar_wordmark wins when
+  # both are set. Rules: lib/studio/navbar_brand.rb.
+  #
+  #   config.navbar_brand = { logo: "/icon-192.png", logo_size: 48,
+  #                           words: [{ text: "Turf" }, { text: "Monster", class: "tm-wordmark" }] }
+  mattr_reader :navbar_brand, default: nil
+
+  def self.navbar_brand=(config)
+    @@navbar_brand = NavbarBrand.normalize(config)
+  end
+
+  # ---- Navbar root hook and layer tier ----
+  # navbar_root_hook: true puts data-navbar-root on the header (live and
+  # preview), the hook a host's tests and scripts find the navbar by.
+  # navbar_z_tier: true layers the live header on the shared layer scale,
+  # z-[var(--z-nav)] (engine.css), in place of z-50, so a modal (--z-modal)
+  # covers it and the tiers stay one table. Both false by default, which
+  # renders byte-identical to before.
+  #
+  #   config.navbar_root_hook = true
+  #   config.navbar_z_tier = true
+  mattr_reader :navbar_root_hook, default: false
+  mattr_reader :navbar_z_tier, default: false
+
+  def self.navbar_root_hook=(value)
+    @@navbar_root_hook = navbar_boolean!(:navbar_root_hook, value)
+  end
+
+  def self.navbar_z_tier=(value)
+    @@navbar_z_tier = navbar_boolean!(:navbar_z_tier, value)
+  end
+
+  def self.navbar_boolean!(name, value)
+    return value if [true, false].include?(value)
+
+    raise ArgumentError, "Studio.#{name} must be true or false (got #{value.inspect})"
+  end
+  private_class_method :navbar_boolean!
+
   # ---- 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
@@ -1486,6 +1599,22 @@ module Studio
     NavbarSlots.resolve_badge(navbar_avatar_badge, view)
   end
 
+  # The in-header bar partial specs for a view (lib/studio/navbar_slots.rb).
+  def self.navbar_header_bars_for(view)
+    NavbarSlots.resolve_header_bars(navbar_header_bars, view)
+  end
+
+  # The menu trigger partial spec for a view, or nil (lib/studio/navbar_slots.rb).
+  def self.navbar_menu_trigger_for(view)
+    NavbarSlots.resolve_menu_trigger(navbar_menu_trigger, view)
+  end
+
+  # The account control's host sidebar for a view, or nil
+  # (lib/studio/navbar_account_sidebar.rb).
+  def self.navbar_account_sidebar_for(view)
+    NavbarAccountSidebar.resolve(navbar_account_sidebar, view)
+  end
+
   # The signed-in user's navbar name for a view (lib/studio/navbar_identity.rb).
   def self.navbar_user_name_for(user, view = nil)
     NavbarIdentity.user_name(user, view, config: navbar_user_name)