studio-engine 0.132.0 → 0.133.0

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

@@ -25,14 +25,33 @@
 // scroll-initial-target (engine.css); elsewhere connect() jumps there, with no glide
 // and nothing in the status line. A row already moved (the browser's own start, a
 // restored scroll, a #fragment inside it) is left where it is.
+//
+// A LOOPING row (loop:, data-carousel-loop) wraps: Next at the last stop goes back
+// to the first, Previous at the first to the last, and neither arrow is ever
+// aria-disabled. There are no cloned slides, so a screen reader reads each once:
+// the row glides back across itself.
+//
+// AUTOPLAY (autoplay: seconds, data-carousel-autoplay) moves the row one stop each
+// interval. It holds still while the pointer is over the slides, while keyboard focus
+// is in it, while the tab is hidden or the row is off screen, and after a swipe,
+// wheel, arrow, dot or key until the reader has left it alone a while (idleDelay).
+// The pause button (WCAG 2.2.2) stops it until pressed again; under reduced motion
+// the row starts stopped. A move by autoplay writes nothing to the status line
+// (APG: a rotating carousel does not announce). Without loop it stops at the end.
 import { Controller } from "@hotwired/stimulus"
-import { TOLERANCE, centerStops, currentStop, hiddenEnds, keyAction, ownsKey, perPage, positionText, startStop, stops, targetStop } from "studio/carousel"
+import {
+  TOLERANCE, autoplayRunning, autoplaySeconds, autoplayStop, centerStops, currentStop, hiddenEnds, idleDelay,
+  initialReasons, keyAction, ownsKey, perPage, positionText, startStop, stops, targetStop, toggleLabel, withReason
+} from "studio/carousel"
+
+const REDUCE = "(prefers-reduced-motion: reduce)"
 
 export default class extends Controller {
-  static targets = ["track", "slide", "prev", "next", "dot", "status"]
+  static targets = ["track", "slide", "prev", "next", "dot", "status", "toggle"]
 
   connect() {
     this.schedule = this.schedule.bind(this)
+    this.loop = this.element.hasAttribute("data-carousel-loop")
     this.trackTarget.addEventListener("scroll", this.schedule, { passive: true })
     if (typeof ResizeObserver === "function") {
       this.observer = new ResizeObserver(this.schedule)
@@ -41,6 +60,7 @@ export default class extends Controller {
     this.element.setAttribute("data-carousel-ready", "")
     this.openAtStart()
     this.sync()
+    this.startAutoplay()
   }
 
   openAtStart() {
@@ -65,6 +85,112 @@ export default class extends Controller {
     this.observer?.disconnect()
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
+    this.stopAutoplay()
+  }
+
+  // -- autoplay ---------------------------------------------------------------
+
+  startAutoplay() {
+    this.seconds = autoplaySeconds(this.element.dataset.carouselAutoplay)
+    if (this.seconds === null) return
+
+    this.motion = window.matchMedia?.(REDUCE)
+    this.reasons = initialReasons({ reducedMotion: !!this.motion?.matches, hidden: document.hidden })
+    this.listeners = [
+      [this.trackTarget, "pointerenter", (event) => { if (event.pointerType !== "touch") this.pause("hover", true) }],
+      [this.trackTarget, "pointerleave", (event) => { if (event.pointerType !== "touch") this.pause("hover", false) }],
+      [this.element, "focusin", (event) => this.pause("focus", this.keyboardFocus(event.target))],
+      [this.element, "focusout", (event) => { if (!this.element.contains(event.relatedTarget)) this.pause("focus", false) }],
+      [this.trackTarget, "pointerdown", () => this.interacted()],
+      [this.trackTarget, "wheel", () => this.interacted()],
+      [this.trackTarget, "touchstart", () => this.interacted()],
+      [document, "visibilitychange", () => this.pause("hidden", document.hidden)],
+      [this.motion, "change", (event) => { if (event.matches) this.pause("stopped", true) }]
+    ].filter(([target]) => target?.addEventListener)
+    this.listeners.forEach(([target, type, handler]) => target.addEventListener(type, handler, { passive: true }))
+
+    if (typeof IntersectionObserver === "function") {
+      this.viewport = new IntersectionObserver(([entry]) => this.pause("offscreen", !entry.isIntersecting))
+      this.viewport.observe(this.element)
+    }
+    this.refresh()
+  }
+
+  stopAutoplay() {
+    this.listeners?.forEach(([target, type, handler]) => target.removeEventListener(type, handler))
+    this.listeners = null
+    this.viewport?.disconnect()
+    this.viewport = null
+    clearTimeout(this.timer)
+    clearTimeout(this.idle)
+    this.timer = this.idle = null
+  }
+
+  // Focus by keyboard holds the row; a mouse click that focuses an arrow does not.
+  // The pause button is the exception: a reader who tabs to it and presses Play
+  // means it to play.
+  keyboardFocus(target) {
+    if (this.hasToggleTarget && this.toggleTarget.contains(target)) return false
+    try { return target.matches(":focus-visible") } catch { return true }
+  }
+
+  pause(reason, on) {
+    if (this.seconds === null || !this.reasons) return
+    this.reasons = withReason(this.reasons, reason, on)
+    this.refresh()
+  }
+
+  // A swipe, a wheel, an arrow, a dot or a key: hold still until the reader has
+  // left the row alone for idleDelay.
+  interacted() {
+    if (this.seconds === null || !this.reasons) return
+    clearTimeout(this.idle)
+    this.idle = setTimeout(() => { this.idle = null; this.pause("interaction", false) }, idleDelay(this.seconds))
+    this.pause("interaction", true)
+  }
+
+  // The pause button.
+  toggle() {
+    if (this.seconds === null || !this.reasons) return
+    const stopped = !this.reasons.has("stopped")
+    if (!stopped) {
+      // Play at the end of a row that does not loop starts it again from the first.
+      this.sync()
+      if (!this.loop && autoplayStop(this.current, this.positions.length, false) === null && this.current > 0) {
+        this.scrollToStop(0, { announce: false })
+      }
+    }
+    this.pause("stopped", stopped)
+  }
+
+  refresh() {
+    const running = autoplayRunning(this.seconds, this.reasons)
+    const stopped = this.reasons.has("stopped")
+    this.element.toggleAttribute("data-carousel-playing", running)
+    if (this.hasToggleTarget) {
+      this.toggleTarget.setAttribute("aria-label", toggleLabel(stopped))
+      this.toggleTarget.toggleAttribute("data-carousel-stopped", stopped)
+    }
+    if (!running) {
+      clearTimeout(this.timer)
+      this.timer = null
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.tick(), this.seconds * 1000)
+    }
+  }
+
+  tick() {
+    this.timer = null
+    this.sync()
+    const count = this.positions.length
+    const to = autoplayStop(this.current, count, this.loop)
+    if (to === null && count > 1) {
+      // The end of a row that does not loop: autoplay is done until Play.
+      this.pause("stopped", true)
+      return
+    }
+    if (to !== null) this.scrollToStop(to, { announce: false })
+    this.refresh()
   }
 
   schedule() {
@@ -104,8 +230,10 @@ export default class extends Controller {
     this.element.toggleAttribute("data-carousel-static", positions.length < 2)
     track.toggleAttribute("data-fade-start", ends.start)
     track.toggleAttribute("data-fade-end", ends.end)
-    if (this.hasPrevTarget) this.prevTarget.setAttribute("aria-disabled", String(!ends.start))
-    if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!ends.end))
+    // A looping row never disables an arrow: each end leads round to the other.
+    const wraps = this.loop && positions.length > 1
+    if (this.hasPrevTarget) this.prevTarget.setAttribute("aria-disabled", String(!wraps && !ends.start))
+    if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!wraps && !ends.end))
     if (this.element.classList.contains("carousel-spotlight")) {
       this.slideTargets.forEach((slide, index) => slide.toggleAttribute("data-current", index === this.current))
     }
@@ -121,6 +249,7 @@ export default class extends Controller {
   next() { this.move("next") }
 
   goTo(event) {
+    this.interacted()
     this.sync()
     this.scrollToStop(Number(event.currentTarget.dataset.carouselIndex))
   }
@@ -139,20 +268,22 @@ export default class extends Controller {
   // A press that goes nowhere (an arrow at its end, Home at the start) scrolls
   // nothing and says nothing: the status line speaks only when the row moves.
   move(action) {
+    this.interacted()
     this.sync()
-    const to = targetStop(action, this.current, this.page, this.positions.length)
+    const to = targetStop(action, this.current, this.page, this.positions.length, this.loop)
     if (to === this.current) return
     this.scrollToStop(to)
   }
 
-  scrollToStop(index) {
+  // announce: false for autoplay, which moves the row without a word.
+  scrollToStop(index, { announce = true } = {}) {
     const left = this.positions[index]
     if (left === undefined) return
 
-    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+    const reduce = window.matchMedia?.(REDUCE).matches
     this.trackTarget.scrollTo({ left, behavior: reduce ? "auto" : "smooth" })
 
-    if (!this.hasStatusTarget) return
+    if (!announce || !this.hasStatusTarget) return
     const total = this.slideTargets.length
     const last = index === this.positions.length - 1
     const first = last ? Math.max(0, total - this.page) : index

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

@@ -9,8 +9,14 @@
 // row's tabs are links, so they work without it. If it fails to load, the sentinel
 // carries data-studio-controller-failed and engine.css gives the row its bar at
 // all times, so a stuck row never lays a transparent title over the page.
+//
+// It also keeps each quick-links menu's button honest: aria-expanded follows the
+// popover, ArrowDown from the button walks into the list, and where the browser has
+// no anchor positioning it places the list under the button. The popover itself
+// opens, closes on Escape and gives focus back with no script, so a failed load
+// leaves a menu that still works.
 import { Controller } from "@hotwired/stimulus"
-import { hiddenEnds, isStuck, revealBy, sentinelMarksThePlace } from "studio/page_header"
+import { hiddenEnds, isStuck, menuPlacement, revealBy, sentinelMarksThePlace } from "studio/page_header"
 
 export default class extends Controller {
   connect() {
@@ -22,6 +28,7 @@ export default class extends Controller {
     window.addEventListener("resize", this.schedule, { passive: true })
     this.tabs?.addEventListener("scroll", this.schedule, { passive: true })
     this.revealOpenTab()
+    this.connectMenus()
     this.sync()
   }
 
@@ -31,6 +38,53 @@ export default class extends Controller {
     this.tabs?.removeEventListener("scroll", this.schedule)
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
+    this.disconnectMenus()
+  }
+
+  connectMenus() {
+    this.menus = [...this.row.querySelectorAll(".page-header-menu")].map((menu) => {
+      const button = menu.querySelector("[popovertarget]")
+      const list = menu.querySelector("[popover]")
+      if (!button || !list) return null
+      button.setAttribute("aria-expanded", "false")
+      const onToggle = (event) => this.menuToggled(button, list, event.newState === "open")
+      const onKey = (event) => {
+        if (event.key !== "ArrowDown") return
+        event.preventDefault()
+        if (!list.matches(":popover-open")) list.showPopover?.()
+        list.querySelector("a")?.focus()
+      }
+      list.addEventListener("toggle", onToggle)
+      button.addEventListener("keydown", onKey)
+      return { button, list, onToggle, onKey }
+    }).filter(Boolean)
+  }
+
+  disconnectMenus() {
+    for (const { button, list, onToggle, onKey } of this.menus || []) {
+      list.removeEventListener("toggle", onToggle)
+      button.removeEventListener("keydown", onKey)
+      if (list.matches?.(":popover-open")) list.hidePopover?.()
+    }
+    this.menus = []
+  }
+
+  menuToggled(button, list, open) {
+    button.setAttribute("aria-expanded", String(open))
+    if (open) {
+      if (!anchorsSupported()) this.placeMenu(button, list)
+      return
+    }
+    // The browser gives focus back on Escape; a focus left on nothing comes back too.
+    if (document.activeElement === document.body || list.contains(document.activeElement)) button.focus()
+  }
+
+  placeMenu(button, list) {
+    const place = menuPlacement(button.getBoundingClientRect(), list.getBoundingClientRect(),
+      { width: window.innerWidth, height: window.innerHeight })
+    list.style.top = `${place.top}px`
+    list.style.left = `${place.left}px`
+    list.style.right = "auto"
   }
 
   schedule() {
@@ -46,6 +100,11 @@ export default class extends Controller {
     const ends = this.tabs ? hiddenEnds(this.tabs) : null
 
     this.row.toggleAttribute("data-stuck", stuck)
+    if (!anchorsSupported()) {
+      for (const { button, list } of this.menus || []) {
+        if (list.matches(":popover-open")) this.placeMenu(button, list)
+      }
+    }
     if (!ends) return
     this.tabs.toggleAttribute("data-fade-start", ends.start)
     this.tabs.toggleAttribute("data-fade-end", ends.end)
@@ -72,3 +131,7 @@ export default class extends Controller {
     this.tabs.scrollLeft += revealBy(this.tabs.getBoundingClientRect(), open.getBoundingClientRect())
   }
 }
+
+function anchorsSupported() {
+  return typeof CSS !== "undefined" && CSS.supports?.("anchor-name: --a") && CSS.supports("position-anchor: --a")
+}

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

@@ -6,8 +6,13 @@
 //       <a href="#theme" data-style-section-nav-target="link">Theme</a>
 //
 // Registered by studio/style_guide, which only the style guide loads.
+//
+// A tab's click is studio/in_page_links': a smooth scroll down the page. The clicked tab
+// holds the highlight until that scroll settles, so the row does not run through every tab
+// the scroll passes on its way.
 import { Controller } from "@hotwired/stimulus"
 import { activeIndex } from "studio/style_section_nav"
+import { SCROLL_EVENT, SCROLL_END_EVENT } from "studio/in_page_links"
 
 const ACTIVE = "btn-primary"
 const REST = "btn-neutral"
@@ -22,14 +27,21 @@ export default class extends Controller {
 
   connect() {
     this.schedule = this.schedule.bind(this)
+    this.hold = this.hold.bind(this)
+    this.release = this.release.bind(this)
     window.addEventListener("scroll", this.schedule, { passive: true })
     window.addEventListener("resize", this.schedule)
+    this.element.addEventListener(SCROLL_EVENT, this.hold)
+    document.addEventListener(SCROLL_END_EVENT, this.release)
     this.sync()
   }
 
   disconnect() {
     window.removeEventListener("scroll", this.schedule)
     window.removeEventListener("resize", this.schedule)
+    this.element.removeEventListener(SCROLL_EVENT, this.hold)
+    document.removeEventListener(SCROLL_END_EVENT, this.release)
+    this.held = null
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
   }
@@ -42,7 +54,21 @@ export default class extends Controller {
     })
   }
 
+  hold(event) {
+    const link = event.detail && event.detail.link
+    if (!this.linkTargets.includes(link)) return
+    this.held = link
+    this.highlight(link)
+  }
+
+  release() {
+    if (!this.held) return
+    this.held = null
+    this.sync()
+  }
+
   sync() {
+    if (this.held) return
     const links = this.linkTargets
     const tops = links.map((link) => {
       const section = document.getElementById(link.getAttribute("href").slice(1))

data/app/javascript/studio/in_page_links.js

@@ -0,0 +1,308 @@
+// studio/in_page_links: a link to a place on the page the reader is on scrolls there. It
+// does not load the page again (docs/PAGE_HEADER.md, "In-page links").
+//
+// Alex McRitchie, 2026-11-06, on the style guide's section pills: "The system needs to
+// understand when a scroll down is the solution rather than a page change."
+//
+// WHY THE ENGINE HAS TO DO THIS. Turbo 8 does not treat a link to "#section" on the same
+// path as a jump: its Navigator.locationWithActionIsSamePage returns false, so the click is a
+// full Turbo visit. It fetches the page, renders it again, fires turbo:visit (the loader and
+// the page transition hear it) and lands with a cut. That reads as a page load.
+//
+// So a plain click on a link whose address is this page (origin, path and query) with a
+// #fragment whose element exists is taken here: no visit, a smooth scroll to the element
+// under the pinned stack, the fragment pushed onto history, and focus moved to the target.
+// Reduced motion jumps. Every other link is left alone, for Turbo or the browser.
+//
+// THE LISTENER BUBBLES, ON THE DOCUMENT. Turbo follows a link from a bubble listener on the
+// window, which runs after this one and skips a click whose default is prevented. A
+// component's own handler on the link (a tab that switches a panel by its hash, an Alpine
+// @click.prevent) runs before this one, so a click it took is never taken here.
+//
+// BACK. Turbo turns history's scroll restoration to "manual", and on a popstate with Turbo's
+// state it starts a restore visit: a second page load. So an entry this module pushed carries
+// Turbo's own state, with the same restoration id, and a popstate between two entries of the
+// page on screen is taken here first (capture, at the window) and scrolls to the place the
+// reader left. A popstate to the page from another page is Turbo's, as before.
+//
+// It imports nothing; test/javascript/in_page_links.test.mjs loads it as a data: module.
+
+// The event a link's own controller hears: the scroll began, and where it is going.
+// detail: { link, target, hash }. It bubbles from the link.
+export const SCROLL_EVENT = "studio:in-page-scroll"
+// The scroll this module started has settled, or the reader took over. On the document.
+export const SCROLL_END_EVENT = "studio:in-page-scroll-end"
+// The state key on a history entry this module wrote: { scrollY } where the reader was.
+export const STATE_KEY = "studioInPage"
+// The mark on a target that took tabindex=-1 for focus here; engine.css draws no ring on it.
+export const FOCUS_MARK = "data-in-page-focus"
+// No scroll for this long ends the scroll, where the browser has no scrollend event.
+export const SETTLE_MS = 150
+// A scroll the reader never sees move still ends: the cap for a scroll that never starts.
+export const START_CAP_MS = 400
+// A scroll aims again at a target that moved more than this, at most this many times.
+export const AIM_SLACK_PX = 2
+export const MAX_AIMS = 6
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"
+const FOCUSABLE = "a[href], area[href], button, input, select, textarea, summary, iframe, [contenteditable], [tabindex]"
+
+// The fragment of `href` when it points into the page at `here`: same origin, path and query,
+// and a fragment that names something. Decoded, as the browser looks it up. Else null.
+export function samePageFragment(href, here) {
+  if (!href || !here) return null
+  let url, page
+  try {
+    page = new URL(here)
+    url = new URL(href, page)
+  } catch {
+    return null
+  }
+  if (url.origin !== page.origin || url.pathname !== page.pathname || url.search !== page.search) return null
+  if (url.hash.length < 2) return null
+  const raw = url.hash.slice(1)
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+// A click the browser would follow in place: the main button, no modifier, not already taken.
+export function plainClick(event) {
+  if (!event || event.defaultPrevented) return false
+  if (event.button !== undefined && event.button !== 0) return false
+  return !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+}
+
+// A link that asks for something other than a jump in this window: a new window or frame, a
+// download, Turbo off, a method or stream link, or a named Turbo frame.
+export function linkOptsOut(link) {
+  const target = link.getAttribute("target")
+  if (target && target.toLowerCase() !== "_self") return true
+  if (link.hasAttribute("download")) return true
+  if (link.hasAttribute("data-turbo-method") || link.hasAttribute("data-method")) return true
+  if (link.hasAttribute("data-turbo-stream")) return true
+  const frame = link.getAttribute("data-turbo-frame")
+  if (frame && frame !== "_top") return true
+  const drive = link.closest ? link.closest("[data-turbo]") : null
+  return !!drive && drive.getAttribute("data-turbo") === "false"
+}
+
+// The element a fragment names: its id, else an <a name>, as the browser finds it.
+export function findTarget(doc, fragment) {
+  if (!fragment) return null
+  const byId = doc.getElementById(fragment)
+  if (byId) return byId
+  const named = doc.getElementsByName ? [...doc.getElementsByName(fragment)] : []
+  return named.find((el) => el.tagName === "A") || null
+}
+
+// THE DECISION: the target to scroll to for this click on this link, or null to leave it.
+export function inPageTarget(event, link, doc, here) {
+  if (!link || !plainClick(event) || linkOptsOut(link)) return null
+  const fragment = samePageFragment(link.getAttribute("href"), here)
+  return fragment === null ? null : findTarget(doc, fragment)
+}
+
+// The history state for the entry a jump pushes. It keeps Turbo's restoration id, so a
+// restore from another page finds this page's snapshot, and moves its index one on.
+export function pushedState(current) {
+  const turbo = current && current.turbo
+  if (!turbo) return { [STATE_KEY]: {} }
+  return { turbo: { ...turbo, restorationIndex: (turbo.restorationIndex || 0) + 1 }, [STATE_KEY]: {} }
+}
+
+// Whether a popstate moves between two entries of the page on screen: the same address,
+// bar the fragment, and, under Turbo, the same restoration id as the page Turbo shows.
+export function samePagePop(state, shownId, url, shownUrl) {
+  if (!sameDocumentAddress(url, shownUrl)) return false
+  const turbo = state && state.turbo
+  if (!turbo) return !!(state && state[STATE_KEY])
+  return !!shownId && turbo.restorationIdentifier === shownId
+}
+
+export function sameDocumentAddress(a, b) {
+  try {
+    const one = new URL(a)
+    const two = new URL(b)
+    return one.origin === two.origin && one.pathname === two.pathname && one.search === two.search
+  } catch {
+    return false
+  }
+}
+
+// How far above the target the scroll stops. Its own scroll-margin-top first: the engine's
+// section-target and section-subtarget already know the stack. Without one, the bottom of the
+// pinned stack, measured now, so the target never lands under the chrome.
+export function marginFor(declared, stackBottom) {
+  if (declared > 0) return null
+  return stackBottom > 0 ? Math.round(stackBottom) : null
+}
+
+function focusTarget(target) {
+  if (!target.matches(FOCUSABLE)) {
+    target.setAttribute("tabindex", "-1")
+    target.setAttribute(FOCUS_MARK, "")
+    target.addEventListener("blur", () => {
+      target.removeAttribute("tabindex")
+      target.removeAttribute(FOCUS_MARK)
+    }, { once: true })
+  }
+  try {
+    target.focus({ preventScroll: true })
+  } catch {
+    // An element that cannot take focus leaves it where it was.
+  }
+}
+
+let installed = false
+
+export function installInPageLinks(doc) {
+  if (installed || !doc || !doc.defaultView) return false
+  installed = true
+  const win = doc.defaultView
+  let shownUrl = win.location.href
+  let settling = null
+
+  const turboHistory = () => (win.Turbo && win.Turbo.session && win.Turbo.session.history) || null
+  const shownId = () => {
+    const history = turboHistory()
+    if (history && history.restorationIdentifier) return history.restorationIdentifier
+    const state = win.history.state
+    return (state && state.turbo && state.turbo.restorationIdentifier) || null
+  }
+  const reduced = () => !!(win.matchMedia && win.matchMedia(REDUCED_MOTION).matches)
+
+  const scrollTo = (target, behavior) => {
+    const declared = parseFloat(win.getComputedStyle(target).scrollMarginTop) || 0
+    const stack = win.studioPinnedStack && win.studioPinnedStack.bottom ? win.studioPinnedStack.bottom() : 0
+    const margin = marginFor(declared, stack)
+    const inline = target.style.scrollMarginTop
+    if (margin !== null) target.style.scrollMarginTop = `${margin}px`
+    target.scrollIntoView({ behavior, block: "start" })
+    if (margin !== null) target.style.scrollMarginTop = inline
+  }
+  const pageTop = (target) => target.getBoundingClientRect().top + win.scrollY
+
+  // One jump, from its start to its end. The browser fixes a smooth scroll's end where the
+  // target was at the start. Content that grows on the way (a lazy frame the scroll passes,
+  // the navbar's collapse) moves the target, so the scroll aims again, up to MAX_AIMS times,
+  // until the reader takes over (a wheel, a touch, a key, a press). The end is the browser's
+  // scrollend where it has one, a quiet spell where not; then the end event, once.
+  const jump = (target, behavior) => {
+    if (settling) settling()
+    let quiet = null
+    let cap = null
+    let aims = 0
+    let reader = false
+    let live = true
+    let aimed = pageTop(target)
+    const takeOver = () => { reader = true }
+    const INPUTS = ["wheel", "touchstart", "keydown", "pointerdown"]
+    const reaim = () => {
+      if (reader || aims >= MAX_AIMS || Math.abs(pageTop(target) - aimed) <= AIM_SLACK_PX) return false
+      aims += 1
+      scrollTo(target, behavior)
+      aimed = pageTop(target)
+      return true
+    }
+    const wait = (ms) => {
+      win.clearTimeout(quiet)
+      quiet = win.setTimeout(end, ms)
+    }
+    const end = () => {
+      if (!live) return
+      // The target moved after the scroll stopped: aim once more and wait for that end.
+      if (reaim()) return wait(START_CAP_MS)
+      win.removeEventListener("scroll", onScroll)
+      win.removeEventListener("scrollend", end)
+      for (const name of INPUTS) win.removeEventListener(name, takeOver, true)
+      win.clearTimeout(quiet)
+      win.clearTimeout(cap)
+      live = false
+      if (settling === stop) settling = null
+      doc.dispatchEvent(new win.CustomEvent(SCROLL_END_EVENT))
+    }
+    const onScroll = () => {
+      win.clearTimeout(cap)
+      reaim()
+      wait(SETTLE_MS)
+    }
+    const stop = () => {
+      reader = true
+      end()
+    }
+    settling = stop
+    win.addEventListener("scroll", onScroll, { passive: true })
+    if ("onscrollend" in win) win.addEventListener("scrollend", end)
+    for (const name of INPUTS) win.addEventListener(name, takeOver, { capture: true, passive: true })
+    cap = win.setTimeout(end, START_CAP_MS)
+    scrollTo(target, behavior)
+    aimed = pageTop(target)
+  }
+
+  doc.addEventListener("click", (event) => {
+    const link = event.target && event.target.closest ? event.target.closest("a[href]") : null
+    const target = inPageTarget(event, link, doc, win.location.href)
+    if (!target) return
+    event.preventDefault()
+
+    const oldURL = win.location.href
+    const href = new URL(link.getAttribute("href"), oldURL).href
+    const behavior = reduced() ? "instant" : "smooth"
+    if (href !== oldURL) {
+      // The entry the reader leaves keeps where they were, for Back.
+      win.history.replaceState({ ...(win.history.state || {}), [STATE_KEY]: { scrollY: win.scrollY } }, "", oldURL)
+      const state = pushedState(win.history.state)
+      win.history.pushState(state, "", href)
+      const history = turboHistory()
+      if (history && state.turbo) {
+        history.currentIndex = state.turbo.restorationIndex
+        history.location = new URL(href)
+      }
+    }
+    shownUrl = win.location.href
+
+    // A scroll still running from an earlier click ends first, so its end cannot release this one.
+    if (settling) settling()
+    link.dispatchEvent(new win.CustomEvent(SCROLL_EVENT, { bubbles: true, detail: { link, target, hash: new URL(href).hash } }))
+    jump(target, behavior)
+    focusTarget(target)
+    if (href !== oldURL) win.dispatchEvent(new win.HashChangeEvent("hashchange", { oldURL, newURL: href }))
+  })
+
+  // Capture at the window runs ahead of Turbo's own popstate listener there.
+  win.addEventListener("popstate", (event) => {
+    const url = win.location.href
+    if (!samePagePop(event.state, shownId(), url, shownUrl)) {
+      shownUrl = url
+      return
+    }
+    shownUrl = url
+    // Turbo would start a restore visit; without Turbo the browser restores the scroll itself.
+    if (event.state && event.state.turbo) {
+      event.stopImmediatePropagation()
+      const history = turboHistory()
+      if (history) {
+        history.location = new URL(url)
+        history.currentIndex = event.state.turbo.restorationIndex
+      }
+    }
+    if (win.history.scrollRestoration !== "manual") return
+    const saved = event.state && event.state[STATE_KEY]
+    if (saved && typeof saved.scrollY === "number") {
+      win.scrollTo({ top: saved.scrollY, behavior: "instant" })
+      return
+    }
+    const fragment = samePageFragment(url, url)
+    const target = findTarget(doc, fragment)
+    if (target) scrollTo(target, "instant")
+    else if (!fragment) win.scrollTo({ top: 0, behavior: "instant" })
+  }, { capture: true })
+
+  // A Turbo visit shows another page, or this one anew.
+  doc.addEventListener("turbo:load", () => { shownUrl = win.location.href })
+  return true
+}
+
+if (typeof document !== "undefined") installInPageLinks(document)