studio-engine 0.129.0 → 0.131.0

data/app/javascript/studio/controllers/style_section_nav_controller.js

@@ -11,10 +11,10 @@ import { activeIndex } from "studio/style_section_nav"
 
 const ACTIVE = "btn-primary"
 const REST = "btn-neutral"
-// A jump lands a section by its scroll-margin (--nav-h + 5rem), read while the
-// header may still be tall; the header then collapses, so the row rises and the
-// section does not. The full margin keeps the clicked section past the line,
-// with the collapse's height to spare, for any later scroll or resize.
+// A jump lands a section by its scroll margin, the stack's pinned heights, read while the
+// header may still be tall; the header then collapses, so the row rises and the section
+// does not (76px on the hub at phone width). The slack keeps the clicked section past the
+// line, for any later scroll or resize.
 const LINE_SLACK = 80
 
 export default class extends Controller {

data/app/javascript/studio/controllers/talk_to_agent_controller.js

@@ -0,0 +1,20 @@
+// talk-to-agent: the talk-to-agent modal (studio/agent_chat/_talk_modal), on the
+// engine's Stimulus application (studio/stimulus registers it lazily, the first
+// time a page renders the modal). It sits on the partial's wrapper:
+//
+//   <div data-studio-controller="talk-to-agent" data-talk-to-agent-soul="alex" ...>
+//
+// The click handling and the panel fill are studio/talk_to_agent.
+import { Controller } from "@hotwired/stimulus"
+import { mountTalkToAgent } from "studio/talk_to_agent"
+
+export default class extends Controller {
+  connect() {
+    this.talk = mountTalkToAgent(this.element)
+  }
+
+  disconnect() {
+    if (this.talk) this.talk.destroy()
+    this.talk = null
+  }
+}

data/app/javascript/studio/infinite_scroll.js

@@ -0,0 +1,142 @@
+// studio/infinite_scroll: the next page loads as its end comes near
+// (docs/LOADER.md, "Infinite scroll"). The markup is studio_infinite_scroll:
+//
+//   <div class="studio-infinite-scroll" data-studio-controller="infinite-scroll">
+//     ...page 1's items...
+//     <turbo-frame id="posts-page-2" data-infinite-scroll-next>
+//       <a href="/posts?page=2" data-infinite-scroll-more>Load more</a>
+//     </turbo-frame>
+//     <p role="status" aria-live="polite" data-infinite-scroll-status></p>
+//   </div>
+//
+// THE BUTTON IS THE PRIMITIVE. "Load more" is an ordinary link inside the next
+// page's frame, so a click loads that frame with Turbo, and with no script at all
+// it opens the next page. This module only clicks it early: when the frame comes
+// within NEAR_PX of the viewport (IntersectionObserver, watching the button's
+// row, since the frame itself takes no box), it points the frame at
+// the link's URL. The button stays in view the whole time, for a keyboard, a
+// screen reader or a browser with no observer.
+//
+//   announce   once a page lands, the status line says how many items came
+//              ("12 more loaded"), and that the list is done when no next frame
+//              came with them. It is polite: it waits for the reader to pause.
+//   focus      a page the reader asked for with the keyboard moves focus to
+//              its first new item, since the button they pressed is gone.
+//
+// It imports nothing; test/javascript/infinite_scroll.test.mjs loads it as a
+// data: module.
+
+export const NEAR_PX = 600
+export const NEXT = "turbo-frame[data-infinite-scroll-next]"
+export const MORE = "[data-infinite-scroll-more]"
+export const STATUS = "[data-infinite-scroll-status]"
+export const DEFAULT_ANNOUNCE = "%{count} more loaded"
+
+// The status line for a page of `count` items. `done` adds the end label.
+export function announcement(template, count, done, endLabel) {
+  const said = String(template || DEFAULT_ANNOUNCE).replace("%{count}", String(count))
+  return done && endLabel ? `${said}. ${endLabel}` : said
+}
+
+// The items a landed frame brought: its element children, less the next frame
+// and the end line, which are the list's machinery rather than its content.
+export function newItems(frame) {
+  return Array.from(frame.children || []).filter((el) =>
+    !(el.matches && (el.matches(NEXT) || el.matches(".studio-infinite-scroll-end") || el.matches(".studio-infinite-scroll-more"))))
+}
+
+// The one frame still waiting for its page: not loaded, not loading.
+export function waitingFrame(root) {
+  const frames = Array.from(root.querySelectorAll(NEXT))
+  return frames.find((frame) => !frame.hasAttribute("src") && !frame.hasAttribute("complete")) || null
+}
+
+// What the observer watches for a frame: its button row, else its link.
+export function sentinelOf(frame) {
+  return frame.querySelector(".studio-infinite-scroll-more") || frame.querySelector(MORE)
+}
+
+// Points the frame at its link's URL, once. Answers whether it started a load.
+export function loadNext(frame) {
+  if (!frame || frame.hasAttribute("src")) return false
+  const link = frame.querySelector(MORE)
+  const url = link && link.getAttribute("href")
+  if (!url) return false
+  frame.setAttribute("src", url)
+  return true
+}
+
+function say(status, text, win) {
+  if (!status) return
+  // Emptied first, so the same words said twice are heard twice.
+  status.textContent = ""
+  const put = () => { status.textContent = text }
+  if (win && typeof win.requestAnimationFrame === "function") win.requestAnimationFrame(put)
+  else put()
+}
+
+// Wires one list. Answers a stop function for the controller's disconnect.
+export function watchInfiniteScroll(root, win) {
+  win = win || window
+  let watcher = null
+  let watched = null
+  let byKeyboard = false
+
+  // The frame takes no box (display: contents), and an observer sees only
+  // boxes, so the watch is on its sentinel: the button's row inside it.
+  function arm() {
+    const frame = waitingFrame(root)
+    const sentinel = frame && sentinelOf(frame)
+    if (sentinel === watched) return
+    if (watcher && watched) watcher.unobserve(watched)
+    watched = sentinel
+    if (!sentinel || !watcher) return
+    watcher.observe(sentinel)
+  }
+
+  if (typeof win.IntersectionObserver === "function") {
+    watcher = new win.IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (!entry.isIntersecting) return
+        watcher.unobserve(entry.target)
+        const frame = entry.target.closest(NEXT)
+        // A Tab onto "Load more" scrolls it into view, so the observer loads the
+        // page before any click: focus inside the frame is that keyboard user.
+        const active = win.document && win.document.activeElement
+        byKeyboard = !!(frame && active && frame.contains(active))
+        loadNext(frame)
+      })
+    }, { rootMargin: `0px 0px ${NEAR_PX}px 0px` })
+  }
+
+  // A click on the button with no pointer behind it is a keyboard press.
+  function onClick(event) {
+    const link = event.target && event.target.closest && event.target.closest(MORE)
+    if (link && root.contains(link)) byKeyboard = event.detail === 0
+  }
+
+  function onLoad(event) {
+    const frame = event.target
+    if (!frame || !frame.matches || !frame.matches(NEXT) || !root.contains(frame)) return
+    const items = newItems(frame)
+    const done = !frame.querySelector(NEXT)
+    say(root.querySelector(STATUS), announcement(root.getAttribute("data-infinite-scroll-announce"), items.length, done,
+      root.getAttribute("data-infinite-scroll-end")), win)
+    if (byKeyboard && items[0]) {
+      if (!items[0].hasAttribute("tabindex")) items[0].setAttribute("tabindex", "-1")
+      items[0].focus({ preventScroll: false })
+    }
+    byKeyboard = false
+    arm()
+  }
+
+  root.addEventListener("click", onClick, true)
+  root.addEventListener("turbo:frame-load", onLoad)
+  arm()
+
+  return function stop() {
+    root.removeEventListener("click", onClick, true)
+    root.removeEventListener("turbo:frame-load", onLoad)
+    if (watcher) watcher.disconnect()
+  }
+}

data/app/javascript/studio/loader.js

@@ -270,8 +270,13 @@ export function setPercent(el, value) {
   if (!el) return
   var loader = el.classList && el.classList.contains('studio-loader') ? el : el.querySelector('.studio-loader')
   if (!loader) return
+  var percent = clampPercent(value)
   loader.setAttribute('data-loader-percent', '')
-  loader.style.setProperty('--studio-loader-percent', String(clampPercent(value)))
+  loader.style.setProperty('--studio-loader-percent', String(percent))
+  // A bar is a progressbar: a percent makes it determinate and is its value.
+  if (loader.getAttribute && loader.getAttribute('role') === 'progressbar') loader.setAttribute('aria-valuenow', String(percent))
+  var sweep = loader.querySelector && loader.querySelector('.progress-meter--indeterminate')
+  if (sweep) sweep.classList.remove('progress-meter--indeterminate')
 }
 
 // A submitter that carries a pending loader.

data/app/javascript/studio/page_transitions.js

@@ -20,6 +20,11 @@ export const STYLES = Object.freeze({
   slide: Object.freeze({ left: "slide-left", right: "slide-right", top: "slide-top", bottom: "slide-bottom" }),
   unfold: Object.freeze({ left: "unfold-right", right: "unfold-left", top: "unfold-bottom", bottom: "unfold-top" }),
 })
+// A Back plays the app's move the other way: the reverse direction, in the same style. So a
+// slide-left goes back as a slide-right, and an unfold-right as an unfold-left.
+export const REVERSE = Object.freeze({ left: "right", right: "left", top: "bottom", bottom: "top" })
+// A link that leads back up the trail: an ancestor in the crumbs, or the phone's parent link.
+export const BACK_LINK = "a[data-page-transition-back]"
 // Mirrors the default in lib/studio.rb, for a page with no style meta.
 export const DEFAULT_STYLE = "slide"
 
@@ -32,17 +37,48 @@ export const FULL_LOAD_STYLE_KEY = "studio-page-transition-style"
 const MAX_READY_IMAGES = 12
 const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"
 
-export function styleFor(direction, style) {
+export function styleFor(direction, style, back = false) {
   const moves = STYLES[Object.hasOwn(STYLES, style) ? style : DEFAULT_STYLE]
-  return Object.hasOwn(moves, direction) ? moves[direction] : null
+  if (!Object.hasOwn(moves, direction)) return null
+  return moves[back ? REVERSE[direction] : direction]
+}
+
+// Whether a visit goes back. Turbo marks <html> with data-turbo-visit-direction for each visit,
+// before turbo:visit fires: "back" for a restore to an earlier history entry, and "forward"
+// for a restore to a later one. So the browser's Forward keeps the app's direction. An advance
+// goes back only when the reader clicked a back link to that same address.
+export function visitIsBack({ action, turboDirection, url, backHref }) {
+  if (action === "restore") return turboDirection === "back"
+  return sameAddress(url, backHref)
+}
+
+// Whether a full load goes back: a traverse to an earlier history entry, or a back link.
+export function fullLoadIsBack(activation, backHref) {
+  if (!activation || !activation.entry) return false
+  if (activation.navigationType === "traverse") {
+    const from = activation.from
+    return !!from && typeof from.index === "number" && from.index >= 0 && activation.entry.index < from.index
+  }
+  return sameAddress(activation.entry.url, backHref)
+}
+
+export function sameAddress(a, b) {
+  if (!a || !b) return false
+  try {
+    const one = new URL(a, "https://x.invalid")
+    const two = new URL(b, "https://x.invalid")
+    return one.origin === two.origin && one.pathname === two.pathname && one.search === two.search
+  } catch {
+    return false
+  }
 }
 
 // The style for one visit, STILL, or null to leave the swap alone (the engine's fade plays,
 // and a morph between two pages stands). An advance visit to the same path can bring a new
 // page, as a launch panel does when it gives way to the chat at its own address, so a name
 // the two share still morphs. A refresh replaces, and stays silent.
-export function planVisit({ direction, style, from, to, transitions, sharedName, advance }) {
-  const move = styleFor(direction, style)
+export function planVisit({ direction, style, from, to, transitions, sharedName, advance, back }) {
+  const move = styleFor(direction, style, back)
   if (!transitions || !from || !to || !move) return null
   if (from === to) return advance && sharedName ? null : STILL
   return sharedName ? null : move
@@ -51,11 +87,11 @@ export function planVisit({ direction, style, from, to, transitions, sharedName,
 // The style a full load should play, or null for a plain load: planVisit's own rule, so the
 // two paths cannot differ. No morph, since the old page cannot read the new page's names
 // before its picture, and a browser with no activation entry has nothing to compare.
-export function planFullLoad({ direction, style, from, activation }) {
+export function planFullLoad({ direction, style, from, activation, back = false }) {
   const url = activation && activation.entry && activation.entry.url
   if (!url) return null
   const to = new URL(url).pathname
-  const move = planVisit({ direction, style, from, to, transitions: true, sharedName: false })
+  const move = planVisit({ direction, style, from, to, transitions: true, sharedName: false, back })
   return move === STILL ? null : move
 }
 
@@ -150,6 +186,11 @@ export function installPageTransitions(doc) {
   let target = null
   let advance = false
   let rendered = false
+  // The address of the back link the reader clicked last, if any. Matched by address, so a
+  // click that never became a visit (a modifier click, a cancelled visit) cannot turn the
+  // next visit around.
+  let backHref = null
+  let back = false
 
   const nameTheMorph = (shared) => {
     if (shared) root.dataset.pageTransitionMorph = ""
@@ -161,6 +202,12 @@ export function installPageTransitions(doc) {
   markHeld(doc)
   known.set(from, morphNames(doc))
 
+  // In capture, ahead of Turbo's own click listener, so the mark is down before the visit.
+  doc.addEventListener("click", (event) => {
+    const link = event.target && event.target.closest ? event.target.closest("a[href]") : null
+    backHref = link && link.matches(BACK_LINK) ? link.href : null
+  }, { capture: true })
+
   doc.addEventListener("turbo:visit", (event) => {
     root.dataset.pageTransitionVisit = ""
     // Turbo opens its view transition before it reads turbo-visit-control. A response it will
@@ -171,7 +218,12 @@ export function installPageTransitions(doc) {
     // A GET that redirects: Turbo renders the response, then replaces to the final address
     // with that same response, all before turbo:load. The page has landed, so nothing moves.
     const action = event.detail.action
-    if (rendered && action === "replace") from = target
+    const redirected = rendered && action === "replace"
+    if (redirected) from = target
+    // No guard keeps the first half's way: Turbo's replace (willRender: false) still fires
+    // turbo:before-render, but `from` is now `target`, so planVisit plays STILL either way.
+    back = visitIsBack({ action, turboDirection: root.dataset.turboVisitDirection, url: event.detail.url, backHref })
+    backHref = null
     rendered = false
     advance = action === "advance"
     predict(known.get(target))
@@ -207,6 +259,7 @@ export function installPageTransitions(doc) {
       transitions: !!doc.startViewTransition && !win.matchMedia(REDUCED_MOTION).matches,
       sharedName,
       advance,
+      back,
     })
     nameTheMorph(sharedName && style !== STILL)
     if (style) root.dataset.pageTransition = style
@@ -226,6 +279,7 @@ export function installPageTransitions(doc) {
     target = null
     advance = false
     rendered = false
+    back = false
     known.set(from, morphNames(doc))
     if (!visited) return
     delete root.dataset.pageTransition
@@ -244,7 +298,10 @@ export function installPageTransitions(doc) {
   // The last moment on the old document. The browser takes its picture after this.
   win.addEventListener("pageswap", (event) => {
     const transition = event.viewTransition
-    const style = transition && planFullLoad({ direction: readDirection(doc), style: readStyle(doc), from, activation: event.activation })
+    const activation = event.activation
+    const style = transition && planFullLoad({
+      direction: readDirection(doc), style: readStyle(doc), from, activation, back: fullLoadIsBack(activation, backHref),
+    })
     const left = leaveStyle(win, style)
     if (!transition) return
     if (!left) {

data/app/javascript/studio/pinned_stack.js

@@ -37,6 +37,11 @@
 // SIZE something as tall as the header; use --nav-bottom to START something
 // underneath it. Same distinction for --pin-<name>-h vs --pin-<name>-bottom.
 //
+// THE SECTION LAYER (studio/_section_header, docs/PAGE_HEADER.md) IS THE ONE LAYER
+// THAT IS NOT A data-pin. A page has many section headers and only one is stuck, so
+// each carries `data-pin-section`, and together they publish as one layer, `section`.
+// See stuckSection below.
+//
 // Started once per document by studio/application. The listeners it adds live
 // for the document, and a Turbo visit republishes through them rather than
 // starting it again.
@@ -152,6 +157,62 @@ export function documentIndex(list, el) {
   return list.length;
 }
 
+// THE SECTION LAYER: MANY HEADERS, ONE LAYER, ONLY THE STUCK ONE COUNTS.
+//
+// A section header is sticky inside its own <section>, so the browser does the
+// swap: the next section's header arrives as the last one is pushed out. It joins
+// the stack so that a table's sticky header and any other reader of
+// --pin-stack-bottom sit under it. It cannot be a plain [data-pin]: composed() takes
+// the lowest edge of every layer, so a header waiting below the fold would drag
+// --pin-stack-bottom down the page, and headers sharing a name would overwrite each
+// other's values.
+//
+// So all of them are one layer named `section`, always in the registry while any is
+// on the page. The roster never changes per swap, so a swap is not a structural write,
+// and --pin-section-top, which every header positions off, stays published when none
+// is stuck. That layer's height is 0 until one is stuck, and then it is the part of the
+// bar still below the layers above, so a header being pushed out gives its room back
+// frame by frame.
+//
+// rects are { top, bottom, parentTop, parentBottom }, in page order; line is
+// --pin-section-top. A header is stuck once it has left its place in the flow and part
+// of it still shows below the line. Its section's top is that place, since it is the
+// section's first child and the section has no top padding.
+//
+// NEITHER FACT READS THE HEADER'S OWN EDGE AGAINST THE LINE. While the navbar collapses
+// the line moves first and the header's `top` follows a publish later, so a comparison
+// would drop the bar for the whole collapse, and a bottom read off the rect would be
+// published one step stale, with nothing left to correct it once the page is still. So
+// the bar's bottom is what sticky will make it: one height under the line, or the end of
+// its section while that pushes it out.
+export function sectionBottom(r, line) {
+  return Math.min(line + (r.bottom - r.top), r.parentBottom);
+}
+
+export function stuckSection(rects, line) {
+  var found = -1;
+  for (var i = 0; i < rects.length; i++) {
+    var r = rects[i];
+    if (r.top - r.parentTop > 0.5 && sectionBottom(r, line) > line + 0.5) found = i;
+  }
+  return found;
+}
+
+function measureSections(nodes, line) {
+  // Below the short-screen floor, or before the publisher runs, the CSS leaves these in
+  // the flow (engine.css, @utility section-header). A header scrolling past the line
+  // there is not stuck, so it must not count.
+  if (window.getComputedStyle(nodes[0]).position !== 'sticky') return null;
+  var rects = [];
+  for (var i = 0; i < nodes.length; i++) {
+    var r = nodes[i].getBoundingClientRect();
+    var parent = nodes[i].parentElement.getBoundingClientRect();
+    rects.push({ top: r.top, bottom: r.bottom, parentTop: parent.top, parentBottom: parent.bottom });
+  }
+  var at = stuckSection(rects, line);
+  return at < 0 ? null : { el: nodes[at], bottom: sectionBottom(rects[at], line) };
+}
+
 // 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
@@ -168,8 +229,9 @@ export function documentIndex(list, el) {
 // reference IMPOSSIBLE rather than merely unlikely: there is no window between
 // a DOM patch and a re-scan in which this can be pointed at the wrong node.
 //
-// Returns { pins, stack, timeline }: every layer measured and composed, the
-// stack's bottom, and whether the header is on the scroll timeline.
+// Returns { pins, stack, timeline, travel, sections, stuck }: every layer measured and
+// composed, the stack's bottom, whether the header is on the scroll timeline and how
+// far it travels, the section headers, and which of them is stuck.
 export function readStack() {
   var header = document.querySelector('header');
   var timeline = onTimeline(header);
@@ -191,11 +253,28 @@ export function readStack() {
   // never publish at all. Both live consumers own their header, so it is
   // adopted as a pin even when it does not ask to be.
   if (header && !headerPinned) list.splice(documentIndex(list, header), 0, measurePin(header, 'nav', true, timeline));
+  // In the registry at height 0 first, so the composition says where its line is.
+  var sections = document.querySelectorAll('[data-pin-section]');
+  var section = null;
+  if (sections.length) {
+    section = { el: sections[0], name: 'section', legacy: false, h: 0, bottom: 0 };
+    list.splice(documentIndex(list, sections[0]), 0, section);
+  }
+  var stack = timeline ? pinnedAt(list) : composed(list);
+  var stuck = section ? measureSections(sections, section.top) : null;
+  if (stuck) {
+    section.el = stuck.el;
+    section.h = stuck.bottom - section.top;
+    section.bottom = stuck.bottom;
+    stack = timeline ? pinnedAt(list) : composed(list);
+  }
   return {
     pins: list,
-    stack: timeline ? pinnedAt(list) : composed(list),
+    stack: stack,
     timeline: timeline,
-    travel: timeline ? timelineTravel(header) : 0
+    travel: timeline ? timelineTravel(header) : 0,
+    sections: sections,
+    stuck: stuck ? stuck.el : null
   };
 }
 
@@ -414,6 +493,9 @@ export function startPinnedStack() {
     settleTimer = null;
     publishAll();
     releaseFollowers();
+    // That publish measured the layers while they still held their last copies. Given back,
+    // they move to the root's values, so their edges are read once more.
+    schedule();
   }
 
   // The registry and the measurement are module-level (readStack, measurePin
@@ -505,12 +587,38 @@ export function startPinnedStack() {
     }
   }
 
+  // WHO WEARS THE BAR, written after every read of the publish. The box does not change
+  // with the attribute, so this resizes nothing and moves nothing. The root's attribute
+  // squares the page row's corners against the bar under it (engine.css, glass).
+  function syncSections(reading) {
+    for (var i = 0; i < reading.sections.length; i++) {
+      var node = reading.sections[i];
+      var on = node === reading.stuck;
+      if (node.hasAttribute('data-stuck') !== on) node.toggleAttribute('data-stuck', on);
+    }
+    var root = document.documentElement;
+    if (root.hasAttribute('data-pin-section-stuck') !== !!reading.stuck) root.toggleAttribute('data-pin-section-stuck', !!reading.stuck);
+  }
+
   var lastPublished = null;
+  var lastTops = null;
   function publishAll() {
+    // What lets a section header stick at all (engine.css): with no publisher its bar
+    // would never come, and it would lay a clear title over the page. Before the read,
+    // so the first publish on a restored scroll already sees it sticky.
+    var html = document.documentElement;
+    if (!html.hasAttribute('data-pin-live')) html.setAttribute('data-pin-live', '');
     var reading = readStack();
     var pins = reading.pins;
     write(pins, reading.stack, reading.timeline, reading.travel);
+    syncSections(reading);
     syncObserver(pins);
+    // A LAYER UNDER A LAYER SETTLES ONE PUBLISH LATER. A new --pin-page-top moves the page
+    // row without resizing it, so nothing wakes the publisher to read the row's new edge,
+    // and the layer under the row would keep a stale line once the page is still. So a
+    // publish that moved any layer's top asks for one more frame. It ends when none moved.
+    var tops = pins.map(function (p) { return p.top; }).join('|');
+    if (tops !== lastTops) { lastTops = tops; schedule(); }
     var key = publishedKey(reading);
     if (key !== lastPublished) {
       lastPublished = key;

data/app/javascript/studio/pull_to_refresh.js

@@ -0,0 +1,147 @@
+// studio/pull_to_refresh: pull the page down from its top to reload it
+// (docs/LOADER.md, "Pull to refresh"). Phone widths and touch only: the
+// controller arms itself where PHONE_QUERY matches and does nothing anywhere
+// else, so a desktop, a mouse or a keyboard never meets it. The markup is
+// studio_pull_to_refresh:
+//
+//   <div class="studio-pull-refresh" data-studio-controller="pull-to-refresh"
+//        data-pull-to-refresh-frame="feed">            (optional: reload one frame)
+//     <span class="studio-pull-refresh-indicator" hidden>...</span>
+//     <p class="sr-only" role="status" data-pull-to-refresh-status></p>
+//     ...the page...
+//   </div>
+//
+//   the pull     a touch that starts with the page at its top and moves down
+//                drags the indicator; --studio-pull is the distance over
+//                THRESHOLD_PX, eased so it resists the finger.
+//   the release  past the threshold it refreshes: the named frame's reload(),
+//                else a Turbo visit to this URL with action "replace" (which the
+//                page-load overlay never shows for). Short of it, it settles back.
+//   the end      turbo:frame-load or turbo:load clears the indicator; so does
+//                MAX_SPIN_MS, so a refresh that fails never leaves it spinning.
+//
+// The browser's own pull (Chrome on Android reloads on overscroll) is turned
+// off with overscroll-behavior-y while the controller is armed, so one pull
+// never refreshes twice.
+//
+// It imports nothing; test/javascript/pull_to_refresh.test.mjs loads it as a
+// data: module.
+
+export const PHONE_QUERY = "(pointer: coarse) and (max-width: 640px)"
+export const THRESHOLD_PX = 72
+export const MAX_SPIN_MS = 10000
+
+// How far a finger `dy` pixels down has pulled, 0..1.2 of the threshold. The
+// first half follows the finger; past it the pull resists.
+export function pullProgress(dy) {
+  if (!(dy > 0)) return 0
+  const raw = dy / THRESHOLD_PX
+  const eased = raw <= 0.5 ? raw : 0.5 + (raw - 0.5) * 0.55
+  return Math.min(1.2, Math.round(eased * 1000) / 1000)
+}
+
+// A release refreshes once the eased pull reaches the threshold.
+export function shouldRefresh(progress) {
+  return progress >= 1
+}
+
+export function phoneTouch(win) {
+  return !!(win && typeof win.matchMedia === "function" && win.matchMedia(PHONE_QUERY).matches)
+}
+
+// Whether a touch on `target` began inside a scroller below `root` that is not
+// at its top: that drag scrolls the scroller back up, so it is not a pull.
+export function insideScroller(target, root) {
+  for (let el = target; el && el !== root; el = el.parentElement) if (el.scrollTop > 0) return true
+  return false
+}
+
+// Wires one container. Answers a stop function, or null where it does not arm.
+export function watchPullToRefresh(root, win, doc) {
+  win = win || window
+  doc = doc || document
+  if (!phoneTouch(win)) return null
+
+  const indicator = root.querySelector(".studio-pull-refresh-indicator")
+  const status = root.querySelector("[data-pull-to-refresh-status]")
+  const label = root.getAttribute("data-pull-to-refresh-label") || "Refreshing"
+  const html = doc.documentElement
+  const previousOverscroll = html.style.overscrollBehaviorY
+  html.style.overscrollBehaviorY = "contain"
+
+  let startY = null
+  let progress = 0
+  let spinTimer = null
+
+  function setPull(value) {
+    progress = value
+    if (indicator) {
+      indicator.hidden = value === 0 && root.getAttribute("data-pull-state") !== "refreshing"
+      indicator.style.setProperty("--studio-pull", String(Math.min(1, value)))
+    }
+  }
+
+  function finish(event) {
+    const frameId = root.getAttribute("data-pull-to-refresh-frame")
+    if (event && event.type === "turbo:frame-load" && (!frameId || event.target.id !== frameId)) return
+    if (root.getAttribute("data-pull-state") !== "refreshing") return
+    clearTimeout(spinTimer)
+    root.setAttribute("data-pull-state", "settling")
+    if (status) status.textContent = ""
+    setPull(0)
+  }
+
+  function refresh() {
+    root.setAttribute("data-pull-state", "refreshing")
+    if (indicator) indicator.hidden = false
+    if (status) status.textContent = label
+    spinTimer = setTimeout(finish, MAX_SPIN_MS)
+    const frameId = root.getAttribute("data-pull-to-refresh-frame")
+    const frame = frameId && doc.getElementById(frameId)
+    if (frame && typeof frame.reload === "function") frame.reload()
+    else if (win.Turbo && typeof win.Turbo.visit === "function") win.Turbo.visit(win.location.href, { action: "replace" })
+    else win.location.reload()
+  }
+
+  function onStart(event) {
+    if (root.getAttribute("data-pull-state") === "refreshing") return
+    if (event.touches.length !== 1 || (win.scrollY || 0) > 0 || insideScroller(event.target, root)) { startY = null; return }
+    startY = event.touches[0].clientY
+    root.setAttribute("data-pull-state", "pulling")
+  }
+
+  function onMove(event) {
+    if (startY === null) return
+    const dy = event.touches[0].clientY - startY
+    if (dy <= 0 || (win.scrollY || 0) > 0) { setPull(0); return }
+    // Holding the page still while the indicator follows the finger.
+    if (event.cancelable) event.preventDefault()
+    setPull(pullProgress(dy))
+  }
+
+  function onEnd() {
+    if (startY === null) return
+    startY = null
+    if (shouldRefresh(progress)) { refresh(); return }
+    root.setAttribute("data-pull-state", "settling")
+    setPull(0)
+  }
+
+  root.addEventListener("touchstart", onStart, { passive: true })
+  root.addEventListener("touchmove", onMove, { passive: false })
+  root.addEventListener("touchend", onEnd)
+  root.addEventListener("touchcancel", onEnd)
+  doc.addEventListener("turbo:frame-load", finish)
+  doc.addEventListener("turbo:load", finish)
+
+  return function stop() {
+    clearTimeout(spinTimer)
+    html.style.overscrollBehaviorY = previousOverscroll
+    root.removeEventListener("touchstart", onStart)
+    root.removeEventListener("touchmove", onMove)
+    root.removeEventListener("touchend", onEnd)
+    root.removeEventListener("touchcancel", onEnd)
+    doc.removeEventListener("turbo:frame-load", finish)
+    doc.removeEventListener("turbo:load", finish)
+  }
+}