studio-engine 0.113.0.rc1 → 0.114.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fdd2e298951ce853f0cccdf203c26d3e060c7de30c3541d4fb07bb00310e167
-  data.tar.gz: 1fecbb7d380d3d80c000d08b54a70b8407962ef0495cb7d41b5579f8a390673d
+  metadata.gz: 3d6bcb337ac80f3ecf247855862249c6617607ea9dad81b6a2b53e1c907f0d56
+  data.tar.gz: 7ab19381f21ddd51bc0c240f9363843132ff073a9742648af7e4d2336ec34d08
 SHA512:
-  metadata.gz: 6c7e8e894beb7fd5bdcfd73a83e459a244fa7f2e858923382f9ba378e64b764e9c9f1adb7e22a633e22a7fb937d98990ce8056a1f69d6265a911684e71229b31
-  data.tar.gz: 1bc3712f6953dbb9ca9d3c2ce6bb4713a1c9ed99897864d5f6381c9b5e87edf15e8c4fb591864af48ccb02af45b80c39e0843a0da00528c8b13ff268033ce7a0
+  metadata.gz: 1cb4414413efb70d843277c2138c3a904055ef6a4277d200aba2a271f82b5447af9e5b74496a96d0f6d6113795b98977a9d2c80f3cb213e150d027b881094a40
+  data.tar.gz: 859f20f74d5d6a316a0f9bf3b116d810f2b3e25ed026532e271eaab248078ce094f5bd3fb15d85410bfea5993c8997410736cdd69f2ffdf3d88788f328f3299c

data/CHANGELOG.md

@@ -4,6 +4,122 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.114.0 — 2026-10-25
+
+### Added
+
+- **The modal blocks carry what a consumer kept its own copies for.** Every new
+  local is optional, and unset each block renders byte for byte as in 0.113.0
+  (`test/views/modal_blocks_baseline_test.rb` holds the touched blocks to
+  goldens rendered by the released 0.113.0 gem). Measured against turf-monster's
+  kept modals (its `test/views/engine_modal_readoption_gaps_test.rb`):
+  - `studio/profiles/_newsletter_modals` takes `modal_store:` (default
+    `"profileModals"`) and `submit_mode: :json`, which posts JSON to the host's
+    `subscribe_url:` / `unsubscribe_url:` (`unsubscribe_method:`, default
+    `DELETE`) through `studio/newsletter_modal` with a spinner and an inline
+    error line, dispatches `changed_event:` (default
+    `studio:newsletter-changed`) with `{ subscribed, email, response }`, calls an
+    opener's `props.onSuccess`, and steps to the next card with no reload. An
+    opener's `props.onSubmit` takes the address instead and nothing is posted.
+    Three optional cards: `subscribe_card:` (a consent box), `success_card:`
+    (a host slot, `partial:` and `locals:`) and `goodbye_card:`; every card,
+    the two existing ones included, takes host copy and an `id:`.
+  - `blocks/_birthday` takes `progress_pill: { current:, total: }`, drawn first
+    inside the card.
+  - `blocks/_error_card` takes `countdown_key:` (an Alpine expression for the
+    seconds, a 429's Retry-After), `countdown_text:` and `auto_close:` (default
+    true), counted by `studio/modal_countdown`; and `cta_close:`,
+    `secondary_close:` and `modal_store:` for buttons that close the store.
+  - `blocks/_success_card` takes `cta_close:`, `secondary_close:`,
+    `modal_store:`, and `slot_position: :message`, which puts the block in the
+    message's place.
+  - `blocks/_change_username` takes `locked: { title:, subtitle:, cta_label:,
+    cta_href:, dismiss: }`, a card that says why the rename is not open yet.
+
+  The two factories, `studioModalCountdown` and `studioNewsletterModal`, are
+  published by `studio/alpine_scopes` and named in its guard. Every
+  `modal_store:` is validated as a JS identifier. The newsletter cards' JSON
+  mode uses the motion layer's `.spinner`.
+- **The engine navbar carries what a forking consumer needed.** Measured
+  against Turf Monster's forks of `layouts/_navbar`, `components/_user_nav` and
+  `components/_sidebar_panel`. Every setting is opt-in, and unset the navbar,
+  user nav and sidebar panel render byte-identical to 0.113.0, signed in and
+  out, live and preview. README, *Signed-out call to action* through *Brand,
+  root hook and layer tier*.
+  - `layouts/_navbar` forwards the user nav's slot locals (`balance_slot`,
+    `extra_icons_slot`, `div2_slot`, `div2_html`).
+  - `Studio.navbar_header_bars`: partials rendered inside the pinned header,
+    above its row, in `[data-nav-header-bars]`, so a control bar (an
+    impersonation escape) never scrolls away; `engine.css` (*THE IN-HEADER
+    BARS*) holds them on the scroll timeline. Never on a preview.
+  - `Studio.navbar_signed_out_cta` takes `modal:` (an id, or an id and JSON
+    props; the engine builds the `$store.modals.open` expression, and `path:`
+    is the fallback `href`), `sign_in_link: false` (no second sign-in link),
+    and `sign_in_path:`.
+  - `Studio.navbar_account_sidebar`: the account control becomes a button that
+    toggles a host store flag, `aria-controls` naming its panels.
+    `Studio.navbar_menu_trigger`: a host partial in the admin dropdown's seat,
+    in the icon rail and the phone row.
+  - `Studio.navbar_phone_name`: the name shows below `md`, capped, and fades
+    when it overflows, in CSS only (`engine.css`, *THE PHONE NAME*).
+  - `Studio.navbar_brand` (logo, size, alt, split title words),
+    `Studio.navbar_root_hook` (`data-navbar-root`) and `Studio.navbar_z_tier`
+    (the live header at `z-[var(--z-nav)]` in place of `z-50`).
+  - `components/_sidebar_panel` takes `title_html` (a lead slot in the title's
+    place that never names the panel) and `close_hook: true`
+    (`data-sidebar-panel-close="<id>"` on the close button).
+  - Bad static config raises at assignment (`InvalidConfig` or
+    `ArgumentError`); a raising callable falls back to the default and is
+    reported once.
+
+- **`studio/profiles/_newsletter_modals` takes `fetcher:`, the host's own
+  request wrapper, in `submit_mode: :json`.** It names an export of the
+  importmap module `studio/host_fetchers`, which the engine pins to an empty
+  module and a host pins to a file of its own (Turf Monster:
+  `export { authedFetch } from "solana_utils"`, so a 401 opens sign-in and a
+  429 the rate-limit card). It is the standard's sanctioned seam: a host pin
+  of an engine name wins, and a `window.*` global is forbidden as an API
+  between files. Validated as a JS identifier and refused under `:form`. A
+  fetcher that returns null has answered the request itself; a name the module
+  does not export fails the press with the plain line and one console error,
+  and never falls back to plain fetch. Unset, the cards send plain fetch, as
+  before.
+
+### Fixed
+
+- **The README warns of three navbar adoption traps** (pinned by
+  `test/docs/navbar_readme_warnings_test.rb`): `navbar_menu_trigger` renders
+  its partial twice, in the rail and the phone row, so it carries no ids; a
+  `navbar_header_bars` callable that raises drops every bar for that render
+  (reported once), so one that carries an OPSEC control (Turf Monster's
+  impersonation bar, OPSEC-046) must not raise; and `navbar_brand`'s word
+  classes live in the host's initializer, which the host's Tailwind scan must
+  include.
+- **`Studio.navbar_account_sidebar` refuses `controls:` that name the engine's
+  link sidebar** (`studio-link-sidebar`, `studio-link-sidebar-mobile`) with
+  `InvalidConfig` at assignment, and a callable's answer when it resolves.
+  `studio/link_sidebar` claims any trigger whose `aria-controls` names that
+  panel, so the account button would have opened the engine's link sidebar
+  instead of the host's.
+- **`Studio.navbar_signed_out_cta` with `modal:` marks its button
+  `aria-haspopup="dialog"`,** so a screen reader announces the dialog before
+  the press. A CTA without `modal:` renders as before.
+- **`Studio.navbar_phone_name` ends a long name in an ellipsis where scroll
+  timelines are unsupported.** The `text-overflow: clip` that makes room for
+  the fade now sits inside the `@supports (animation-timeline: scroll())`
+  block with the fade, so Firefox, which has no fade, keeps `truncate`'s
+  ellipsis instead of cutting the name mid-letter.
+- **`studio/cropper_assets` pins Cropper.js with Subresource Integrity.** The
+  cdnjs `cropper.min.css` and `cropper.min.js` (1.6.2) tags now carry sha384
+  `integrity` and `crossorigin="anonymous"`, so a changed file on the CDN fails
+  to load instead of running on the page. The URLs are unchanged, so a CSP that
+  names the script by file (Turf Monster's) keeps matching. The hashes were
+  computed over the fetched files and their bytes checked against cdnjs's
+  published SRI. Byte-exact copies live in `test/fixtures/files/cropperjs-1.6.2`:
+  the suite hashes them offline, and the browser lane serves them for the two
+  cdnjs URLs so the tags load as shipped. `bin/cropper-sri-live` re-checks the
+  pins against the live CDN.
+
 ## 0.113.0 — 2026-10-24
 
 ### Added

data/README.md

@@ -765,6 +765,51 @@ end
   and is reported once per process per error class, never a 500.
 - A host on an older engine can set it safely with
   `Studio.navbar_signed_out_cta = … if Studio.respond_to?(:navbar_signed_out_cta=)`.
+- Three optional keys; absent, the CTA renders as before:
+  - `modal:` `"auth"`, or `{ id: "auth", props: { step: "credentials" } }`. The
+    button opens that modal on the engine's modal host
+    (`$store.modals.open(id, props)`), and `path:` stays its `href`, the
+    fallback with no script or no modal host. The engine builds the expression
+    from this data: the id must be a plain name and the props JSON, so no host
+    JavaScript reaches the page as a string. The button carries
+    `data-nav-cta-modal="<id>"` and `aria-haspopup="dialog"`.
+  - `sign_in_link: false` drops the quiet sign-in link in both rows, for an app
+    whose CTA is its sign-in (one Sign in, not two).
+  - `sign_in_path:` points the quiet sign-in link somewhere other than
+    `login_path`.
+
+```ruby
+config.navbar_signed_out_cta = { label: "Sign in", path: "/signin", sign_in_link: false,
+                                 modal: { id: "auth", props: { step: "credentials", mode: "signup" } } }
+```
+
+### Header bars — `Studio.navbar_header_bars`
+
+Partials the navbar renders INSIDE its pinned header, above the row, so they
+never scroll away: a control an admin must not lose, such as an impersonation
+bar's JS-free "Return to <admin>" button. An ambient label (the environment
+bar) belongs in the bar stack above the header, which scrolls. Empty (`[]`, the
+default), the navbar renders as before. Rules: `lib/studio/navbar_slots.rb`.
+
+```ruby
+config.navbar_header_bars = ->(view) { view.impersonating? ? ["shared/impersonation_banner"] : [] }
+```
+
+- They render in `[data-nav-header-bars]`, the header's first child, signed in
+  and out, never on a preview.
+- The cost of being in the header: it is a stacking context, so these bars do
+  not rise over an open modal the way the bar stack does.
+- On the scroll timeline `engine.css` (*THE IN-HEADER BARS*) carries them down
+  by the band, so they hold at the top of the window while the compact bar
+  sticks under them.
+- Validation and the raising-callable fallback are `navbar_items`'s.
+- **A callable that raises, the navbar renders no header bars** for that render
+  (all of them, not just the one that failed), and the error is reported once
+  per process per error class. A bar that carries an OPSEC control (Turf
+  Monster's impersonation bar and its "Return to <admin>" button, OPSEC-046)
+  would vanish without a trace on the page, so the callable must not raise:
+  guard each lookup it makes (`view.impersonating?` on a page whose controller
+  lacks the helper, say) and answer `[]` for none.
 
 ### Navbar items — `Studio.navbar_items`
 
@@ -842,6 +887,100 @@ The legacy string locals (`balance_html`, `extra_icons_html`, `div2_html` —
 pre-rendered HTML injected via `raw`) are deprecated but still honored when the
 matching slot is absent, so existing call sites render unchanged.
 
+`layouts/_navbar` takes the same four (`balance_slot`, `extra_icons_slot`,
+`div2_slot`, `div2_html`) and forwards them, so an app rendering the engine
+navbar fills these seats without forking either partial:
+
+```erb
+<%= render "layouts/navbar", div2_slot: { partial: "components/seeds_bar", locals: { compact: true } } %>
+```
+
+A `balance_slot` reserves the balance column as `balance_html` does, and the
+link sidebar's trigger still follows an `extra_icons_slot`.
+
+### Menu trigger and account sidebar — `Studio.navbar_menu_trigger`, `Studio.navbar_account_sidebar`
+
+For an app whose menu is its own sidebar (Turf Monster's gear sidebar), not
+the admin dropdown or the engine's link sidebar. Both `nil` by default, which
+renders as before.
+
+```ruby
+config.navbar_menu_trigger = "components/gear_sidebar_trigger"
+config.navbar_account_sidebar = { flag: "gearOpen", controls: %w[gear-sidebar gear-sidebar-mobile] }
+```
+
+- `navbar_menu_trigger` is one partial spec (or a callable) rendered in the
+  admin dropdown's seat: the icon rail from `md` (in
+  `[data-nav-menu-trigger]`), and the phone row. Rules:
+  `lib/studio/navbar_slots.rb`. **It renders the partial twice**, once in each
+  seat, and both are in the page at every width, so the partial carries no
+  `id` (nor anything keyed to one, such as a `<label for>`): a second copy of
+  an id is invalid, and `getElementById` and `aria-controls` find only the
+  first. Point at the panel by its own id from the trigger, never the reverse.
+- `navbar_account_sidebar` makes the account control a button that toggles
+  `$store.<store>.<flag>` (`store:` defaults to `"sidebars"`), with
+  `aria-controls` naming the panels, `aria-haspopup="dialog"` and a bound
+  `aria-expanded`. It wins over the link sidebar and the account link. The
+  engine builds the toggle from the names, which must be plain identifiers. It
+  carries `data-profile-image-toggle`, so a host handler that claims its
+  triggers in the capture phase, before Alpine binds, claims it too. Its
+  `controls:` may not name the engine's own link sidebar
+  (`studio-link-sidebar`, `studio-link-sidebar-mobile`): `studio/link_sidebar`
+  claims a click on any trigger whose `aria-controls` names it, so the button
+  would open the engine's panel instead of the host's. That is refused with
+  `InvalidConfig` at assignment (a callable's answer, when it resolves). Rules:
+  `lib/studio/navbar_account_sidebar.rb`.
+
+### Sidebar panel lead and close hook
+
+`components/_sidebar_panel` takes two opt-in locals; unset, the panel renders
+as before:
+
+- `title_html:` HTML in the title's place, for a panel whose header leads with
+  a live status line. It is content, not a name: it never feeds
+  `aria-labelledby` or `aria-label`, so a caller that passes it instead of
+  `title:` passes `aria_label:`. `title:` wins when both are passed.
+- `close_hook: true` (with an `id:`) adds `data-sidebar-panel-close="<id>"` to
+  the close button, beside `data-link-sidebar-close`. The contract is the
+  host's: its own document handler matches the button to its panel by id
+  (Turf Monster's gear sidebar does). `studio/link_sidebar` reads only
+  `data-link-sidebar-close`, and only inside its own panels.
+
+### Phone name — `Studio.navbar_phone_name`
+
+`true` shows the signed-in name beside the avatar below `md` too, capped at
+4.5rem (6rem from 400px), and fades it out over its right half when it does not
+fit. The fade is CSS only (`engine.css`, *THE PHONE NAME*): it runs on the
+name's own scroll timeline, which is inactive while the name fits, so a short
+name never fades. A browser without scroll timelines (Firefox today) ends a long
+name in an ellipsis instead. `false`, the default, keeps the name
+screen-reader text below `md`.
+
+### Brand, root hook and layer tier — `Studio.navbar_brand`, `Studio.navbar_root_hook`, `Studio.navbar_z_tier`
+
+```ruby
+config.navbar_brand = { logo: "/icon-192.png", logo_size: 48, alt: "Turf Monster",
+                        words: [{ text: "Turf" }, { text: "Monster", class: "tm-wordmark" }] }
+config.navbar_root_hook = true   # data-navbar-root on the header, live and preview
+config.navbar_z_tier = true      # the live header at z-[var(--z-nav)], not z-50
+```
+
+- `navbar_brand`: every key optional. `logo:` replaces the "Navbar Logo" theme
+  image, `logo_size:` adds `width` and `height`, `alt:` replaces `app_name` as
+  its alt, and `words:` replaces the `app_name` split: each word its own
+  truncating span with the host's class and nothing else. `navbar_wordmark`
+  wins when both are set. Rules: `lib/studio/navbar_brand.rb`.
+- **The word classes live in the host's initializer**
+  (`config/initializers/studio.rb`), which a host's Tailwind scan does not
+  read by default (Turf Monster's `content:` lists `app/views`,
+  `app/helpers`, `app/javascript` and the engine's views). A utility named
+  only there, `text-heading` say, compiles only if some view also uses it.
+  Add the initializer to the scan (`content:`, or `@source` under Tailwind 4),
+  or give the word a class the host's CSS defines (`tm-wordmark`). The same
+  rule as the engine's views glob:
+  [NEW_APP_SETUP.md, section 14](docs/NEW_APP_SETUP.md#14-css-component-classes).
+- `navbar_root_hook` and `navbar_z_tier` are booleans, `false` by default.
+
 ### The account row
 
 From 768px the user nav's right end reads theme toggle, gear, name, avatar,

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

@@ -883,6 +883,58 @@ body.modal-open .studio-app-banner {
     }
   }
 }
+/* THE PHONE NAME (Studio.navbar_phone_name, components/_user_nav). Below 768px
+   the signed-in name shows beside the avatar in a capped box. A name that
+   fits draws whole; one that does not fades out over its right half instead
+   of ending in an ellipsis. The fade needs no script: the name's box clips
+   (truncate), which makes it a scroll container, and a scroll timeline on a
+   container with nothing to scroll is inactive, so the animation, and its
+   mask, applies only while the name overflows. The clip that drops the
+   ellipsis lives inside the same check: a browser without scroll timelines
+   has no fade, so it keeps truncate's ellipsis rather than cutting the name
+   mid-letter. From 768px the name truncates as before. */
+@media (max-width: 767px) {
+  @supports (animation-timeline: scroll()) {
+    [data-nav-name-phone] > [data-nav-name] {
+      text-overflow: clip;
+      animation: nav-name-fade linear both;
+      animation-timeline: scroll(self inline);
+    }
+  }
+}
+@keyframes nav-name-fade {
+  from, to {
+    -webkit-mask-image: linear-gradient(to right, black 50%, transparent);
+    mask-image: linear-gradient(to right, black 50%, transparent);
+  }
+}
+
+/* THE IN-HEADER BARS ON THE SCROLL TIMELINE (Studio.navbar_header_bars, which
+   layouts/_navbar renders in [data-nav-header-bars] at the top of the header).
+   On the timeline the header sticks at minus its band, so its TOP band leaves
+   the window, and these bars sit at its top. So they move down by the band
+   over the range the band scrolls away in, on the same linear timeline: the
+   header rises by exactly as much as they fall, and they hold still at the top
+   of the window. The band needs no correction (the controller measures it as
+   expanded less collapsed height, and the bars are in both readings), nor
+   does the row (it slides down half the band, which centres it on what is left
+   below the bars). Same conditions as the collapse above. Lifted from Turf
+   Monster's fork of the navbar, where it was measured. */
+@layer utilities {
+  @supports (animation-timeline: scroll()) {
+    @media (min-width: 768px) {
+      .nav-shell[data-nav-timeline] > [data-nav-header-bars] {
+        position: relative;
+        z-index: 1;
+        animation: nav-tl-header-bars linear both;
+        animation-timeline: scroll(root block);
+        animation-range: var(--nav-start, 0px) calc(var(--nav-start, 0px) + var(--nav-band));
+      }
+    }
+  }
+}
+@keyframes nav-tl-header-bars { to { transform: translateY(var(--nav-band)); } }
+
 /* THE PINNED EDGE ON THE SCROLL TIMELINE (studio/pinned_stack).
    On a timeline header the pinned stack publishes where the stack sits once it
    has PINNED (the compact bar), and writes nothing per scroll frame. A sticky

data/app/helpers/studio_navbar_helper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# The navbar's view seams: links, items, the avatar badge and the signed-out
-# CTA. Each resolves once per render pass, since a host lambda may read
+# The navbar's view seams: links, items, the avatar badge, the header bars,
+# the menu trigger, the account sidebar and the signed-out CTA. Each resolves once per render pass, since a 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"
@@ -21,6 +21,22 @@ module StudioNavbarHelper
     @studio_navbar_signed_out_cta = Studio.navbar_signed_out_cta_for(self)
   end
 
+  # The signed-out CTA's modal opener, as link_to options: {} when the CTA
+  # names no modal, so the button renders as before. The expression is built
+  # here from validated data (a plain id and JSON props), never taken from the
+  # host as a string. It opens the modal only where the engine's modal host
+  # has registered $store.modals, and only then cancels the link, so the href
+  # is the fallback without script or without a host. aria-haspopup="dialog"
+  # tells a screen reader, before the press, that the link opens a dialog.
+  def studio_navbar_cta_modal_options(cta)
+    modal = cta && cta[:modal]
+    return {} unless modal
+
+    open = "$store.modals.open(#{modal[:id].to_json}, #{modal[:props].to_json})"
+    { "data-nav-cta-modal": modal[:id], "aria-haspopup": "dialog",
+      "@click": "$store.modals && ($event.preventDefault(), #{open})" }
+  end
+
   # Studio.navbar_items as partial specs ({ partial:, locals: }), [] for none.
   # Resolved once per render pass: the desktop bar and the phone row both ask.
   def studio_navbar_items
@@ -34,6 +50,35 @@ module StudioNavbarHelper
     @studio_navbar_avatar_badge = Studio.navbar_avatar_badge_for(self)
   end
 
+  # Studio.navbar_header_bars as partial specs, [] for none.
+  def studio_navbar_header_bars
+    @studio_navbar_header_bars ||= Studio.navbar_header_bars_for(self)
+  end
+
+  # Studio.navbar_menu_trigger as one partial spec, or nil for the admin
+  # dropdown. Resolved once per render pass: the rail and the phone row both ask.
+  def studio_navbar_menu_trigger
+    return @studio_navbar_menu_trigger if defined?(@studio_navbar_menu_trigger)
+
+    @studio_navbar_menu_trigger = Studio.navbar_menu_trigger_for(self)
+  end
+
+  # Studio.navbar_account_sidebar as { store:, flag:, controls: }, or nil.
+  def studio_navbar_account_sidebar
+    return @studio_navbar_account_sidebar if defined?(@studio_navbar_account_sidebar)
+
+    @studio_navbar_account_sidebar = Studio.navbar_account_sidebar_for(self)
+  end
+
+  # The account control's toggle and aria-expanded expressions for a resolved
+  # account sidebar, built from its validated names. The toggle is guarded, so
+  # a page without the store does nothing rather than throw.
+  def studio_navbar_account_sidebar_expressions(sidebar)
+    ref = "$store.#{sidebar[:store]}"
+    { toggle: "#{ref} && (#{ref}.#{sidebar[:flag]} = !#{ref}.#{sidebar[:flag]})",
+      expanded: "#{ref} && #{ref}.#{sidebar[:flag]} ? 'true' : 'false'" }
+  end
+
   # One resolved partial spec, rendered through the normal partial pipeline.
   def studio_navbar_slot_tag(spec)
     render partial: spec[:partial], locals: spec[:locals]

data/app/javascript/studio/alpine_scopes.js

@@ -7,13 +7,15 @@
 //   x-data="birthdayModal({ minAge, url })"          studio/birthday
 //   x-data="studioBirthdayFields('1991-01-31')"      studio/birthday
 //   x-data="studioProfileForm({ first_name: 'Pat' })" studio/profile_form
+//   x-data="studioModalCountdown({ seconds: 12 })"   studio/modal_countdown
+//   x-data="studioNewsletterModal({ url: '/n' })"    studio/newsletter_modal
 //   submitFormWithProgress(form, opts)               studio/image_upload
 //
 // WHY THESE ARRIVE WITH THE PAGE AND ARE NOT LAZY. Alpine evaluates an x-data
 // expression when it meets the element: at start for a page's own markup, at
 // mount for a modal card. A factory that is not defined by then leaves its
-// element dead, and the element here is a photo upload, the birthday gate or
-// the profile form. A dynamic import cannot promise to have resolved, and one
+// element dead, and the element here is a photo upload, the birthday gate,
+// the profile form, a rate-limit card's countdown or a newsletter card. A dynamic import cannot promise to have resolved, and one
 // that fails is final for the document (studio/lazy_controllers). So the
 // factories are imported statically and preloaded on every page.
 //
@@ -37,6 +39,8 @@ import { cropPhotoModal } from "studio/cropper"
 import { imageUploadHost, avatarCropperHost, submitFormWithProgress } from "studio/image_upload"
 import { birthdayModal, studioBirthdayFields } from "studio/birthday"
 import { studioProfileForm } from "studio/profile_form"
+import { studioModalCountdown } from "studio/modal_countdown"
+import { studioNewsletterModal } from "studio/newsletter_modal"
 
 // name -> the factory Alpine calls. Alpine passes the expression's own
 // arguments and nothing else.
@@ -46,7 +50,9 @@ export const SCOPES = {
   avatarCropperHost: () => avatarCropperHost(),
   birthdayModal: (opts) => birthdayModal(opts),
   studioBirthdayFields: (initial) => studioBirthdayFields(initial),
-  studioProfileForm: (initial) => studioProfileForm(initial)
+  studioProfileForm: (initial) => studioProfileForm(initial),
+  studioModalCountdown: (opts) => studioModalCountdown(opts),
+  studioNewsletterModal: (opts) => studioNewsletterModal(opts)
 }
 
 // Plain functions a page calls by name.

data/app/javascript/studio/host_fetchers.js

@@ -0,0 +1,16 @@
+// studio/host_fetchers: the seam a host fills with its own request wrappers.
+//
+// The engine pins this name to this empty module. A host that sends its
+// requests through a wrapper of its own (Turf Monster's authedFetch) pins the
+// same name to a file of its own, which wins because the host's importmap is
+// drawn last, and exports the wrapper by name:
+//
+//   # config/importmap.rb
+//   pin "studio/host_fetchers", to: "newsletter_fetchers.js"
+//   // app/javascript/newsletter_fetchers.js
+//   export { authedFetch } from "solana_utils"
+//
+// A partial that takes a fetcher: local (studio/profiles/_newsletter_modals)
+// names one of those exports; studio/newsletter_modal imports this module on
+// the first press that needs it. Nothing here is on the boot graph.
+export {}

data/app/javascript/studio/modal_countdown.js

@@ -0,0 +1,95 @@
+// studio/modal_countdown: a modal card that counts down and closes itself.
+//
+//   x-data="studioModalCountdown({ seconds: $store.modals.current().props.secondsLeft, store: 'modals', autoClose: true })"
+//       blocks/_error_card with countdown_key: the "give it a sec" wait after
+//       a 429, seeded from the response's Retry-After. The card shows
+//       waitLabel and, at zero, closes the store it is mounted in.
+//
+// The seconds are read ONCE, at mount, from whatever expression the host named:
+// the card counts its own copy down and never writes back to the modal's props.
+// No seconds, or none above zero, is no countdown: nothing ticks and nothing
+// closes, so a card opened without a Retry-After stays until it is dismissed.
+//
+// studio/alpine_scopes publishes the factory on window, statically: Alpine
+// evaluates the x-data as the modal host mounts the card, and a factory that is
+// not defined by then leaves the card dead. It imports nothing;
+// test/javascript/modal_countdown.test.mjs loads it as a data: module.
+
+// Above this many seconds the wait reads in minutes ("3 min"), below it in
+// seconds ("45s"): a rate limit of several minutes counted in seconds reads as
+// a clock, not a wait.
+export const MINUTES_FROM = 90
+
+// A host value as whole seconds to wait: a Retry-After of "12", 12 or 11.2 all
+// wait 12. Anything that is not a positive number is 0, no wait.
+export function startSeconds(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.ceil(n) : 0
+}
+
+// The wait as a person reads it.
+export function waitLabel(seconds) {
+  const s = Math.max(0, Math.floor(Number(seconds) || 0))
+  return s > MINUTES_FROM ? Math.ceil(s / 60) + " min" : s + "s"
+}
+
+// x-data for a counting card.
+//
+// opts:
+//   seconds    the wait, read once at mount (see startSeconds).
+//   store      the Alpine store the card is mounted in (default "modals").
+//   autoClose  close that store at zero (default true).
+//
+// env: { win, setInterval, clearInterval } for the tests.
+export function studioModalCountdown(opts, env) {
+  opts = opts || {}
+  const win = (env && env.win) || (typeof window !== "undefined" ? window : {})
+  const every = (env && env.setInterval) || ((fn, ms) => setInterval(fn, ms))
+  const stopEvery = (env && env.clearInterval) || ((id) => clearInterval(id))
+
+  return {
+    remaining: startSeconds(opts.seconds),
+    store: opts.store || "modals",
+    autoClose: opts.autoClose !== false,
+    _timer: null,
+
+    get counting() {
+      return this.remaining > 0
+    },
+    get waitLabel() {
+      return waitLabel(this.remaining)
+    },
+
+    init() {
+      this._stop()
+      if (this.remaining <= 0) return
+      this._timer = every(() => this.tick(), 1000)
+    },
+
+    tick() {
+      if (this.remaining <= 0) return this._stop()
+      this.remaining -= 1
+      if (this.remaining > 0) return
+      this.remaining = 0
+      this._stop()
+      if (this.autoClose) this._close()
+    },
+
+    // The card may already be gone (a person dismissed it in the last second),
+    // so a store with nothing open, or no such store, is not an error.
+    _close() {
+      try { win.Alpine.store(this.store).close() } catch (_) {}
+    },
+
+    _stop() {
+      if (this._timer !== null) stopEvery(this._timer)
+      this._timer = null
+    },
+
+    // Alpine calls destroy() when the host unmounts the card, so a card closed
+    // by hand leaves no interval behind it.
+    destroy() {
+      this._stop()
+    }
+  }
+}