studio-engine 0.113.0 → 0.114.0.rc1

data/app/javascript/studio/newsletter_modal.js

@@ -0,0 +1,252 @@
+// studio/newsletter_modal: the newsletter cards' JSON mode
+// (studio/profiles/_newsletter_modals with submit_mode: :json).
+//
+//   x-data="studioNewsletterModal({ action: 'subscribe', url, store, needsEmail, requiresConsent, nextId, event })"
+//
+// One scope for every card, so each binds the same names: email, consent,
+// saving, error, props, ready and submit(). A card that only shows (the success
+// and goodbye beats) binds props and nothing else.
+//
+// WHAT submit() DOES, in order:
+//   1. Refuses quietly while a request is in flight, or while a consent box the
+//      card carries is unticked (the button is disabled then too).
+//   2. When the card asks for an address, refuses an address with no "@" past
+//      its first character, on the card's own error line.
+//   3. HANDS OFF when the opener passed props.onSubmit: closes the card and
+//      calls it with the address (or null). The opener owns the request then;
+//      this is how a page that already knows how to subscribe asks only for the
+//      address.
+//   4. Otherwise POSTs JSON to the host's url (DELETE or another verb by
+//      opts.method) with the page's CSRF token, and reads the answer: a 2xx, not by redirect, whose
+//      body does not say success: false is a success; anything else shows
+//      body.error, or a plain line, on the card. The request goes through
+//      plain fetch, or through the host's own fetcher when opts.fetcher names
+//      one (THE HOST'S FETCHER, below).
+//   5. On success: dispatches opts.event on window with
+//      { subscribed, email, response }, calls props.onSuccess(response) when the
+//      opener passed one, then swaps to opts.nextId (the success or goodbye card)
+//      with the response as its props, or closes when there is none.
+//
+// No page reload anywhere: the host's listener updates whatever the page shows.
+//
+// THE HOST'S FETCHER. A host whose requests go through its own wrapper (Turf
+// Monster's authedFetch: a 401 opens the sign-in card, a 429 the rate-limit
+// card) names it with opts.fetcher, a JS identifier. The card resolves it as a
+// named export of the importmap module "studio/host_fetchers": the engine pins
+// that name to an empty module, and a host that pins the same name to its own
+// file wins (FRONT_END_STANDARD.md, "The engine's modules"). Never a window
+// global: the standard forbids a window.* API between files. The host's module
+// is imported on the first press that needs it, not at boot.
+//
+//   # the host's config/importmap.rb
+//   pin "studio/host_fetchers", to: "newsletter_fetchers.js"
+//   // app/javascript/newsletter_fetchers.js
+//   export { authedFetch } from "solana_utils"
+//
+// The fetcher takes fetch's arguments and returns a Response, or null when it
+// has answered the request itself (authedFetch opens its own card and returns
+// null): the card then stops its spinner and says nothing more. A name the
+// module does not export as a function, or a module that does not load, fails
+// the press with the card's plain line and one console error; it never falls
+// back to plain fetch, which would quietly drop the host's 401 handling.
+//
+// studio/alpine_scopes publishes the factory on window, statically: Alpine
+// evaluates the x-data as the modal host mounts the card. It imports nothing
+// statically (the host's fetcher module is a dynamic import);
+// test/javascript/newsletter_modal.test.mjs loads it as a data: module.
+
+export const INVALID_EMAIL = "Enter a valid email address."
+export const SUBSCRIBE_FAILED = "Could not join the newsletter."
+export const UNSUBSCRIBE_FAILED = "Could not unsubscribe."
+export const CHANGED_EVENT = "studio:newsletter-changed"
+export const HOST_FETCHERS = "studio/host_fetchers"
+export const FETCHER_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+// The host's fetcher named +name+, as a function, or null when the module does
+// not load or does not export a function by that name. +importer+ loads
+// studio/host_fetchers (the tests pass their own).
+export async function resolveFetcher(name, importer) {
+  if (!FETCHER_NAME.test(String(name || ""))) return null
+  try {
+    const mod = await importer()
+    const fn = mod && mod[name]
+    return typeof fn === "function" ? fn : null
+  } catch (_) {
+    return null
+  }
+}
+
+// The address trimmed, or "" when it cannot be one: an "@" with nothing before
+// it, or none at all. The server is the real check; this only saves a round trip
+// for the address nobody meant.
+export function cleanEmail(value) {
+  const s = String(value == null ? "" : value).trim()
+  return s.indexOf("@") > 0 ? s : ""
+}
+
+// What the host's answer means. ok: a 2xx whose body does not say
+// success: false, and that fetch did not reach by a redirect (an expired session
+// redirected to an HTML sign-in page answers 200, and joined nobody). error:
+// the body's own words, else the fallback.
+export function outcomeOf(response, body, fallback) {
+  body = body && typeof body === "object" ? body : {}
+  const ok = !!(response && response.ok && !response.redirected) && body.success !== false
+  return ok ? { ok: true, body: body } : { ok: false, body: body, error: body.error || fallback }
+}
+
+// The page's CSRF token, or "" on a page without one.
+export function csrfToken(doc) {
+  try {
+    const meta = doc && doc.querySelector('meta[name="csrf-token"]')
+    return (meta && meta.content) || ""
+  } catch (_) {
+    return ""
+  }
+}
+
+// x-data for a newsletter card.
+//
+// opts:
+//   action           "subscribe" (default) or "unsubscribe".
+//   url              the host's JSON endpoint for the action.
+//   method           the verb (default "POST").
+//   store            the Alpine store the card is mounted in (default "modals").
+//   needsEmail       the card asks for an address.
+//   requiresConsent  the card carries a consent box (ticked to start).
+//   nextId           the card a success swaps to; blank closes instead.
+//   event            the window event a success dispatches (CHANGED_EVENT).
+//   fetcher          the host's fetcher, by its export name in
+//                    studio/host_fetchers; blank sends through plain fetch.
+//
+// env: { win, importer } for the tests.
+export function studioNewsletterModal(opts, env) {
+  opts = opts || {}
+  const win = (env && env.win) || (typeof window !== "undefined" ? window : {})
+  const action = opts.action === "unsubscribe" ? "unsubscribe" : "subscribe"
+  const importer = (env && env.importer) || (() => import("studio/host_fetchers"))
+
+  return {
+    email: "",
+    consent: true,
+    saving: false,
+    error: "",
+    action: action,
+    url: opts.url || "",
+    method: String(opts.method || "POST").toUpperCase(),
+    store: opts.store || "modals",
+    needsEmail: !!opts.needsEmail,
+    requiresConsent: !!opts.requiresConsent,
+    nextId: opts.nextId || "",
+    event: opts.event || CHANGED_EVENT,
+    fetcher: opts.fetcher || "",
+
+    _store() {
+      try { return win.Alpine.store(this.store) } catch (_) { return null }
+    },
+
+    // The open card's props, or {} with nothing open.
+    get props() {
+      const store = this._store()
+      const entry = store && store.current && store.current()
+      return (entry && entry.props) || {}
+    },
+
+    get ready() {
+      return !this.saving && (!this.requiresConsent || !!this.consent)
+    },
+
+    async submit() {
+      if (!this.ready) return
+      let address = null
+      if (this.needsEmail) {
+        address = cleanEmail(this.email)
+        if (!address) {
+          this.error = INVALID_EMAIL
+          return
+        }
+      }
+      this.error = ""
+
+      const props = this.props
+      if (action === "subscribe" && typeof props.onSubmit === "function") {
+        const handOff = props.onSubmit
+        this._close()
+        handOff(address)
+        return
+      }
+
+      this.saving = true
+      const fallback = action === "unsubscribe" ? UNSUBSCRIBE_FAILED : SUBSCRIBE_FAILED
+      let outcome
+      try {
+        const init = {
+          method: this.method,
+          credentials: "same-origin",
+          headers: {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "X-CSRF-Token": csrfToken(win.document)
+          }
+        }
+        if (action === "subscribe") init.body = JSON.stringify({ email: address })
+        const send = await this._sender()
+        if (!send) {
+          outcome = { ok: false, body: {}, error: fallback }
+        } else {
+          const response = await send(this.url, init)
+          if (response == null && this.fetcher) {
+            // The host's fetcher answered it (its own sign-in or wait card).
+            this.saving = false
+            return
+          }
+          let body = {}
+          try { body = await response.json() } catch (_) {}
+          outcome = outcomeOf(response, body, fallback)
+        }
+      } catch (_) {
+        outcome = { ok: false, body: {}, error: fallback }
+      }
+
+      this.saving = false
+      if (!outcome.ok) {
+        this.error = outcome.error
+        return
+      }
+      this._succeed(outcome.body, address, props)
+    },
+
+    // What sends the request: plain fetch, or the host's named fetcher; null
+    // when a named one cannot be found.
+    async _sender() {
+      if (!this.fetcher) return (url, init) => win.fetch(url, init)
+      const fn = await resolveFetcher(this.fetcher, importer)
+      if (!fn) {
+        try {
+          win.console.error(`studio/newsletter_modal: ${HOST_FETCHERS} exports no function named ${this.fetcher}`)
+        } catch (_) {}
+      }
+      return fn
+    },
+
+    _succeed(body, address, props) {
+      const subscribed = action === "subscribe"
+      try {
+        win.dispatchEvent(new win.CustomEvent(this.event, {
+          detail: { subscribed: subscribed, email: address, response: body }
+        }))
+      } catch (_) {}
+      if (typeof props.onSuccess === "function") {
+        try { props.onSuccess(body) } catch (_) {}
+      }
+      const store = this._store()
+      if (!store) return
+      if (this.nextId) store.swap(this.nextId, body)
+      else store.close()
+    },
+
+    _close() {
+      const store = this._store()
+      if (store) store.close()
+    }
+  }
+}

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

@@ -17,9 +17,23 @@
     data-pin-edge: on a header on the scroll timeline the stack publishes the
     PINNED bar and nothing per frame, so at the top of the page this fixed panel
     would cover the expanded header. engine.css (THE PINNED EDGE ON THE SCROLL
-    TIMELINE) moves it with the header on the scroll timeline instead. %>
+    TIMELINE) moves it with the header on the scroll timeline instead.
+
+    Two opt-in locals (unset, the panel renders as it did in 0.113.0):
+      title_html  the header's LEAD SLOT: HTML in the title's place, for a panel
+                  whose lead is a live status line rather than a label. It is
+                  content, NOT a name: it never feeds aria-labelledby or
+                  aria-label, so a caller that passes it instead of `title` must
+                  pass aria_label, or the panel has no accessible name. `title`
+                  wins when both are passed. Escaped unless html_safe.
+      close_hook  true stamps the close button data-sidebar-panel-close="<id>"
+                  too, so a host's own document handler can match the button
+                  to its panel by id. Needs `id`; without one it adds nothing.
+                  data-link-sidebar-close stays, and studio/link_sidebar counts
+                  it only inside its own panels. %>
 <% id             = local_assigns.fetch(:id, nil) %>
 <% title          = local_assigns.fetch(:title, nil) %>
+<% title_html     = local_assigns.fetch(:title_html, nil) %>
 <% open           = local_assigns.fetch(:open) %>
 <% actions_html   = local_assigns.fetch(:actions_html, nil) %>
 <% body_html      = local_assigns.fetch(:body_html, nil) %>
@@ -34,6 +48,7 @@
 <% role           = local_assigns.fetch(:role, "complementary") %>
 <% aria_label     = local_assigns.fetch(:aria_label, title) %>
 <% labelledby     = id.present? && title.present? ? "#{id}-title" : nil %>
+<% close_hook     = local_assigns.fetch(:close_hook, false) && id.present? %>
 
 <aside
   <% if id.present? %>id="<%= id %>"<% end %>
@@ -64,10 +79,14 @@
   role="<%= role %>"
   <% if labelledby %>aria-labelledby="<%= labelledby %>"<% elsif aria_label.present? %>aria-label="<%= aria_label %>"<% end %>>
   <div class="flex flex-col h-full">
-    <% if title.present? || actions_html.present? || close_action.present? %>
+    <% if title.present? || title_html.present? || actions_html.present? || close_action.present? %>
       <div class="flex items-center justify-between p-4 border-b border-subtle">
         <% if title.present? %>
           <h3 <% if labelledby %>id="<%= labelledby %>"<% end %> class="text-lg font-bold text-heading"><%= title %></h3>
+        <% elsif title_html.present? %>
+          <%# min-w-0 so a long status line truncates in its own box instead of
+              pushing the close button off the panel's edge on a phone. %>
+          <div class="min-w-0 flex-1" data-sidebar-panel-lead><%= title_html %></div>
         <% end %>
         <div class="flex items-center gap-2 ml-auto">
           <%= actions_html if actions_html.present? %>
@@ -76,7 +95,7 @@
                     @click="<%= close_action %>"
                     class="flex items-center justify-center w-8 h-8 rounded-full text-secondary hover:text-heading hover:bg-surface-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 transition"
                     aria-label="Close sidebar"
-                    data-link-sidebar-close="true">
+                    data-link-sidebar-close="true"<% if close_hook %> data-sidebar-panel-close="<%= id %>"<% end %>>
               <span class="text-xl leading-none">&times;</span>
             </button>
           <% end %>

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

@@ -15,7 +15,10 @@
     (default display_name) and the signed-out button reads
     Studio.sign_in_label (default "Log in"); lib/studio/navbar_identity.rb.
     Studio.navbar_avatar_badge (default nil) draws one partial over the
-    avatar; lib/studio/navbar_slots.rb.
+    avatar, and Studio.navbar_menu_trigger (default nil) replaces the admin
+    dropdown in the icon rail; lib/studio/navbar_slots.rb.
+    Studio.navbar_account_sidebar (default nil) makes the account control
+    open a host sidebar; lib/studio/navbar_account_sidebar.rb.
 
     Legacy string locals (deprecated): balance_html, extra_icons_html,
     div2_html — pre-rendered HTML injected via raw. Still honored when
@@ -63,6 +66,9 @@
     of it. A link that goes nowhere looks identical to one that works until it is
     clicked, which is why nobody reported it.
 %>
+<%# Studio.navbar_menu_trigger: the host's menu control in the admin
+    dropdown's seat (the icon rail from md, and the signed-out rail). %>
+<% menu_trigger = respond_to?(:studio_navbar_menu_trigger) ? studio_navbar_menu_trigger : nil %>
 <% studio_nav_destination =
      if defined?(account_path)
        account_path
@@ -102,7 +108,11 @@
               glyphs side by side read as a double gear. Desktop only, like
               the theme toggle: below md the navbar's phone row draws the cog,
               so a second one here put two on an admin's phone. %>
+          <% if menu_trigger %>
+          <span class="hidden md:block" data-nav-menu-trigger><%= studio_navbar_slot_tag(menu_trigger) %></span>
+          <% else %>
           <%= render "components/admin_dropdown", display_class: "hidden md:block" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
+          <% end %>
         </div>
       </div>
       <% if div2_content.present? %>
@@ -219,15 +229,34 @@
         dialog" rather than a link that goes nowhere it says. studio/link_sidebar
         claims its click from the document, before Alpine binds, as it does the
         gear's. An app with no sidebar keeps the link to the account page. %>
-    <% account_opens_sidebar = respond_to?(:studio_account_opens_sidebar?) && studio_account_opens_sidebar? %>
+    <%# Studio.navbar_account_sidebar: a HOST sidebar the control opens
+        instead (a button toggling the host's store flag, built by the engine
+        from validated names). It wins over the link sidebar and the account
+        link. It carries data-profile-image-toggle, so a host handler that
+        claims its triggers in the capture phase, before Alpine binds, claims
+        this one; the guarded @click is the path when nothing claims it. Its
+        controls may not name the engine's own link sidebar ids, refused at
+        assignment (lib/studio/navbar_account_sidebar.rb). %>
+    <% account_sidebar = respond_to?(:studio_navbar_account_sidebar) ? studio_navbar_account_sidebar : nil %>
+    <% account_opens_sidebar = !account_sidebar && respond_to?(:studio_account_opens_sidebar?) && studio_account_opens_sidebar? %>
     <% account_classes = "group flex items-center gap-2 flex-shrink-0" %>
+    <%# Studio.navbar_phone_name: the name shows below md too, capped, and
+        fades at its edge when it overflows (engine.css, THE PHONE NAME). %>
+    <% phone_name = Studio.navbar_phone_name %>
     <% 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 account_opens_sidebar || studio_nav_destination %>" data-nav-name><%= Studio.navbar_user_name_for(current_user, self) %></span></span>
+      <% if phone_name %><span class="min-w-0 max-w-[4.5rem] min-[400px]:max-w-[6rem] md:max-w-40" data-nav-name-phone><% else %><span class="sr-only md:not-sr-only md:max-w-40"><% end %><span class="block truncate text-right text-heading font-semibold text-base leading-none transition<%= " group-hover:text-primary" if account_sidebar || account_opens_sidebar || studio_nav_destination %>" data-nav-name><%= Studio.navbar_user_name_for(current_user, self) %></span></span>
       <span class="flex-shrink-0 flex items-center" aria-hidden="true">
         <%= render "components/avatar", user: current_user, size: "nav" %>
       </span>
     <% end %>
-    <% if account_opens_sidebar %>
+    <% if account_sidebar %>
+      <% account_js = studio_navbar_account_sidebar_expressions(account_sidebar) %>
+      <%= tag.button type: "button", class: "#{account_classes} cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40",
+                     data: { nav_account: "", profile_image_toggle: "" },
+                     aria: { controls: account_sidebar[:controls], haspopup: "dialog" },
+                     ":aria-expanded": account_js[:expanded], "@click.stop": account_js[:toggle],
+                     "x-bind:style": "$store.devMode && 'background: lightgreen'" do %><%= account_inner %><% end %>
+    <% elsif account_opens_sidebar %>
       <button type="button" class="<%= account_classes %> cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40" data-nav-account data-profile-image-toggle
               aria-controls="studio-link-sidebar studio-link-sidebar-mobile" aria-haspopup="dialog"
               :aria-expanded="$store.sidebars && $store.sidebars.linkTreeOpen ? 'true' : 'false'"
@@ -251,7 +280,11 @@
     <div data-nav-avatar-badge><%= studio_navbar_slot_tag(avatar_badge) %></div>
     <% end %>
   <% else %>
+    <% if menu_trigger %>
+    <span class="hidden md:block" data-nav-menu-trigger><%= studio_navbar_slot_tag(menu_trigger) %></span>
+    <% else %>
     <%= render "components/admin_dropdown", display_class: "hidden md:block" unless respond_to?(:studio_sidebar_replaces_admin_menu?) && studio_sidebar_replaces_admin_menu? %>
+    <% end %>
     <%# 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">

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

@@ -4,6 +4,13 @@
       preview         — if true, disables scroll handler and sticky positioning
       balance_html    — raw HTML for balance display (passed through to _user_nav)
       extra_icons_html — raw HTML for extra icon buttons (passed through to _user_nav)
+      balance_slot, extra_icons_slot, div2_slot, div2_html
+                      — components/_user_nav's slot locals (a partial path, or
+                        { partial:, locals: }), forwarded to it as given. A
+                        balance_slot reserves the balance column as balance_html
+                        does. extra_icons_slot is rendered here, so the link
+                        sidebar's trigger still follows it; like the user nav,
+                        a slot wins over its legacy _html string.
       brand_heading   — boolean, draw the brand title as the page's h1 (default: true).
                         Pass false on a page that carries its own h1: the brand is
                         drawn as a div with the same classes and contents.
@@ -20,6 +27,13 @@
 <% pin_header = Studio.smooth_load && !is_preview %>
 <% balance_html = local_assigns.fetch(:balance_html, nil) %>
 <% extra_icons_html = local_assigns.fetch(:extra_icons_html, nil) %>
+<%# The user nav's slot locals, forwarded only when passed, so a navbar that
+    passes none renders the user nav exactly as before. %>
+<% user_nav_slots = local_assigns.slice(:balance_slot, :div2_slot, :div2_html).compact %>
+<% extra_icons_slot = local_assigns[:extra_icons_slot] %>
+<% if extra_icons_slot.present? %>
+  <% extra_icons_html = extra_icons_slot.is_a?(Hash) ? render(extra_icons_slot[:partial], **extra_icons_slot.fetch(:locals, {})) : render(extra_icons_slot.to_s) %>
+<% end %>
 <% brand_tag = local_assigns.fetch(:brand_heading, true) ? "h1" : "div" %>
 <%# Out-of-the-box navigation (engine 0.30): when the host declares
     Studio.sidebar_sections, the navbar mounts the link-sidebar trigger in its
@@ -50,6 +64,13 @@
   prefix = words.join(" ")
   logo_path = Studio.logo_for("Navbar Logo")
   wordmark = Studio.navbar_wordmark
+  # Studio.navbar_brand: the host's logo, its size and alt, and the title as
+  # words with the host's classes. nil (the default) draws as before.
+  brand = Studio.navbar_brand
+  logo_path = brand[:logo] if brand && brand[:logo]
+  logo_alt = (brand && brand[:alt]) || Studio.app_name
+  logo_size = brand && brand[:logo_size]
+  brand_words = brand && brand[:words]
 %>
 
 <%# nav-shell is the --nav-p scope: the engine's nav-collapse controller (studio/nav_collapse) writes
@@ -76,7 +97,10 @@
     or a scroll_timeline: local for one render; engine.css, THE SCROLL-DRIVEN
     COLLAPSE). Never on a preview: the /navbar page drives --nav-p itself. %>
 <% scroll_timeline = local_assigns.fetch(:scroll_timeline, Studio.navbar_scroll_timeline) %>
-<header data-pin="nav"<% unless is_preview %> x-data data-studio-controller="nav-collapse" data-nav-collapse-scrolled-class="shadow-lg border-b border-subtle is-scrolled"<%= " data-nav-timeline" if scroll_timeline %><% end %>
+<%# Studio.navbar_root_hook puts data-navbar-root on the header, live and
+    preview; Studio.navbar_z_tier layers the live header at --z-nav on the
+    shared scale (engine.css) instead of z-50. Both off renders as before. %>
+<header data-pin="nav"<%= " data-navbar-root".html_safe if Studio.navbar_root_hook %><% unless is_preview %> x-data data-studio-controller="nav-collapse" data-nav-collapse-scrolled-class="shadow-lg border-b border-subtle is-scrolled"<%= " data-nav-timeline" if scroll_timeline %><% end %>
         <%# top-0, a STATIC value, and never a custom property. Any bars render as
             this header's sibling in normal flow (studio/banners/_stack), so they
             already occupy their own height above it and there is nothing to
@@ -85,7 +109,7 @@
             measurement landed, moved again on a webfont swap, and drew twice
             during a view transition composited at two different tops. Only CSS
             can set this top now, so none of that is reachable. %>
-        class="nav-shell <%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 z-50 bg-page transition-shadow duration-300" %>"
+        class="nav-shell <%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 #{Studio.navbar_z_tier ? 'z-[var(--z-nav)]' : 'z-50'} bg-page transition-shadow duration-300" %>"
         <%= %(:class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'").html_safe if is_preview %>>
   <style>
     /* THE PHONE STEP IS A SHARE OF THE VIEWPORT, NOT A CONSTANT, and that is the
@@ -144,6 +168,18 @@
        title swap matters most: it is DISCRETE, which is the 1px reverse lurch
        the primitive exists to delete. Full accounting in engine.css. */
   </style>
+  <%# Studio.navbar_header_bars: bars INSIDE the pinned header, above its row,
+      so they never scroll away: a control an admin must not lose (an
+      impersonation bar's JS-free "Return to <admin>" button). An ambient
+      label belongs in the bar stack above the header, which scrolls. Being in
+      the header costs one thing, stated: the header is a stacking context, so
+      these never rise over an open modal. On the scroll timeline engine.css
+      (THE IN-HEADER BARS) carries them down by the band so they hold at the
+      window's top. Never on a preview, and [] (the default) renders nothing. %>
+  <% header_bars = !is_preview && respond_to?(:studio_navbar_header_bars) ? studio_navbar_header_bars : [] %>
+  <% if header_bars.any? %>
+  <div data-nav-header-bars><% header_bars.each do |bar| %><%= studio_navbar_slot_tag(bar) %><% end %></div>
+  <% end %>
   <div class="nav-row flex items-center">
     <%# Left side: logo + nav %>
     <%# min-w-0 THREE TIMES, on every flex item between the row and the title.
@@ -174,14 +210,16 @@
             <%# No w-*/h-* utility here: .nav-shell .nav-logo sizes it off --nav-p.
                 transition-transform, NOT transition-all — the hover lift still
                 eases, while width/height follow the finger with no clock. %>
-            <img src="<%= logo_path %>" alt="<%= Studio.app_name %>" class="nav-logo rounded-full shadow-lg <%= "group-hover:scale-105 transition-transform duration-300" unless is_preview %>">
+            <img src="<%= logo_path %>" alt="<%= logo_alt %>"<% if logo_size %> width="<%= logo_size %>" height="<%= logo_size %>"<% end %> class="nav-logo rounded-full shadow-lg <%= "group-hover:scale-105 transition-transform duration-300" unless is_preview %>">
           <% end %>
           <%# truncate on the SPANS, not the h1. .nav-title is itself a flex
               container (a column below 768px, a baseline row above), so the
               overflow that has to be clipped belongs to each word's own box —
               `truncate` on the h1 would clip the flex CONTAINER and leave the
               spans drawing outside it, which is the bug rather than the fix. %>
-          <<%= brand_tag %> 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></<%= brand_tag %>>
+          <%# Studio.navbar_brand's words, when set, replace the app_name split
+              inside the same h1: one span per word, the host's class plus truncate. %>
+          <<%= brand_tag %> class="nav-title font-extrabold text-heading tracking-tight min-w-0"><% if brand_words %><% brand_words.each do |word| %><span class="<%= [word[:class], "truncate"].compact.join(" ") %>"><%= word[:text] %></span><% end %><% else %><span class="truncate"><%= prefix %></span><span class="text-primary truncate"><%= last_word %></span><% end %></<%= brand_tag %>>
           <% end %>
         <% end %>
         <%# Desktop nav — Studio.navbar_links, then Studio.navbar_items. data-nav-links, only where the
@@ -201,16 +239,21 @@
     <%# Right side: user nav. The fixed column (matches sidebar width) exists
         to seat a balance in the top row; with no balance content it shrinks
         to fit. %>
-    <div class="<%= balance_html.present? ? 'user-nav-col' : 'user-nav-fit' %> flex-shrink-0 pl-0 pr-4 md:px-4">
+    <div class="<%= balance_html.present? || user_nav_slots[:balance_slot].present? ? 'user-nav-col' : 'user-nav-fit' %> flex-shrink-0 pl-0 pr-4 md:px-4">
       <% if show_user %>
-        <%= render "components/user_nav", balance_html: balance_html, extra_icons_html: extra_icons_html %>
+        <%= render "components/user_nav", balance_html: balance_html, extra_icons_html: extra_icons_html, **user_nav_slots %>
       <% else %>
         <div class="flex items-center justify-end gap-3">
           <%= sidebar_trigger_desktop if sidebar_active %>
           <span class="hidden md:flex"><%= render "components/theme_toggle_morph" %></span>
           <% if signed_out_cta %>
-          <%= link_to Studio.sign_in_label, login_path, class: "hidden md:inline text-sm font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
-          <%= link_to signed_out_cta[:label], signed_out_cta[:path], class: "btn btn-primary whitespace-nowrap", data: { nav_signed_out_cta: "" } %>
+          <%# sign_in_link: false drops the quiet link (the CTA is the sign-in);
+              sign_in_path points it elsewhere; modal: opens a modal from the
+              button, its path the fallback (lib/studio/navbar_signed_out_cta.rb). %>
+          <% unless signed_out_cta[:sign_in_link] == false %>
+          <%= link_to Studio.sign_in_label, signed_out_cta[:sign_in_path] || login_path, class: "hidden md:inline text-sm font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
+          <% end %>
+          <%= link_to signed_out_cta[:label], signed_out_cta[:path], class: "btn btn-primary whitespace-nowrap", data: { nav_signed_out_cta: "" }, **studio_navbar_cta_modal_options(signed_out_cta) %>
           <% else %>
           <%= link_to Studio.sign_in_label, login_path, class: "btn btn-primary" %>
           <% end %>
@@ -231,11 +274,18 @@
     <%= studio_navbar_slot_tag(item) %>
     <% end %>
     <span class="ml-auto flex items-center gap-3">
-      <% if signed_out_cta %>
-      <%= link_to Studio.sign_in_label, login_path, class: "text-xs font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
+      <% if signed_out_cta && signed_out_cta[:sign_in_link] != false %>
+      <%= link_to Studio.sign_in_label, signed_out_cta[:sign_in_path] || login_path, class: "text-xs font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
       <% end %>
       <%= render "components/link_sidebar_trigger" if sidebar_active %>
+      <%# Studio.navbar_menu_trigger takes the admin dropdown's seat here too: its
+          second render (the rail is the first), so the partial carries no ids. %>
+      <% menu_trigger = respond_to?(:studio_navbar_menu_trigger) ? studio_navbar_menu_trigger : nil %>
+      <% if menu_trigger %>
+      <%= studio_navbar_slot_tag(menu_trigger) %>
+      <% else %>
       <%= render "components/admin_dropdown" unless sidebar_active && studio_sidebar_replaces_admin_menu? %>
+      <% end %>
       <%= render "components/theme_toggle_morph" %>
     </span>
   </div>

data/app/views/studio/_alpine_scopes_guard.html.erb

@@ -1,13 +1,15 @@
 <%#
   THE X-DATA FACTORIES' GUARD: says so when a page's factories did not load.
 
-  The photo crop, the upload hosts, the birthday card and row and the profile
-  form bind an x-data factory by name (cropPhotoModal, imageUploadHost,
-  avatarCropperHost, birthdayModal, studioBirthdayFields, studioProfileForm),
-  and all six are published by studio/alpine_scopes from four modules
-  (studio/cropper, studio/image_upload, studio/birthday, studio/profile_form).
+  The photo crop, the upload hosts, the birthday card and row, the profile
+  form, the error card's countdown and the newsletter cards bind an x-data
+  factory by name (cropPhotoModal, imageUploadHost, avatarCropperHost,
+  birthdayModal, studioBirthdayFields, studioProfileForm, studioModalCountdown,
+  studioNewsletterModal), and all eight are published by studio/alpine_scopes
+  from six modules (studio/cropper, studio/image_upload, studio/birthday,
+  studio/profile_form, studio/modal_countdown, studio/newsletter_modal).
   A browser keeps a failed module request for the life of the document, so one
-  failure among the five at page load leaves every name undefined until a
+  failure among the seven at page load leaves every name undefined until a
   reload: the profile page with no Save, the birthday card with nothing to
   press. This script is what speaks then, so it is INLINE and imports nothing:
   it shares no request with the modules whose failure it reports.
@@ -46,7 +48,7 @@
   (function () {
     if (window.studioScopesGuard) return;
 
-    var NAMES = ["cropPhotoModal", "imageUploadHost", "avatarCropperHost", "birthdayModal", "studioBirthdayFields", "studioProfileForm"];
+    var NAMES = ["cropPhotoModal", "imageUploadHost", "avatarCropperHost", "birthdayModal", "studioBirthdayFields", "studioProfileForm", "studioModalCountdown", "studioNewsletterModal"];
     var BOUND = "[x-data]";
     var FAILED = "data-studio-scope-failed";
     var FALLBACK = "data-studio-scope-fallback";

data/app/views/studio/_cropper_assets.html.erb

@@ -7,6 +7,18 @@
     page through studio/alpine_scopes; this partial loads the library alone.
 
     Pair with: the crop-photo and saving modal registrations in your modal-host
-    block (see the README and CHANGELOG), and x-data="imageUploadHost({...})". %>
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.css">
-<script defer src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"></script>
+    block (see the README and CHANGELOG), and x-data="imageUploadHost({...})".
+
+    Both tags are pinned with Subresource Integrity, so a changed file on the CDN
+    fails to load rather than running. The hashes are sha384 over the exact
+    1.6.2 files; a version bump recomputes both (openssl dgst -sha384 -binary
+    FILE | openssl base64 -A), replaces the byte-exact copies in
+    test/fixtures/files/cropperjs-<version> that the browser lane serves, and
+    runs bin/cropper-sri-live. Keep the URLs exact: consumer CSPs name the
+    script by file. %>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.css"
+      integrity="sha384-6LFfkTKLRlzFtgx8xsWyBdKGpcMMQTkv+dB7rAbugeJAu1Ym2q1Aji1cjHBG12Xh"
+      crossorigin="anonymous">
+<script defer src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"
+        integrity="sha384-jrOgQzBlDeUNdmQn3rUt/PZD+pdcRBdWd/HWRqRo+n2OR2QtGyjSaJC0GiCeH+ir"
+        crossorigin="anonymous"></script>

data/app/views/studio/modals/blocks/_birthday.html.erb

@@ -58,6 +58,12 @@
     demo_underage (Boolean, optional) — style-guide preview ONLY: make the local
                 resolve take the REFUSED branch, so the guide can show the
                 handoff without a backend. Ignored unless demo.
+    progress_pill (Hash, optional) — { current: Integer, total: Integer } for a
+                card that is one step of a chain (turf-monster's onboarding runs
+                it at 2 of 3). Renders blocks/_progress_pill FIRST inside the
+                card's root, above the title row, where the chain's other steps
+                put theirs. Absent (the default), the card renders exactly as it
+                did before the local existed. Any other key raises.
 
   The scope, birthdayModal(), is studio/birthday, published on every page by
   studio/alpine_scopes. Single root element (modal-host template mount rule).
@@ -90,8 +96,20 @@
   demo        = local_assigns.fetch(:demo, false)
   demo_underage     = local_assigns.fetch(:demo_underage, false)
   age_gate_modal_id = local_assigns.fetch(:age_gate_modal_id, "age-gate")
+  # A Hash or nothing, and only the two keys blocks/_progress_pill reads: a typo
+  # (`totl:`) would otherwise fall back to the pill's default total and draw a
+  # chain of the wrong length with no error anywhere.
+  progress_pill     = local_assigns[:progress_pill]
+  unless progress_pill.nil?
+    unless progress_pill.is_a?(Hash) && progress_pill.key?(:current) && (progress_pill.keys - %i[current total]).empty?
+      raise ArgumentError, "blocks/_birthday progress_pill: takes { current:, total: }, got #{progress_pill.inspect}"
+    end
+  end
 %>
 <div x-data="birthdayModal({ minAge: <%= min_age.to_i %>, state: '<%= j state %>', url: '<%= j submit_url %>', store: '<%= j modal_store %>', demo: <%= demo ? 'true' : 'false' %>, demoUnderage: <%= demo_underage ? 'true' : 'false' %>, gateId: '<%= j age_gate_modal_id.to_s %>' })">
+  <% if progress_pill %>
+  <%= render "studio/modals/blocks/progress_pill", **progress_pill %>
+  <% end %>
   <%= render layout: "studio/modals/blocks/shell", locals: { title: title, modal_store: modal_store } do %>
     <%# The age line only exists when the app HAS a bar. A card that says
         "You must be 0+" is what an unconditional line produces for a host that