studio-engine 0.107.0 → 0.108.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2df600bffd7dc544c53e67f5c2d53eaa750f9f8dde61faa148bf1734b0e3bc80
-  data.tar.gz: 0d188944db2d33faba21c2d0c14489a929795f4c4f7f4864e6e7e2dfa18e6ca8
+  metadata.gz: 2990527dd511a02eea248d9a8ceb2e5f2df97b2b19423f3022b864ea162e38b0
+  data.tar.gz: 24d9da854c8773924858c46fe3bcf31e81ecf4b2e5a1c40b629e16067ad661ac
 SHA512:
-  metadata.gz: 82cc2318817c6fcddfab389e3da1135c9f8aa0b4eb6d3adfd4949bb2c4949c9263fb4a8595eb74b90815dc004ef143caa5d452b106d6f4547d736bcd9ecba9bd
-  data.tar.gz: 4c3deddf0ef3e644051bd48b06dfc9ed0798b31af6d51b65fe43a8a4bde1d57be8eac2d359421d17e58176d2e1496b6728f5f5d7b5867656f71bb478945bed78
+  metadata.gz: 847d51a58aafc2e75e1d7621cdb674b4dda4c6d54b30676a95803fe5980ad5630392ead197848afe25255b8176cc7754b34c6971a1a27c5fc0f9a162c898c6f6
+  data.tar.gz: fc2bfa04fe01978a9b60ad854553cf89c6d1cb250ebe9ff0c5b75c9b09b49b02ba3a0203e069b32e774763d6505400f4a8a5c5c5574479a39f353e3606451557

data/CHANGELOG.md

@@ -4,6 +4,79 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+
+- **`GET /_studio/health_report`: the daily health report as JSON, for the
+  hub's central pull.** McRitchie Studio runs one 07:00 America/Denver job that
+  pulls every app's report and posts it to Discord, so a satellite needs no
+  worker or schedule of its own. Drawn by `Studio.routes` in every environment,
+  production included, and inert until the app names a token:
+  `config.health_report_token` or `STUDIO_HEALTH_TOKEN` (new). With none it
+  answers a bare 404; a request without `Authorization: Bearer <token>`
+  (compared in constant time) gets 401; `?ending=<ISO 8601>` picks the day
+  that ends there (a bad value is 400), else the day the job would report now.
+  The body is the same `Studio::HealthReport.build` the email uses, counts only
+  (`schema`, `app`, `engine_version`, `window`, `quiet`, `sections`,
+  `error_kinds`, `error_groups`): no section's names or emails ever leave the
+  app, and an email address quoted in an error message is sent as `[email]`. It runs on `ActionController::API`, so no host `before_action`,
+  session, cookie or redirect touches it. See `docs/HEALTH_REPORT.md`, *The
+  hub endpoint*.
+
+## 0.108.0 — 2026-10-15
+
+### Changed
+
+- **The navbar collapse no longer moves the page.** `studio/nav_collapse`
+  holds a header that sits in the page's flow at its expanded footprint: the
+  header carries `margin-bottom: calc(var(--nav-hold) * var(--nav-p) +
+  var(--nav-hold-fix))`, which grows in the same style recalc that shrinks it,
+  so the document never changes height. Before, every frame of the collapse
+  reflowed the page: content ran ahead of the finger, a quick scroll back to the
+  top pushed the page down for ~10 frames after the scroll stopped, and near the
+  bottom of a page the browser clamped the scroll back (measured on the hub's
+  `/links`: 344 to 305 with nobody touching it). Held, the progress follows the
+  scroll position exactly: the 5px-per-frame cap and the short-page guard apply
+  only to a header out of flow (fixed or absolute), which never moved the page.
+  The collapse stays continuous; endpoints and the ramp are unchanged. No markup
+  change: every header on the controller (the engine navbar, and forks through
+  the `navCollapse()` shim) gets it.
+- **The pinned stack stops restyling the whole page while you scroll.**
+  `studio/pinned_stack` publishes the header's live geometry as inherited
+  custom properties on `<html>`, and every write there restyles the entire
+  document: 8.7ms a write on turf-monster's 2,000-element contest page, every
+  frame the header's bottom edge moved, which dropped frames on a 120Hz screen.
+  While a scroll is in motion it now writes the values only onto the elements
+  that read them live (an inline style or a stylesheet rule that positions off
+  them, found by a scan, or `[data-pin-follow]`), and writes `<html>` once the
+  scroll has been still for 160ms. Restyling during the collapse on that page
+  fell from 226ms to 25ms over 27 frames. `scroll-margin`/`scroll-padding`
+  readers are served by the settled write; structural changes (a layer arriving
+  or leaving) still write `<html>` at once. A SCRIPT that reads these values
+  off `<html>` (`getComputedStyle(document.documentElement)`) sees them up to
+  160ms late during a scroll; read them off the element that positions by them
+  instead. Known readers: turf-monster's contest chat panel and cyvasse's game
+  controller, both of which read at an event, not per frame. Followers release
+  their copies before Turbo caches the page, and the collapse controller clears
+  its own state when a header is restored from that cache, so Back never stacks
+  a second hold.
+
+### Added
+
+- **`Studio::Storage`: object storage on Cloudflare R2, on by default for an app
+  that names its bucket.** One copy of the `StorageBackend` module the hub,
+  turf-monster and mcritchie-industries each hand-wrote. An app with
+  `config.s3_bucket_prefix` set now gets, with no initializer of its own: a boot
+  check (a retired `ACTIVE_STORAGE_BACKEND` / `STUDIO_S3_BACKEND` value raises in
+  every environment; a missing R2 variable raises in production and QA, naming
+  each), `Studio::S3` pointed at R2 when the app left `s3_endpoint` unset, and
+  Active Storage services `amazon` and `amazon_dev` on `StudioTrashS3`, merged
+  under the app's own `config/storage.yml` (an app's service of the same name
+  wins). New config: `manage_storage` (default true; false opts out) and
+  `storage_public_url_required` (default false; true makes `R2_PUBLIC_URL`
+  required). An app still carrying its own `StorageBackend` keeps its own
+  connection and services; only the switch check is new to it. README.md,
+  *Managed storage*.
+
 ## 0.107.0 — 2026-10-14
 
 ### Changed

data/README.md

@@ -148,6 +148,8 @@ Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
+In every environment, production included, it also draws `/_studio/health_report`: the daily health report as counts-only JSON, which the McRitchie Studio hub pulls at 07:00 and posts to Discord. It answers 404 until the app sets `STUDIO_HEALTH_TOKEN` (or `config.health_report_token`), and 401 to a request without that bearer token ([`docs/HEALTH_REPORT.md`](docs/HEALTH_REPORT.md#the-hub-endpoint)).
+
 ## Non-Production Banners
 
 Consumer layouts can render the shared environment banner inside their sticky
@@ -966,6 +968,49 @@ config.s3_key_prefix    = "mcritchie-industries/"
 logical keys and never see it. Unset (the default) leaves keys byte-identical to
 what every already-shipped app wrote.
 
+### Managed storage — `Studio::Storage` (on by default)
+
+Object storage is Cloudflare R2, and only R2: AWS S3 was retired on 2026-10-10.
+An app that names its bucket (`config.s3_bucket_prefix`) gets all of this from
+the engine, with no initializer of its own:
+
+- **A boot check** (`studio.storage`, after the host's initializers). Both
+  switches, `ACTIVE_STORAGE_BACKEND` and `STUDIO_S3_BACKEND`, may be unset or
+  `r2`; a retired value (`s3`, `mirror_to_r2`, `mirror_to_s3`) or any other
+  value refuses the boot in every environment. In production (QA boots
+  `RAILS_ENV=production` too) a missing `R2_ENDPOINT`, `R2_ACCESS_KEY_ID` or
+  `R2_SECRET_ACCESS_KEY` refuses the boot, naming every missing variable and the
+  1Password item `r2.<prefix>`. Elsewhere, none set boots on a placeholder
+  connection (`https://r2-not-configured.invalid`, which never resolves, and
+  placeholder keys), and some set raises: half a configuration is a mistake.
+- **`Studio::S3` on R2**: endpoint, region `auto`, keys and public URL, filled in
+  only when the app left `s3_endpoint` unset. A public URL the app set is kept.
+- **Active Storage services** `amazon` (this environment's bucket) and
+  `amazon_dev` (always the dev bucket), both `service: StudioTrashS3` on R2 with
+  `request_checksum_calculation` / `response_checksum_validation` set to
+  `when_required`. The bucket is `<prefix>-production` on real production only;
+  QA (`QA_ENV`), development, test and CI resolve `<prefix>-dev`, the same
+  resolution `Studio::S3` uses. They are merged UNDER the app's own
+  `config/storage.yml`: a service of the same name there wins, and an app with
+  no storage file still gets both.
+
+```ruby
+# config/initializers/studio.rb: the whole adoption
+config.s3_bucket_prefix = "turf-monster"
+config.storage_public_url_required = true # only an app that serves public object URLs
+```
+
+`storage_public_url_required` makes `R2_PUBLIC_URL` as required as the keys
+(a keyless process then gets the placeholder host as its public URL). Leave it
+false for an app whose objects are private and served by signed URL.
+`config.manage_storage = false` opts out entirely.
+
+For app code: `Studio::Storage.configured?` (every required variable set, so
+false on placeholders), `.remote_in_development?` (any R2 variable set),
+`.credential_hint`, `.bucket` / `.dev_bucket`, and `.connection`. Every method
+takes the environment hash and `strict:` as arguments, so each rule can be
+tested without booting.
+
 ### S3-compatible storage (Cloudflare R2)
 
 `Studio::S3` talks to any S3-compatible endpoint. The McRitchie fleet is moving
@@ -979,8 +1024,10 @@ config.s3_secret_access_key = ENV["R2_SECRET_ACCESS_KEY"]
 config.s3_public_url        = ENV["R2_PUBLIC_URL"] # custom domain on this env's bucket
 ```
 
-All four are nil by default, and nil is AWS exactly as before. The keys must be
-set as a pair. R2 serves nothing anonymously from its S3 endpoint, so with an
+All four are nil by default. For an app that names its bucket, the engine fills
+them from the R2 variables at boot ([Managed storage](#managed-storage--studiostorage-on-by-default));
+setting `s3_endpoint` yourself keeps the connection yours. With managed storage
+off, nil is AWS exactly as before. The keys must be set as a pair. R2 serves nothing anonymously from its S3 endpoint, so with an
 endpoint and no `s3_public_url`, `Studio::S3.url` raises `NotConfigured` and
 `upload` writes but returns `nil`; serve private objects with `signed_url`.
 
@@ -1120,17 +1167,25 @@ Name every `assets.<domain>` host the bucket answers on. If the bucket has the
 
 ### Adopt it in an app
 
-Active Storage: change the R2 service in `config/storage.yml` from `service: S3`
-to `service: StudioTrashS3`. Every other key stays as it is:
+Active Storage: name your bucket and the engine supplies the trash services.
+With `config.s3_bucket_prefix` set, `amazon` and `amazon_dev` are
+`service: StudioTrashS3` on R2 with no storage.yml entry of your own
+([Managed storage](#managed-storage--studiostorage-on-by-default)); select one in
+`config/environments/*.rb` as usual (`config.active_storage.service = :amazon`).
+
+A service under another name, or an app with `manage_storage = false`, names the
+service itself in `config/storage.yml`:
 
 ```yaml
-r2:
+archive:
   service: StudioTrashS3
-  bucket: my-app-production
+  bucket: my-app-archive
   endpoint: <%= ENV["R2_ENDPOINT"] %>
   region: auto
   access_key_id: <%= ENV["R2_ACCESS_KEY_ID"] %>
   secret_access_key: <%= ENV["R2_SECRET_ACCESS_KEY"] %>
+  request_checksum_calculation: when_required
+  response_checksum_validation: when_required
 ```
 
 An app with its own S3 service subclass (turf-monster's

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

@@ -518,7 +518,9 @@ body.modal-open .studio-app-banner {
          single frame on a flick — measured 39px in turf-monster, the full
          178 -> 139. navCollapse() converts this to --nav-p units off
          --nav-ramp's 3x relation to the collapse total, so one number covers
-         every band. */
+         every band. It binds only a header OUT of the page's flow: a header
+         in flow is held (studio/nav_collapse, the hold), so the page cannot
+         move, and its progress follows the scroll exactly. */
       --nav-max-step: 5px;
       --nav-pad: calc(1.5rem - 1rem * var(--nav-p, 0));                 /* py-6 -> py-2 */
       --nav-logo-size: calc(3rem - 1rem * var(--nav-p, 0));             /* 48px -> 32px */

data/app/controllers/studio/health_reports_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Studio
+  # GET /_studio/health_report — the daily health report as JSON, for the
+  # McRitchie Studio hub's one 07:00 America/Denver job, which pulls every app
+  # and posts to Discord. Drawn in every environment, production included; the
+  # report is the same Studio::HealthReport.build the email uses, so the two can
+  # never disagree. docs/HEALTH_REPORT.md, "The hub endpoint".
+  #
+  # INERT BY DEFAULT. With no Studio.health_report_token (else
+  # ENV["STUDIO_HEALTH_TOKEN"]) it answers a bare 404, the same as a route that
+  # is not there. With one, a request without `Authorization: Bearer <token>`
+  # gets 401; the compare is constant-time (Studio::HealthReport.authorized?).
+  #
+  # COUNTS ONLY. Studio::HealthReport.payload drops every section's `items`, so
+  # no signup's or contact's name or email ever leaves the app.
+  #
+  # ActionController::API, NOT the host's ApplicationController: a server-to-
+  # server fetch carries no session, and a host's before_actions (sign-in, geo,
+  # allow_browser, onboarding) would answer it with a redirect or an HTML page.
+  # This base runs none of them, keeps no session, sets no cookie and checks no
+  # CSRF token, and every answer here is JSON or a bare status.
+  class HealthReportsController < ActionController::API
+    def show
+      return head(:not_found) if Studio.health_report_token.blank?
+
+      response.headers["Cache-Control"] = "no-store"
+      unless Studio::HealthReport.authorized?(request.authorization)
+        response.headers["WWW-Authenticate"] = 'Bearer realm="studio-health-report"'
+        return render(json: { error: "unauthorized" }, status: :unauthorized)
+      end
+
+      window = begin
+        Studio::HealthReport.window_for(params[:ending].presence)
+      rescue ArgumentError
+        return render(json: { error: "ending must be an ISO 8601 time" }, status: :bad_request)
+      end
+
+      render json: Studio::HealthReport.payload(Studio::HealthReport.build(window: window))
+    rescue StandardError => e
+      # build already turns a failing SOURCE into a section's `failure`; this is
+      # anything else. Logged as an ErrorLog row, answered as JSON, never HTML.
+      Studio::HealthReport.capture(e)
+      render json: { error: "health report failed" }, status: :internal_server_error
+    end
+  end
+end

data/app/javascript/studio/nav_collapse.js

@@ -22,7 +22,25 @@
 // sizing opinion, so an app whose navbar collapses to different endpoints than
 // the engine's adopts the mechanism without touching its markup.
 //
-// Four details are load-bearing:
+// Five details are load-bearing:
+//
+//   the hold: the header keeps its EXPANDED footprint in the page's flow. As it
+//   shrinks, the controller gives the difference back as margin below it, so
+//   the document never changes height and nothing under the header moves on
+//   its own. Before the hold, the collapse reflowed the whole page every frame:
+//   content ran ahead of the finger while collapsing, a flick back to the top
+//   pushed the page DOWN for ~10 frames after the scroll had stopped, and near
+//   the bottom of a page the browser clamped scrollY back 4px a frame as the
+//   document shrank under it. Held, the page scrolls exactly as far as the
+//   finger moved it, and only the header itself changes size. A header that
+//   is not in flow (fixed or absolute) is left alone: it never moved the page.
+//
+//   (Held, the two guards below exist only for an UNHELD header. The document
+//   no longer shortens, so the short-page flap cannot happen, and the per-frame
+//   cap, which slowed the header so the page it dragged would not jump, now
+//   only makes the header lag the scroll. Worse, a lagging header opens a gap
+//   above the content on a fast scroll back to the top. Held, the progress is
+//   the scroll position, every frame.)
 //
 //   passive + rAF: the listener never blocks the compositor and coalesces a
 //   burst of scroll events (iOS momentum fires far above 60Hz) into one write
@@ -31,7 +49,9 @@
 //   frame, and it would leak the live page's scroll progress into the preview
 //   headers on /navbar.
 //
-//   the smoothstep: collapsing a sticky, IN-FLOW header pulls the page up,
+//   the smoothstep (written for an UNHELD header; held, the page does not
+//   move, and the smoothstep only shapes how the header itself shrinks):
+//   collapsing a sticky, IN-FLOW header pulls the page up,
 //   so during the collapse content moves by the scroll AND by the shrink:
 //   faster than the finger, always. That is inherent; reclaiming the vertical
 //   space is the point. What is tunable is the shape of the burst. --nav-ramp
@@ -64,11 +84,13 @@ export const DEFAULT_MAX_STEP = 5;
 //   scrollHeight  document.documentElement.scrollHeight
 //   innerHeight   window.innerHeight
 //   reduce        prefers-reduced-motion matches
+//   held          the header holds its footprint (see the hold above): no
+//                 short-page guard, no per-frame cap
 //
 // Answers { p, settling }: the progress to publish, and whether the frame
 // clamp left it short of where the scroll position wants it (so the caller
 // must schedule another frame).
-export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, reduce }) {
+export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, reduce, held }) {
   // The height the document WOULD have with the navbar expanded. The
   // add-back is the whole trick; see the guard note above.
   var roomExpanded = scrollHeight - innerHeight + ramp * p;
@@ -76,7 +98,7 @@ export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, re
   // WHERE THE COLLAPSE WANTS TO BE, from scroll position alone.
   var target;
   var snap = false;
-  if (roomExpanded < ramp + 24) {
+  if (!held && roomExpanded < ramp + 24) {
     target = 0;
     snap = true;
   } else if (reduce) {
@@ -85,6 +107,8 @@ export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, re
   } else {
     var t = Math.min(1, y / ramp);
     target = t * t * (3 - 2 * t);
+    // Held, the progress IS the scroll position: nothing to cap.
+    if (held) snap = true;
   }
 
   // THE RATE LIMIT: how far the collapse may travel in ONE frame.
@@ -115,7 +139,7 @@ export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, re
   if (snap) {
     // A guard refusal and a reduced-motion state are DECISIONS, not
     // motion; ramping them would animate the very thing each exists to
-    // avoid.
+    // avoid. A held header follows the scroll exactly.
     next = target;
   } else {
     var maxStep = (3 * maxPx) / ramp;
@@ -135,6 +159,30 @@ export function shadowLit(lit, y) {
   return lit ? y > 5 : y > 60;
 }
 
+// THE HOLD, in two parts.
+//
+// THE LINEAR PART IS CSS. The header carries
+//   margin-bottom: calc(base + var(--nav-hold) * var(--nav-p) + var(--nav-hold-fix))
+// where --nav-hold is its rest height minus its collapsed height. That margin
+// grows in the SAME style recalc that shrinks the header, so the document
+// never shortens, not even for one layout. (Setting the margin from script
+// after the shrink was the first version of this, and it lost: the shrink's
+// own layout shortened the document, and on a short page the browser clamped
+// scrollY before the margin came back. Measured: 211 -> 167.)
+//
+// THE RESIDUE IS SCRIPT. A collapse need not be exactly linear in --nav-p
+// (the tallest thing in the row can change mid-ramp), and the scrolled state
+// may add a border. holdFix answers what the linear part missed, so the
+// footprint is the rest height exactly: rest - (height + hold * p).
+export function holdFix({ rest, height, hold, p }) {
+  return rest - height - hold * p;
+}
+
+// Only a header in the page's flow moves the page as it shrinks.
+export function inFlow(position) {
+  return position !== 'fixed' && position !== 'absolute';
+}
+
 // --nav-ramp and --nav-max-step off the header's computed style, each with
 // its default when the band declares none.
 export function readTuning(style) {
@@ -162,12 +210,60 @@ export class NavCollapse {
     this._onScroll = this.onScroll.bind(this);
     this._onResize = this.onResize.bind(this);
     this._apply = this.apply.bind(this);
+    this.held = false;
+    this.rest = 0;
+    this.hold = 0;
+    this.fix = 0;
+    this.lastHeight = null;
+    this._observer = null;
+    this._remeasure = this.remeasure.bind(this);
   }
 
   start() {
     this.stopped = false;
     this._reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
-    this.tuning = readTuning(getComputedStyle(this.el));
+    // A HEADER RESTORED FROM TURBO'S SNAPSHOT CACHE arrives as it was left:
+    // its scrolled classes on, and this controller's own hold still inline
+    // (Turbo copies the page before the old controller disconnects). Read as
+    // the header's own, that hold was counted twice on Back: a permanent band
+    // under the header, 39-43px on turf-monster's contest page. So the
+    // controller clears what it owns before it reads anything.
+    this.onScrolled(false);
+    this.el.style.marginBottom = '';
+    this.el.style.removeProperty('--nav-hold');
+    this.el.style.removeProperty('--nav-hold-fix');
+    this.el.style.removeProperty('--nav-p');
+    var style = getComputedStyle(this.el);
+    this.tuning = readTuning(style);
+    this.held = inFlow(style.position);
+    if (this.held) {
+      var base = parseFloat(style.marginBottom) || 0;
+      this.el.style.marginBottom =
+        'calc(' + base + 'px + var(--nav-hold, 0px) * var(--nav-p, 0) + var(--nav-hold-fix, 0px))';
+      this.measure();
+      // The header's height also moves for reasons that are not --nav-p: the
+      // scrolled state's bottom border (1px), a webfont landing, a
+      // Turbo-streamed badge. The observer re-applies the hold for any of
+      // them, in the frame they land. Only a header AT REST (unscrolled,
+      // expanded) redefines the rest height, because that is the one state
+      // whose height the footprint must equal: scrolled, a change is
+      // something the header is doing, not what it rests at.
+      if (typeof ResizeObserver === 'function') {
+        var self = this;
+        this._observer = new ResizeObserver(function () {
+          if (self.stopped) return;
+          var h = self.el.getBoundingClientRect().height;
+          if (self.lastHeight !== null && Math.abs(h - self.lastHeight) <= 0.1) return;
+          self.lastHeight = h;
+          // At rest the header's height IS its rest height, and a change
+          // there is new content: measure both endpoints again.
+          if (self.atRest() && Math.abs(h - self.rest) > 0.1) self.measure();
+          else self.correct(h);
+        });
+        this._observer.observe(this.el);
+      }
+      if (document.fonts && document.fonts.ready) document.fonts.ready.then(this._remeasure);
+    }
     this.apply();
 
     window.addEventListener('scroll', this._onScroll, { passive: true });
@@ -181,6 +277,13 @@ export class NavCollapse {
     this.stopped = true;
     window.removeEventListener('scroll', this._onScroll);
     window.removeEventListener('resize', this._onResize);
+    if (this._observer) this._observer.disconnect();
+    this._observer = null;
+    if (this.held) {
+      this.el.style.marginBottom = '';
+      this.el.style.removeProperty('--nav-hold');
+      this.el.style.removeProperty('--nav-hold-fix');
+    }
     if (this._reduce && this._reduce.removeEventListener) {
       this._reduce.removeEventListener('change', this._apply);
     }
@@ -194,9 +297,69 @@ export class NavCollapse {
 
   onResize() {
     this.tuning = readTuning(getComputedStyle(this.el));
+    if (this.held) this.measure();
     this.onScroll();
   }
 
+  atRest() {
+    return this.p === 0 && window.scrollY <= 0;
+  }
+
+  // The header's height at a given --nav-p, read by putting it there for the
+  // length of one synchronous layout. Nothing paints in between, so the
+  // reader never sees it. The margin is pinned to the rest height while it
+  // reads, so the document only ever GROWS during the read: growing cannot
+  // clamp the scroll position, shrinking can.
+  heightAt(p) {
+    var style = this.el.style;
+    var was = style.getPropertyValue('--nav-p');
+    style.setProperty('--nav-p', String(p));
+    var h = this.el.getBoundingClientRect().height;
+    if (was) style.setProperty('--nav-p', was); else style.removeProperty('--nav-p');
+    return h;
+  }
+
+  // Both endpoints, then the linear hold between them and the residue at the
+  // current progress. Both are read UNSCROLLED: the rest height is the
+  // header's height at the top of the page, where the scrolled state (and any
+  // border it carries) is off. The residue absorbs that state while it is on.
+  measure() {
+    var style = this.el.style;
+    var lit = this.scrolled;
+    if (lit) this.onScrolled(false);
+    style.setProperty('--nav-hold-fix', '0px');
+    this.fix = 0;
+    style.setProperty('--nav-hold', '0px');
+    var pinned = style.marginBottom;
+    style.marginBottom = '0px';
+    var rest = this.heightAt(0);
+    style.marginBottom = rest + 'px';
+    var collapsed = this.heightAt(1);
+    style.marginBottom = pinned;
+    if (lit) this.onScrolled(true);
+    this.rest = rest;
+    this.hold = Math.max(0, rest - collapsed);
+    style.setProperty('--nav-hold', this.hold + 'px');
+    this.correct(this.el.getBoundingClientRect().height);
+  }
+
+  remeasure() {
+    if (this.stopped || !this.held) return;
+    this.measure();
+  }
+
+  // Write the residue the linear hold missed, when it moved by more than a
+  // rounding error. The observer calls this in the frame the height changed,
+  // before paint.
+  correct(height) {
+    this.lastHeight = height;
+    var fix = holdFix({ rest: this.rest, height: height, hold: this.hold, p: this.p });
+    if (Math.abs(fix - this.fix) > 0.1) {
+      this.fix = fix;
+      this.el.style.setProperty('--nav-hold-fix', fix.toFixed(2) + 'px');
+    }
+  }
+
   apply() {
     this.queued = false;
     if (this.stopped) return;
@@ -210,7 +373,8 @@ export class NavCollapse {
       maxPx: this.tuning.maxPx,
       scrollHeight: document.documentElement.scrollHeight,
       innerHeight: window.innerHeight,
-      reduce: this._reduce.matches
+      reduce: this._reduce.matches,
+      held: this.held
     });
 
     if (frame.p !== this.p) {

data/app/javascript/studio/pinned_stack.js

@@ -85,6 +85,69 @@ export function composed(pins) {
 
 var started = false
 
+// THE READERS OF THE STACK, found rather than declared.
+//
+// Every value this publisher writes is an inherited custom property on
+// documentElement, so every write restyles the WHOLE document, whether or not
+// an element reads it. On a scroll frame that is the hot path: the header's
+// bottom edge moves every frame while an ambient bar scrolls away and while
+// the navbar collapses. Measured on turf-monster's contest page (about 2,000
+// elements): one root write cost 8.7ms of style recalc against 0.2ms for the
+// same write on the header, and the collapse dropped every second or third
+// frame on a 120Hz screen. The hub's 478-element /links paid 1ms.
+//
+// Only a handful of elements read these values. So while a scroll is in
+// motion the publisher writes them onto those elements alone, and writes the
+// root once the scroll settles. A reader is any element that
+//   · carries [data-pin-follow], the explicit opt-in;
+//   · uses one in its inline style (studio/_sidebar_panel does); or
+//   · matches a stylesheet rule that uses one (scanned once per document).
+// The document's root and body are never followers: a rule there (a custom
+// property derived from --nav-h on :root) is served by the settled write.
+//
+// A reader follows LIVE only when it uses a value for something that paints.
+// scroll-margin and scroll-padding matter only at the moment of an anchor
+// jump, and the settled root serves them: turf-monster's contest board carries
+// `scroll-margin-top: var(--nav-h)` on a 1,200-element subtree, and following
+// it live cost the whole page's restyle back.
+export var READS_THE_STACK = /var\(\s*--(pin-|nav-bottom|nav-h\b)/;
+
+export function readsLive(cssText) {
+  var decls = String(cssText || '').split(';');
+  for (var i = 0; i < decls.length; i++) {
+    var at = decls[i].indexOf(':');
+    if (at < 0) continue;
+    var name = decls[i].slice(0, at).trim().toLowerCase();
+    if (/^scroll-(margin|padding)/.test(name)) continue;
+    if (READS_THE_STACK.test(decls[i].slice(at + 1))) return true;
+  }
+  return false;
+}
+
+export function followerSelectors(sheets) {
+  var found = ['[data-pin-follow]', '[style*="var(--pin-"]', '[style*="var(--nav-bottom"]', '[style*="var(--nav-h"]'];
+  function walk(rules) {
+    for (var i = 0; rules && i < rules.length; i++) {
+      var rule = rules[i];
+      if (rule.selectorText && rule.style && readsLive(rule.style.cssText)) {
+        var parts = rule.selectorText.split(',');
+        for (var j = 0; j < parts.length; j++) {
+          var sel = parts[j].trim();
+          if (sel && found.indexOf(sel) === -1) found.push(sel);
+        }
+      }
+      if (rule.cssRules) walk(rule.cssRules);
+    }
+  }
+  for (var k = 0; k < sheets.length; k++) {
+    var rules = null;
+    // A cross-origin sheet refuses cssRules; it cannot hold this app's readers.
+    try { rules = sheets[k].cssRules; } catch (e) { rules = null; }
+    walk(rules);
+  }
+  return found;
+}
+
 export function startPinnedStack() {
   if (started || !window.ResizeObserver) return;
   started = true;
@@ -109,6 +172,73 @@ export function startPinnedStack() {
   // when one departs. The REGISTRY ITSELF is never cached; see readPins().
   var observed = [];
 
+  // THE MOTION WRITE (see READS_THE_STACK above). lastScrollAt marks the
+  // gesture; within SETTLE_MS of it a publish writes the followers, and a
+  // timer writes the root once the scroll has been still that long.
+  var SETTLE_MS = 160;
+  var lastScrollAt = -Infinity;
+  var settleTimer = null;
+  var selectors = null;
+  // The scan is redone when the document's stylesheets change (a Turbo visit
+  // into a page with its own), keyed on their hrefs and count.
+  var scannedSheets = null;
+  var followed = [];
+  var followedProps = [];
+
+  function followers() {
+    var key = [].map.call(document.styleSheets, function (sheet) { return sheet.href || 'inline'; }).join('|');
+    if (!selectors || key !== scannedSheets) {
+      selectors = followerSelectors(document.styleSheets);
+      scannedSheets = key;
+    }
+    var out = [];
+    for (var i = 0; i < selectors.length; i++) {
+      var nodes;
+      // A selector the scan lifted may not be queryable (a pseudo-element).
+      try { nodes = document.querySelectorAll(selectors[i]); } catch (e) { continue; }
+      for (var j = 0; j < nodes.length; j++) {
+        var n = nodes[j];
+        if (n === document.documentElement || n === document.body || n === document.head) continue;
+        // The inline matches are substring guesses; the declarations decide.
+        if (selectors[i].charAt(0) === '[' && selectors[i] !== '[data-pin-follow]' && !readsLive(n.getAttribute('style'))) continue;
+        if (out.indexOf(n) === -1) out.push(n);
+      }
+    }
+    return out;
+  }
+
+  function writeFollowers(props) {
+    var targets = followers();
+    // An element that stopped reading the stack (or left the page) gives its
+    // copies back, so it inherits the root again.
+    for (var f = 0; f < followed.length; f++) {
+      if (targets.indexOf(followed[f]) !== -1) continue;
+      for (var g = 0; g < followedProps.length; g++) followed[f].style.removeProperty(followedProps[g][0]);
+    }
+    for (var i = 0; i < targets.length; i++) {
+      for (var k = 0; k < props.length; k++) {
+        if (targets[i].style.getPropertyValue(props[k][0]) !== props[k][1]) targets[i].style.setProperty(props[k][0], props[k][1]);
+      }
+    }
+    followed = targets;
+    followedProps = props;
+  }
+
+  // Once the root holds the settled values, the followers inherit them again.
+  function releaseFollowers() {
+    for (var i = 0; i < followed.length; i++) {
+      for (var k = 0; k < followedProps.length; k++) followed[i].style.removeProperty(followedProps[k][0]);
+    }
+    followed = [];
+    followedProps = [];
+  }
+
+  function settle() {
+    settleTimer = null;
+    publishAll();
+    releaseFollowers();
+  }
+
   // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
   //
   // This used to build a `pins` array once and hold each element by reference
@@ -174,6 +304,22 @@ export function startPinnedStack() {
     if (!force) {
       for (i = 0; i < pins.length; i++) { if (!last.hasOwnProperty(pins[i].name)) { force = true; break; } }
     }
+
+    // IN MOTION, THE FOLLOWERS ONLY. A structural change still writes the
+    // root at once: it is rare, and a layer arriving must reach every reader.
+    if (!force && performance.now() - lastScrollAt < SETTLE_MS) {
+      var props = [];
+      for (i = 0; i < pins.length; i++) {
+        p = pins[i];
+        props.push(['--pin-' + p.name + '-h', p.h + 'px'], ['--pin-' + p.name + '-bottom', p.bottom + 'px'], ['--pin-' + p.name + '-top', p.top + 'px']);
+        if (p.legacy) props.push(['--nav-h', p.h + 'px'], ['--nav-bottom', p.bottom + 'px']);
+      }
+      props.push(['--pin-stack-bottom', stack + 'px']);
+      writeFollowers(props);
+      if (settleTimer) clearTimeout(settleTimer);
+      settleTimer = setTimeout(settle, SETTLE_MS);
+      return;
+    }
     for (i = 0; i < pins.length; i++) {
       p = pins[i];
       seen[p.name] = true;
@@ -287,6 +433,12 @@ export function startPinnedStack() {
   function invalidate() { forceWrite = true; publishAll(); }
   document.addEventListener('DOMContentLoaded', invalidate);
   document.addEventListener('turbo:load', invalidate);
+  // Turbo copies the page into its snapshot cache before it leaves: give the
+  // followers' copies back first, so a restored page carries none of them.
+  document.addEventListener('turbo:before-cache', function () {
+    if (settleTimer) { clearTimeout(settleTimer); settleTimer = null; }
+    releaseFollowers();
+  });
   // A Turbo Stream replaces nodes WITHOUT a turbo:load. The registry is derived
   // per publish, so a stale reference is no longer possible either way — but the
   // OBSERVER still has to be moved onto the incoming node, and the stack has to
@@ -297,6 +449,8 @@ export function startPinnedStack() {
   // Registered ONCE at start, not inside a re-scan, so a Turbo nav
   // re-publishes instead of stacking another listener per visit.
   window.addEventListener('scroll', schedule, { passive: true });
+  // The gesture's clock for the motion write (see READS_THE_STACK).
+  window.addEventListener('scroll', function () { lastScrollAt = performance.now(); }, { passive: true });
   window.addEventListener('resize', schedule, { passive: true });
 
   // A deferred module runs after the body is parsed, so the layers are already

data/lib/studio/engine.rb

@@ -42,6 +42,30 @@ module Studio
     # silently assigns the OrderedOptions and rotation then dies inside a
     # rescued comparison. The behavioral test caught that; a config read-back
     # would have called it green.
+    # STORAGE, PART 1: THE ACTIVE STORAGE SERVICES (Studio::Storage). Active
+    # Storage builds its service registry in an on_load(:active_storage_blob)
+    # hook its "active_storage.services" initializer registers, reading
+    # config.active_storage.service_configurations, or config/storage.yml when
+    # that is nil. Hooks run in registration order, so this one, registered
+    # BEFORE that initializer, runs first and hands it the app's own services
+    # with the engine's `amazon` / `amazon_dev` merged under them (an app's
+    # service of the same name wins). Lazy like Active Storage's own read: it
+    # runs when Blob first loads, after every host initializer, so it sees the
+    # host's s3_bucket_prefix. An app still configuring Studio::S3 itself
+    # (Studio::Storage.owns_connection? false) keeps its services as they are.
+    # Declared first in this class so Railtie's
+    # implicit `after: <previous initializer>` chaining ties it to nothing.
+    initializer "studio.storage.services", before: "active_storage.services" do |app|
+      ActiveSupport.on_load(:active_storage_blob) do
+        next unless Studio::Storage.enabled? && Studio::Storage.owns_connection?
+
+        storage = app.config.active_storage
+        storage.service_configurations = Studio::Storage.merge_services(
+          storage.service_configurations || Studio::Storage.storage_file_configurations(Rails.root, Rails.env)
+        )
+      end
+    end
+
     initializer "studio.logger", before: :initialize_logger, after: :load_environment_hook do |app|
       cap = Studio::LogRotation.cap_for(
         env: Rails.env,
@@ -254,6 +278,23 @@ module Studio
       end
     end
 
+    # STORAGE, PART 2: THE BOOT CHECK and Studio::S3 on R2 (Studio::Storage),
+    # for an app that names its bucket. After the host's config/initializers,
+    # where s3_bucket_prefix and storage_public_url_required are set, and before
+    # anything serves. Raising here fails a release phase's db:migrate instead of
+    # crash-looping web and worker afterwards. Both switches are always checked;
+    # the connection is checked and applied only when the host left s3_endpoint
+    # unset, so an app still carrying its own StorageBackend keeps its own rules.
+    # Declared LAST among this class's initializers: Railtie chains each
+    # initializer `after:` the one declared before it, so anything declared
+    # below this would be dragged after the host's initializers too.
+    initializer "studio.storage", after: :load_config_initializers do
+      next unless Studio::Storage.enabled?
+
+      Studio::Storage.validate!(check_connection: false)
+      Studio::Storage.apply_studio_s3_settings!
+    end
+
     # `studio_engine:install:migrations` with no ActiveRecord. Rails defines it
     # for every engine that ships db/migrate, and it invokes
     # `railties:install:migrations`, which only ActiveRecord's tasks define, so

data/lib/studio/health_report.rb

@@ -6,6 +6,10 @@ require "active_support/core_ext/module/attribute_accessors"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/object/try"
 require "active_support/core_ext/string/filters"
+require "active_support/security_utils"
+require "digest"
+require "time"
+require_relative "version"
 
 # The daily application health report: signups, errors and (optionally) contact
 # messages from the last day, emailed at 07:00 in the app's zone. The full
@@ -48,8 +52,20 @@ module Studio
   #   config.health_report_contacts = ->(window) { ContactSubmission.where(created_at: window) }
   mattr_accessor :health_report_contacts, default: nil
 
+  # The bearer token the hub presents to GET /_studio/health_report, the JSON
+  # copy of this report that McRitchie Studio pulls from every app at 07:00 and
+  # posts to Discord. nil or blank falls through to ENV["STUDIO_HEALTH_TOKEN"],
+  # read on every request; blank there too means the endpoint answers 404.
+  mattr_writer :health_report_token, default: nil
+
+  def self.health_report_token
+    class_variable_get(:@@health_report_token).presence || ENV.fetch(HealthReport::TOKEN_ENV_KEY, nil).presence
+  end
+
   module HealthReport
     ENV_KEY = "STUDIO_HEALTH_REPORT_TO"
+    TOKEN_ENV_KEY = "STUDIO_HEALTH_TOKEN"
+    SCHEMA = 1         # the JSON contract's version; bump on a breaking change
     LISTED = 10        # names shown under a count; the count is always whole
     ERROR_GROUPS = 15  # distinct errors shown; the rest are counted as "more"
 
@@ -131,6 +147,65 @@ module Studio
       "#{count} #{count == 1 ? noun : "#{noun}s"}"
     end
 
+    # ---- the JSON endpoint (Studio::HealthReportsController) ---------------
+
+    # Does this Authorization header carry the configured token? false when no
+    # token is configured. Both sides are digested before the constant-time
+    # compare, so neither the token's bytes nor its length leak through timing.
+    def authorized?(authorization, token: Studio.health_report_token)
+      return false if token.blank?
+
+      presented = authorization.to_s[/\ABearer[ ]+(\S+)\s*\z/i, 1]
+      return false if presented.nil?
+
+      ActiveSupport::SecurityUtils.secure_compare(Digest::SHA256.hexdigest(presented),
+                                                  Digest::SHA256.hexdigest(token.to_s))
+    end
+
+    # The window the endpoint reports: the day ENDING at `ending` (an ISO 8601
+    # time), else the day the job would report now. Raises ArgumentError on a
+    # value that is not ISO 8601, which the controller answers with a 400.
+    def window_for(ending, now: Time.now)
+      return window(now) if ending.nil?
+
+      window_ending(Time.iso8601(ending.to_s))
+    end
+
+    SECTION_KEYS = %i[signups errors contacts].freeze
+
+    # The report as the hub reads it. COUNTS ONLY, by construction: a Section's
+    # `items` (names and emails) never reach this hash, so no signup or contact
+    # detail leaves the app. Error groups carry the class and the truncated
+    # message the email already shows.
+    def payload(report)
+      {
+        schema: SCHEMA,
+        app: report.app_name.to_s,
+        engine_version: Studio::VERSION,
+        window: { begin: iso(report.window.begin), end: iso(report.window.end), label: report.window_label },
+        quiet: report.quiet?,
+        sections: SECTION_KEYS.filter_map do |key|
+          section = report.public_send(key)
+          next unless section
+
+          { key: key.to_s, title: section.title, count: section.count.to_i, failure: section.failure }
+        end,
+        error_kinds: report.error_kinds.to_i,
+        error_groups: Array(report.error_groups).map do |group|
+          { error_class: group.error_class, message: scrub(group.message), count: group.count.to_i,
+            first_seen: iso(group.first_seen), last_seen: iso(group.last_seen) }
+        end
+      }
+    end
+
+    def iso(time) = time&.iso8601
+
+    EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/
+
+    # An exception message can quote the address it choked on ("no account for
+    # ann@example.com"). The email may show it; the JSON leaving the app may not.
+    def scrub(message) = message.to_s.gsub(EMAIL, "[email]")
+
     # ---- gathering (needs the host's database) ------------------------------
 
     def build(window: self.window(Time.now))

data/lib/studio/storage.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require_relative "environment_banner"
+
+module Studio
+  # OBJECT STORAGE IS CLOUDFLARE R2, AND ONLY R2. One copy of the rules the hub,
+  # turf-monster and mcritchie-industries each carried as a hand-written
+  # `StorageBackend` module (AWS S3 was retired on 2026-10-10, so there is no S3
+  # stage and no mirror stage left to select). README.md, "Managed storage".
+  #
+  # ON BY DEFAULT for every app that names its bucket (`config.s3_bucket_prefix`).
+  # Such an app gets, with no initializer of its own:
+  #
+  #   - the BOOT CHECK (Studio::Engine, "studio.storage"): a retired or unknown
+  #     switch value, or a missing R2 variable in production, refuses the boot
+  #     by name. config/storage.yml is rendered lazily (a release-phase
+  #     db:migrate never renders it), so without a boot check a bad value passes
+  #     the release and crash-loops web and worker instead.
+  #   - Studio::S3 on R2: endpoint, region "auto", keys and public URL, filled in
+  #     when the app left `s3_endpoint` unset (an app that hand-configures the
+  #     connection keeps it; the engine stands back).
+  #   - Active Storage services `amazon` (this environment's bucket) and
+  #     `amazon_dev` (always the dev bucket), both `service: StudioTrashS3` on R2.
+  #     The names are kept because blob rows record them. A service of the same
+  #     name in the app's own config/storage.yml WINS, so an app's own copy keeps
+  #     working until it adopts this one.
+  #
+  # Opt out with `config.manage_storage = false`.
+  #
+  # THE TWO SWITCHES, ACTIVE_STORAGE_BACKEND and STUDIO_S3_BACKEND, staged the
+  # move and are still `r2` on the deployed apps. Unset or `r2` means R2. A
+  # retired value (s3, mirror_to_r2, mirror_to_s3) or any other value RAISES in
+  # every environment: it must never look like a successful selection of a store
+  # that no longer exists.
+  #
+  # THE CONNECTION: R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY (1Password
+  # item r2.<prefix>: the prod pair on production, the dev pair on QA and
+  # locally), plus R2_PUBLIC_URL, which is required only when the app sets
+  # `config.storage_public_url_required = true` (it serves public object URLs to
+  # strangers; an app with private objects only has no public domain).
+  #
+  # A MISSING VARIABLE:
+  #   production (QA boots RAILS_ENV=production too)   RAISES, naming every
+  #     missing variable. A dyno that boots without storage fails at the first
+  #     upload hours later; one that refuses to boot fails the deploy.
+  #   elsewhere, NONE set (test, CI, a keyless desk)   boots on a placeholder
+  #     connection: a reserved `.invalid` host (RFC 2606, never resolves) and
+  #     placeholder keys, so nothing reaches AWS through the SDK's default
+  #     endpoint or credential chain, and the first real call fails naming
+  #     r2-not-configured.invalid.
+  #   elsewhere, SOME set   RAISES, naming the missing ones: half a configuration
+  #     is a mistake, not a choice.
+  #
+  # Dependency-free apart from EnvironmentBanner, so the unit suite requires it
+  # directly and every method takes its inputs as arguments.
+  module Storage
+    BACKEND = "r2"
+    SWITCHES = %w[ACTIVE_STORAGE_BACKEND STUDIO_S3_BACKEND].freeze
+    RETIRED_VALUES = %w[s3 mirror_to_r2 mirror_to_s3].freeze
+
+    CONNECTION_VARIABLES = %w[R2_ENDPOINT R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY].freeze
+    PUBLIC_URL_VARIABLE = "R2_PUBLIC_URL"
+    REGION = "auto"
+
+    # The engine's Active Storage service: S3Service whose delete MOVES the
+    # object under trash/<utc date>/<epoch ms>/<key>, so a purged or replaced
+    # attachment has a three-day grace period
+    # (lib/active_storage/service/studio_trash_s3_service.rb).
+    ACTIVE_STORAGE_SERVICE = "StudioTrashS3"
+    # The service names blob rows record. `amazon` is this environment's bucket;
+    # `amazon_dev` is the dev bucket in every environment (local desks).
+    SERVICE = "amazon"
+    DEV_SERVICE = "amazon_dev"
+
+    UNCONFIGURED_HOST = "r2-not-configured.invalid"
+    PLACEHOLDER_ENDPOINT = "https://#{UNCONFIGURED_HOST}"
+    PLACEHOLDER_KEY = "r2-not-configured"
+    PLACEHOLDER_PUBLIC_URL = "https://#{UNCONFIGURED_HOST}"
+
+    module_function
+
+    # Whether the engine manages this app's storage: it named its bucket and did
+    # not opt out.
+    def enabled?(prefix: Studio.s3_bucket_prefix, manage: manage_setting)
+      manage != false && !prefix.to_s.strip.empty?
+    end
+
+    # Whether a missing R2 variable refuses the boot. Production and QA both run
+    # RAILS_ENV=production. The one exception is Rails' own build-time flag:
+    # `SECRET_KEY_BASE_DUMMY=1 bin/rails assets:precompile` (a Dockerfile) boots
+    # production with no secrets on purpose and never touches storage, so it
+    # boots on the placeholder connection instead (moms-app's rule).
+    def strict?(env = ENV)
+      rails_production? && env["SECRET_KEY_BASE_DUMMY"].to_s.strip.empty?
+    end
+
+    def rails_production?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:production?) && Rails.env.production? ? true : false
+    end
+
+    def active_storage_stage(env = ENV)
+      stage(env, "ACTIVE_STORAGE_BACKEND")
+    end
+
+    def studio_s3_stage(env = ENV)
+      stage(env, "STUDIO_S3_BACKEND")
+    end
+
+    def stage(env, name)
+      value = env[name].to_s.strip
+      return BACKEND if value.empty? || value == BACKEND
+
+      if RETIRED_VALUES.include?(value)
+        raise ArgumentError, "#{name}=#{value.inspect} names a retired stage: AWS S3 was retired on 2026-10-10 " \
+                             "and storage runs on Cloudflare R2 only. Unset #{name} or set it to #{BACKEND}."
+      end
+
+      raise ArgumentError, "#{name}=#{value.inspect} is not a storage backend; unset #{name} or set it to #{BACKEND}"
+    end
+
+    # The variables a complete connection needs.
+    def variables(public_url_required: public_url_required_setting)
+      public_url_required ? CONNECTION_VARIABLES + [PUBLIC_URL_VARIABLE] : CONNECTION_VARIABLES
+    end
+
+    # Whether this process holds a real R2 connection: every required variable
+    # set. False on CI and a keyless desk, where the connection is placeholders;
+    # code that must refuse up front rather than fail at its first call asks
+    # this, because the placeholder keys make "is a key set?" answer yes.
+    def configured?(env = ENV, public_url_required: public_url_required_setting)
+      variables(public_url_required: public_url_required).all? { |name| present?(env, name) }
+    end
+
+    # Whether development should talk to the remote dev bucket rather than Disk:
+    # whenever any R2 variable is set at all (a laptop's .env.development).
+    def remote_in_development?(env = ENV)
+      (CONNECTION_VARIABLES + [PUBLIC_URL_VARIABLE]).any? { |name| present?(env, name) }
+    end
+
+    # The R2 connection: { endpoint:, access_key_id:, secret_access_key:,
+    # public_url: }. public_url is nil when R2_PUBLIC_URL is unset and not
+    # required. See the module comment for what a missing variable does.
+    def connection(env = ENV, strict: strict?, public_url_required: public_url_required_setting,
+                   prefix: Studio.s3_bucket_prefix)
+      names = variables(public_url_required: public_url_required)
+      missing = names.reject { |name| present?(env, name) }
+
+      if missing.empty?
+        return { endpoint: value(env, "R2_ENDPOINT"), access_key_id: value(env, "R2_ACCESS_KEY_ID"),
+                 secret_access_key: value(env, "R2_SECRET_ACCESS_KEY"),
+                 public_url: present?(env, PUBLIC_URL_VARIABLE) ? value(env, PUBLIC_URL_VARIABLE) : nil }
+      end
+
+      if !strict && missing.size == names.size
+        return { endpoint: PLACEHOLDER_ENDPOINT, access_key_id: PLACEHOLDER_KEY, secret_access_key: PLACEHOLDER_KEY,
+                 public_url: public_url_required ? PLACEHOLDER_PUBLIC_URL : nil }
+      end
+
+      why = if strict
+              "production and QA refuse to boot without it"
+            else
+              "#{(names - missing).join(', ')} #{names.size - missing.size == 1 ? 'is' : 'are'} set, and half a " \
+                "configuration is a mistake: set all of #{names.join(', ')} or none"
+            end
+      raise ArgumentError, "#{missing.join(', ')} must be set: storage runs on Cloudflare R2 only, and #{why} " \
+                           "(#{credential_source(prefix)})"
+    end
+
+    # The credentials an operator should check when Studio::S3 fails wholesale.
+    def credential_hint(public_url_required: public_url_required_setting)
+      "#{variables(public_url_required: public_url_required).join(' / ')} (local dev reads them from .env.development)"
+    end
+
+    # The Studio.configure settings for Studio::S3. s3_public_url is present only
+    # when there is one to give (see #connection).
+    def studio_s3_settings(env = ENV, strict: strict?, public_url_required: public_url_required_setting,
+                           prefix: Studio.s3_bucket_prefix)
+      studio_s3_stage(env)
+      r2 = connection(env, strict: strict, public_url_required: public_url_required, prefix: prefix)
+      settings = { s3_endpoint: r2[:endpoint], s3_region: REGION,
+                   s3_access_key_id: r2[:access_key_id], s3_secret_access_key: r2[:secret_access_key] }
+      settings[:s3_public_url] = r2[:public_url] if r2[:public_url]
+      settings
+    end
+
+    # WHICH BUCKET. Only real production gets "<prefix>-production". QA boots
+    # RAILS_ENV=production exactly like production, so QA_ENV
+    # (Studio.qa_environment?) is what sends it to "<prefix>-dev", the same
+    # resolution Studio::S3 picks its bucket by, which keeps both writers on one
+    # bucket. A laptop, a desk and CI resolve the dev bucket too.
+    def bucket(prefix = Studio.s3_bucket_prefix, production: production_environment?)
+      "#{require_prefix(prefix)}-#{production ? 'production' : 'dev'}"
+    end
+
+    def dev_bucket(prefix = Studio.s3_bucket_prefix)
+      bucket(prefix, production: false)
+    end
+
+    # Real production: Rails production and not a QA app.
+    def production_environment?(env = ENV)
+      rails_production? && !EnvironmentBanner.qa_environment?(env)
+    end
+
+    # One Active Storage service config on R2. Checksums only when required:
+    # Active Storage sends Content-MD5, aws-sdk-s3 >= 1.178 adds a CRC32 by
+    # default, and R2 refuses a request carrying both (measured 2026-09-28).
+    def service(bucket_name, r2)
+      { "service" => ACTIVE_STORAGE_SERVICE,
+        "endpoint" => r2.fetch(:endpoint), "access_key_id" => r2.fetch(:access_key_id),
+        "secret_access_key" => r2.fetch(:secret_access_key),
+        "region" => REGION, "bucket" => bucket_name,
+        "request_checksum_calculation" => "when_required",
+        "response_checksum_validation" => "when_required" }
+    end
+
+    # The services the engine supplies: { "amazon" => ..., "amazon_dev" => ... }.
+    def active_storage_services(env = ENV, prefix: Studio.s3_bucket_prefix, strict: strict?,
+                                production: production_environment?(env))
+      active_storage_stage(env)
+      r2 = connection(env, strict: strict, public_url_required: false, prefix: prefix)
+      { SERVICE => service(bucket(prefix, production: production), r2),
+        DEV_SERVICE => service(dev_bucket(prefix), r2) }
+    end
+
+    # The app's own service configurations with the engine's merged UNDER them:
+    # a name the app's storage.yml already defines keeps the app's definition.
+    # Computes nothing (and so raises nothing) when the app defines both.
+    def merge_services(existing, env = ENV, prefix: Studio.s3_bucket_prefix, strict: strict?,
+                       production: production_environment?(env))
+      existing = (existing || {}).to_h
+      defined = existing.keys.map(&:to_s)
+      return existing if [SERVICE, DEV_SERVICE].all? { |name| defined.include?(name) }
+
+      supplied = active_storage_services(env, prefix: prefix, strict: strict, production: production)
+      supplied.reject { |name, _| defined.include?(name) }.merge(existing)
+    end
+
+    # What Active Storage itself would read when the app sets no
+    # service_configurations: config/storage/<env>.yml, else config/storage.yml.
+    # An app with neither starts from no services, and gets the engine's.
+    def storage_file_configurations(root, rails_env)
+      file = File.join(root.to_s, "config/storage/#{rails_env}.yml")
+      file = File.join(root.to_s, "config/storage.yml") unless File.exist?(file)
+      return {} unless File.exist?(file)
+
+      require "active_support/configuration_file"
+      ActiveSupport::ConfigurationFile.parse(file) || {}
+    end
+
+    # Point Studio::S3 at R2, unless the app configured the connection itself
+    # (s3_endpoint already set). A public URL the app set is never overwritten.
+    # Returns whether it wrote anything, and remembers the answer for
+    # #owns_connection?.
+    def apply_studio_s3_settings!(config = Studio, env = ENV, strict: strict?,
+                                  public_url_required: public_url_required_setting)
+      @owns_connection = config.s3_endpoint.to_s.strip.empty?
+      return false unless @owns_connection
+
+      settings = studio_s3_settings(env, strict: strict, public_url_required: public_url_required,
+                                         prefix: config.s3_bucket_prefix)
+      settings.delete(:s3_public_url) unless config.s3_public_url.to_s.strip.empty?
+      settings.each { |name, setting| config.public_send("#{name}=", setting) }
+      true
+    end
+
+    # Whether the engine owns this app's R2 connection: the app left s3_endpoint
+    # unset. An app that configured it is still carrying its own StorageBackend,
+    # which also decides its own Active Storage services (turf-monster defines
+    # NONE in a keyless process, and its suite pins that), so the engine adds no
+    # service to it either. Answered by the boot initializer once it has run;
+    # before that (a host initializer loading Blob early), by s3_endpoint itself.
+    def owns_connection?(config = Studio)
+      return @owns_connection unless @owns_connection.nil?
+
+      config.s3_endpoint.to_s.strip.empty?
+    end
+
+    def reset_ownership!
+      @owns_connection = nil
+    end
+
+    # THE BOOT CHECK. Both switches, always. The connection, when the engine
+    # owns it (the app left s3_endpoint unset); an app still carrying its own
+    # copy checks its own.
+    def validate!(env = ENV, strict: strict?, public_url_required: public_url_required_setting,
+                  prefix: Studio.s3_bucket_prefix, check_connection: true)
+      active_storage_stage(env)
+      studio_s3_stage(env)
+      connection(env, strict: strict, public_url_required: public_url_required, prefix: prefix) if check_connection
+      true
+    end
+
+    def credential_source(prefix)
+      name = prefix.to_s.strip
+      name.empty? ? "1Password item r2.<app>" : "1Password item r2.#{name}"
+    end
+
+    def present?(env, name)
+      !value(env, name).empty?
+    end
+
+    def value(env, name)
+      env[name].to_s.strip
+    end
+
+    def require_prefix(prefix)
+      name = prefix.to_s.strip
+      raise ArgumentError, "Studio.s3_bucket_prefix not set in config/initializers/studio.rb" if name.empty?
+
+      name
+    end
+
+    def manage_setting
+      Studio.respond_to?(:manage_storage) ? Studio.manage_storage : true
+    end
+
+    def public_url_required_setting
+      Studio.respond_to?(:storage_public_url_required) ? Studio.storage_public_url_required : false
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.107.0"
+  VERSION = "0.108.0.rc2"
 end

data/lib/studio.rb

@@ -44,6 +44,7 @@ require "studio/username_generator"
 require "studio/public_user"
 require "studio/name_parts"
 require "studio/s3"
+require "studio/storage"
 require "studio/image_cache"
 require "studio/host_schema"
 require "studio/link_token"
@@ -1110,6 +1111,17 @@ module Studio
   # production process ignores it, because its own bucket IS production.
   mattr_accessor :s3_production_public_url, default: nil
 
+  # STORAGE IS MANAGED BY DEFAULT (Studio::Storage; README.md, "Managed storage"). An app that
+  # names its bucket (s3_bucket_prefix) gets the R2 boot check, Studio::S3 on R2
+  # and the `amazon` / `amazon_dev` StudioTrashS3 services with no initializer of
+  # its own. false opts out entirely.
+  mattr_accessor :manage_storage, default: true
+
+  # Whether R2_PUBLIC_URL is as required as the keys: true for an app that hands
+  # public object URLs to strangers (og:images, email banners, headshots). An app
+  # whose objects are private and served by signed URL leaves it false.
+  mattr_accessor :storage_public_url_required, default: false
+
   # Knowledge layer — the S3-backed document store + /admin/knowledge browser
   # (Studio::KnowledgeDoc). Routes are opt-in like every route surface.
   # knowledge_agents is the roster of agent slugs the intake UI offers
@@ -1435,6 +1447,14 @@ module Studio
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
+      # The daily health report as JSON, for the hub's central 07:00 pull
+      # (Studio::HealthReportsController). Drawn in EVERY environment, production
+      # included: the controller is the gate, answering 404 until the app names
+      # a token (Studio.health_report_token / STUDIO_HEALTH_TOKEN) and 401 to a
+      # request that does not present it.
+      get "_studio/health_report", to: "studio/health_reports#show", as: :studio_health_report,
+          defaults: { format: :json }
+
       # Developer-desk tools. Drawn outside production, and each controller
       # re-checks Studio.local_tool_enabled? per request (loopback only) — the
       # route being absent is the outer gate, not the only one.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.107.0
+  version: 0.108.0.rc2
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -398,6 +398,7 @@ files:
 - app/controllers/studio/component_previews_controller.rb
 - app/controllers/studio/emails_controller.rb
 - app/controllers/studio/geo_settings_controller.rb
+- app/controllers/studio/health_reports_controller.rb
 - app/controllers/studio/knowledge_docs_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
@@ -775,6 +776,7 @@ files:
 - lib/studio/session_state.rb
 - lib/studio/sidebar_sections.rb
 - lib/studio/site_footer.rb
+- lib/studio/storage.rb
 - lib/studio/survey.rb
 - lib/studio/survey/breakdown.rb
 - lib/studio/survey/export.rb