studio-engine 0.107.0.rc1 → 0.108.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd203cdc5c017f4b75ad4f8a1d1af735e55a0791b33e457db3352bf4c250066c
-  data.tar.gz: b6afd7f7ea6cfe36293c5151caa9a4c53ffb31def0c0b3be752551a52e9655e9
+  metadata.gz: 01a56dee2b229822d24c392ac0f3c62f4b2a1d8c0328a2e84966dd4aa73630cc
+  data.tar.gz: 4b906a31d12a9fe5aae18b11f222fda647a1b7dba53627173c681f9da1fbb0b0
 SHA512:
-  metadata.gz: 8efd7d7240c1498a9bf3ba8486e7dcd46c52e174242aeea6e0560abfcded3a5a40530418316463834d5b02bedb4975dc2d16a3fdea2e1d980c3cf1dafbc2a89e
-  data.tar.gz: 11a034ae73a7112c6d2d1a46c639616230794a64ef88ae620552a3cb027c09cc5406812c78821c5658a0287bf9e44c26b5e417212be6b6292e5292fbd419d161
+  metadata.gz: 944aa8ae14a3a9b5a213a4e3594969a2343849ac972a9eba576e9a2fc784eb4c77ca082b947d3f0238478cd9e2e2bd9e5ee3d976365fe0a4cf47c721fbd13f9d
+  data.tar.gz: 472497c4720a4365117f33135f57cd7b9eefdbc2ee7c339f3f9354b9226ae1e05c1dae7fb424c47f1b7efa18302f4ca468e9ac59e4f7abf1767750f9dda051aa

data/CHANGELOG.md

@@ -4,6 +4,61 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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

@@ -966,6 +966,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 +1022,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 +1165,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/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/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.rc1"
+  VERSION = "0.108.0.rc1"
 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.107.0.rc1
+  version: 0.108.0.rc1
 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
@@ -775,6 +775,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