studio-engine 0.135.2 → 0.136.0

data/app/javascript/studio/page_header_self_styled.js

@@ -0,0 +1,194 @@
+// studio/page_header_self_styled: the page-header controller's work for an app with no
+// Stimulus and no import map (config.page_header_self_styled, docs/PAGE_HEADER.md, "In a
+// plain-CSS app"). studio/page_header/_assets loads it by its own module tag, once per
+// page, beside the row's scoped CSS.
+//
+// For every studio/_page_header on the page it:
+//   - marks the row data-stuck once it has left its place in the flow, so the CSS gives
+//     it the bar;
+//   - marks which ends of the tabs hide a tab (data-fade-start, data-fade-end);
+//   - scrolls the open tab into view inside the tabs on load;
+//   - keeps each Links menu's aria-expanded in step with its popover, walks into the list
+//     on ArrowDown, and places the list where the browser has no anchor positioning.
+//
+// With no pinned stack on the page (window.studioPinnedStack), it also publishes
+// --nav-bottom from the document's first <header>, when that header is sticky or fixed,
+// so the row sticks under the app's own masthead. An app whose CSS sets --nav-bottom or
+// --pin-page-top keeps its own value.
+//
+// IT IMPORTS NOTHING, because a plain app may have no import map. The five measurements
+// below are studio/page_header's, copied; test/javascript/page_header_self_styled.test.mjs
+// holds the copies to the originals. It boots only in a browser, so the test can load it
+// as a data: module. A module runs once per document, so a Turbo visit rescans on
+// turbo:load.
+
+export function isStuck(rowTop, restTop) {
+  return rowTop - restTop > 0.5
+}
+
+export function sentinelMarksThePlace(parentDisplay) {
+  return !/flex|grid/.test(parentDisplay)
+}
+
+export function hiddenEnds({ scrollLeft, clientWidth, scrollWidth }) {
+  return {
+    start: scrollLeft > 1,
+    end: scrollLeft + clientWidth < scrollWidth - 1
+  }
+}
+
+export function revealBy(box, tab, margin = 32) {
+  if (tab.left < box.left) return tab.left - box.left - margin
+  if (tab.right > box.right) return tab.right - box.right + margin
+  return 0
+}
+
+export function menuPlacement(button, list, viewport, gap = 8) {
+  const below = viewport.height - button.bottom
+  const above = button.top
+  const top = below < list.height + gap && above > below
+    ? Math.max(gap, button.top - list.height - 4)
+    : button.bottom + 4
+  const left = Math.min(
+    Math.max(gap, button.right - list.width),
+    Math.max(gap, viewport.width - list.width - gap)
+  )
+  return { top, left }
+}
+
+// The bottom edge, in px, of the app's own masthead: the first header, when it is sticky
+// or fixed. 0 for any other header, or none.
+export function mastheadBottom(position, bottom) {
+  return position === "sticky" || position === "fixed" ? Math.max(0, bottom) : 0
+}
+
+function anchorsSupported() {
+  return typeof CSS !== "undefined" && !!CSS.supports &&
+    CSS.supports("anchor-name: --a") && CSS.supports("position-anchor: --a")
+}
+
+function boot() {
+  if (window.studioPageHeaderSelfStyled) {
+    window.studioPageHeaderSelfStyled.scan()
+    return
+  }
+
+  const root = document.documentElement
+  let rows = []
+  let frame = null
+  let ownsNavBottom = null
+
+  const publishNavBottom = () => {
+    if (window.studioPinnedStack) return
+    if (ownsNavBottom === null) {
+      const computed = getComputedStyle(root)
+      ownsNavBottom = !root.style.getPropertyValue("--nav-bottom") &&
+        !computed.getPropertyValue("--nav-bottom").trim() &&
+        !computed.getPropertyValue("--pin-page-top").trim()
+    }
+    if (!ownsNavBottom) return
+    const header = document.querySelector("header")
+    const bottom = header ? mastheadBottom(getComputedStyle(header).position, header.getBoundingClientRect().bottom) : 0
+    const value = `${Math.round(bottom * 100) / 100}px`
+    if (root.style.getPropertyValue("--nav-bottom") !== value) root.style.setProperty("--nav-bottom", value)
+  }
+
+  // The top of the row's place in the flow. In a flex or grid parent only the row can
+  // say, so it is unstuck for one read; no frame paints in between.
+  const restTop = ({ sentinel, row }) => {
+    if (sentinelMarksThePlace(getComputedStyle(sentinel.parentElement).display)) {
+      return sentinel.getBoundingClientRect().top
+    }
+    row.style.position = "static"
+    const top = row.getBoundingClientRect().top
+    row.style.position = ""
+    return top
+  }
+
+  const 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"
+  }
+
+  const sync = () => {
+    publishNavBottom()
+    rows = rows.filter((item) => item.row.isConnected)
+    for (const item of rows) {
+      item.row.toggleAttribute("data-stuck", isStuck(item.row.getBoundingClientRect().top, restTop(item)))
+      if (!anchorsSupported()) {
+        for (const { button, list } of item.menus) {
+          if (list.matches(":popover-open")) placeMenu(button, list)
+        }
+      }
+      if (!item.tabs) continue
+      const ends = hiddenEnds(item.tabs)
+      item.tabs.toggleAttribute("data-fade-start", ends.start)
+      item.tabs.toggleAttribute("data-fade-end", ends.end)
+    }
+  }
+
+  const schedule = () => {
+    if (frame) return
+    frame = requestAnimationFrame(() => {
+      frame = null
+      sync()
+    })
+  }
+
+  // A disclosure, not role="menu": the popover opens, closes on Escape and gives focus
+  // back with no script. This keeps aria-expanded honest and adds ArrowDown.
+  const wireMenu = (menu) => {
+    const button = menu.querySelector("[popovertarget]")
+    const list = menu.querySelector("[popover]")
+    if (!button || !list) return null
+    button.setAttribute("aria-expanded", "false")
+    list.addEventListener("toggle", (event) => {
+      const open = event.newState === "open"
+      button.setAttribute("aria-expanded", String(open))
+      if (open) {
+        if (!anchorsSupported()) placeMenu(button, list)
+        return
+      }
+      if (document.activeElement === document.body || list.contains(document.activeElement)) button.focus()
+    })
+    button.addEventListener("keydown", (event) => {
+      if (event.key !== "ArrowDown") return
+      event.preventDefault()
+      if (!list.matches(":popover-open")) list.showPopover?.()
+      list.querySelector("a")?.focus()
+    })
+    return { button, list }
+  }
+
+  const wire = (sentinel) => {
+    if (sentinel.hasAttribute("data-page-header-live")) return
+    const row = sentinel.nextElementSibling
+    if (!row || !row.classList.contains("page-header")) return
+    sentinel.setAttribute("data-page-header-live", "")
+    const tabs = row.querySelector(".page-header-tabs")
+    const menus = [...row.querySelectorAll(".page-header-menu")].map(wireMenu).filter(Boolean)
+    if (tabs) {
+      tabs.addEventListener("scroll", schedule, { passive: true })
+      const open = tabs.querySelector("[aria-current]")
+      if (open) tabs.scrollLeft += revealBy(tabs.getBoundingClientRect(), open.getBoundingClientRect())
+    }
+    rows.push({ sentinel, row, tabs, menus })
+  }
+
+  const scan = () => {
+    document.querySelectorAll(".page-header-sentinel").forEach(wire)
+    sync()
+  }
+
+  window.studioPageHeaderSelfStyled = { scan }
+  window.addEventListener("scroll", schedule, { passive: true })
+  window.addEventListener("resize", schedule, { passive: true })
+  document.addEventListener("turbo:load", scan)
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", scan)
+  else scan()
+}
+
+if (typeof window !== "undefined" && typeof document !== "undefined") boot()

data/app/javascript/studio/page_transitions.js

@@ -106,6 +106,15 @@ export function leaveStyle(win, style) {
   }
 }
 
+// A skip the engine chooses. Chrome rejects the skipped transition's `ready` with "Transition
+// was skipped" and leaves the rejection unhandled (measured: a pageerror whenever nothing
+// awaits `ready`). This skip is the engine's own decision, so that one rejection is expected
+// and handled here. A transition the engine did not skip is never touched.
+export function skipOwnTransition(transition) {
+  if (transition.ready && typeof transition.ready.catch === "function") transition.ready.catch(() => {})
+  transition.skipTransition()
+}
+
 // A slow image must not hold a click: past the cap the swap goes ahead.
 export function withCap(promise, ms, timer = setTimeout) {
   return Promise.race([promise, new Promise((done) => timer(done, ms))])
@@ -210,9 +219,11 @@ export function installPageTransitions(doc) {
 
   doc.addEventListener("turbo:visit", (event) => {
     root.dataset.pageTransitionVisit = ""
-    // Turbo opens its view transition before it reads turbo-visit-control. A response it will
-    // not render gets no turbo:before-render, so this stands, and that transition draws nothing.
-    // The full load after it plays the one motion. Left alone while a motion is still running.
+    // A response Turbo will not render gets no turbo:before-render, so this stands. Turbo
+    // opens no transition for it (studio/reload_visits takes the meta out of what it parses),
+    // and should one open on a path that guard does not see (a frame's reload visit), this
+    // makes it draw nothing. The full load after it plays the one motion. Left alone while a
+    // motion is still running.
     if (!root.dataset.pageTransition) root.dataset.pageTransition = STILL
     target = new URL(event.detail.url).pathname
     // A GET that redirects: Turbo renders the response, then replaces to the final address
@@ -231,17 +242,37 @@ export function installPageTransitions(doc) {
 
   // A page never visited: read its names from the response, ahead of the old page's picture.
   // Only a page with names of its own can share one, so every other page skips the parse.
+  //
+  // TURBO READS THE PAGE THROUGH THIS READ. Turbo starts its view transition one frame after
+  // its own read of the response resolves, and the browser takes the old page's picture then:
+  // the morph's name must be down by that moment. Turbo's responseHTML getter is a fresh
+  // response.clone().text() on each access, and nothing orders this module's read before
+  // Turbo's, so this read is put in its place (studio/reload_visits does the same): the read
+  // Turbo awaits is the one that has already named the morph. Measured without it: under an
+  // 8x CPU throttle, 2 of 6 visits started the transition with no name, and nothing morphed.
   doc.addEventListener("turbo:before-fetch-response", (event) => {
     if (event.target && event.target.tagName === "TURBO-FRAME") return
     if (!morphNames(doc).size) return
     const { fetchResponse } = event.detail
-    Promise.resolve(fetchResponse.responseHTML).then((html) => {
-      if (!html) return
-      const names = morphNames(new win.DOMParser().parseFromString(html, "text/html"))
-      const path = new URL(fetchResponse.response.url).pathname
-      known.set(path, names)
-      if (target && (path === target || fetchResponse.redirected)) predict(names)
-    }).catch(() => {})
+    const named = Promise.resolve(fetchResponse.responseHTML).then((html) => {
+      try {
+        if (!html) return html
+        const names = morphNames(new win.DOMParser().parseFromString(html, "text/html"))
+        const path = new URL(fetchResponse.response.url).pathname
+        known.set(path, names)
+        if (target && (path === target || fetchResponse.redirected)) predict(names)
+      } catch {
+        // A page this module cannot read morphs nothing; Turbo still renders it.
+      }
+      return html
+    })
+    // A failed read rejects for Turbo exactly as its own would; this module needs no answer.
+    named.catch(() => {})
+    try {
+      Object.defineProperty(fetchResponse, "responseHTML", { configurable: true, value: named })
+    } catch {
+      // A response that refuses the swap keeps Turbo's own read, and the race this closes.
+    }
   })
 
   // In capture, so the hold is in place before any other listener takes Turbo's resume.
@@ -305,7 +336,7 @@ export function installPageTransitions(doc) {
     const left = leaveStyle(win, style)
     if (!transition) return
     if (!left) {
-      transition.skipTransition()
+      skipOwnTransition(transition)
       return
     }
     markHeld(doc)

data/app/javascript/studio/reload_visits.js

@@ -0,0 +1,93 @@
+// studio/reload_visits: Turbo opens no view transition for a visit it will only reload.
+//
+// THE DEFECT. Smooth load (layouts/studio/_smooth_load) turns on Turbo's same-document view
+// transitions. Turbo starts the transition BEFORE it reads the response's head: its render
+// callback is what finds turbo-visit-control reload (turf-monster's /wallet and /account) or a
+// changed data-turbo-track="reload" asset, and then navigates by a full load. That navigation
+// can skip the transition while its `ready` promise is still pending. Turbo awaits only
+// `finished` (turbo-rails 2.0.23, turbo.js ViewTransitioner#renderChange), so `ready` rejects
+// with nobody listening: an unhandled "Transition was skipped" error on every such visit that
+// loses the race (turf-monster CI run 42447610386).
+//
+// THE FIX, AT THE CAUSE. Turbo starts a transition only when both the current page and the new
+// snapshot carry the view-transition meta (PageView#shouldTransitionTo). So when Turbo's own
+// renderer says it will not render a response, this takes that meta out of the HTML Turbo
+// parses. Turbo then swaps nothing in a transition and goes straight to its full load, which
+// plays the page transition once (docs/PAGE_TRANSITIONS.md, "Full page loads"). Only a page
+// Turbo was going to throw away is changed, and the page the full load brings is the server's
+// own. No promise is marked handled, so a real failure (a duplicate view-transition-name, a
+// render that throws) still surfaces.
+//
+// THE SEAM. turbo:before-fetch-response, the moment studio/loader also uses: Turbo awaits
+// fetchResponse.responseHTML right after it, so a promise put there is what Turbo parses. The
+// two compose in either order, since each reads the other's promise. A frame's response is left
+// alone: a frame never transitions, and its reload is a new fetch.
+//
+// It imports nothing; test/javascript/reload_visits.test.mjs loads it as a data: module.
+
+// The meta Turbo reads for a same-document transition: `view-transition` (same-origin), or
+// the `turbo-view-transition` setting. Not `view-transition-*` names of anything else.
+const TRANSITION_META = /<meta\b[^>]*\bname\s*=\s*["']?(?:turbo-)?view-transition(?![\w-])[^>]*>/gi
+const VISIT_CONTROL_RELOAD = /<meta[^>]*(turbo-visit-control[^>]*reload|reload[^>]*turbo-visit-control)/i
+
+// The head alone: Turbo's decision reads only the head, and the body is most of the bytes.
+export function headOf(html) {
+  const end = html.search(/<\/head\s*>/i)
+  return end < 0 ? html : html.slice(0, end)
+}
+
+export function prefersTransition(html) {
+  TRANSITION_META.lastIndex = 0
+  return TRANSITION_META.test(headOf(html))
+}
+
+// Whether Turbo would render this HTML as the next page. Asked of Turbo's own PageRenderer, so
+// the answer cannot drift from Turbo's (visit control, then the tracked assets). Without
+// Turbo's classes, the visit-control meta alone, the case a host sets on purpose.
+export function rendersAsPage(html, doc, turbo) {
+  const head = headOf(html)
+  if (turbo && turbo.PageRenderer && turbo.PageSnapshot) {
+    const current = turbo.PageSnapshot.fromElement(doc.documentElement)
+    const next = turbo.PageSnapshot.fromHTMLString(head)
+    return new turbo.PageRenderer(current, next, false).shouldRender
+  }
+  return !VISIT_CONTROL_RELOAD.test(head)
+}
+
+// The HTML Turbo should parse: unchanged, unless it carries the transition meta and Turbo will
+// not render it, and then the same HTML with that meta out of its head.
+export function withoutReloadTransition(html, doc, turbo) {
+  if (typeof html !== "string" || !prefersTransition(html)) return html
+  // A Turbo whose classes changed shape leaves the HTML as it came: the old behaviour, not a
+  // failed visit.
+  try {
+    if (rendersAsPage(html, doc, turbo)) return html
+  } catch {
+    return html
+  }
+  const head = headOf(html)
+  return head.replace(TRANSITION_META, "") + html.slice(head.length)
+}
+
+export function guardResponse(event, doc, turbo) {
+  if (event.target && event.target.tagName === "TURBO-FRAME") return false
+  const response = event.detail && event.detail.fetchResponse
+  if (!response || !response.isHTML) return false
+  const html = Promise.resolve(response.responseHTML).then((text) => withoutReloadTransition(text, doc, turbo))
+  Object.defineProperty(response, "responseHTML", { configurable: true, value: html })
+  return true
+}
+
+let installed = false
+
+export function installReloadVisits(doc) {
+  if (installed || !doc || !doc.addEventListener) return false
+  installed = true
+  doc.addEventListener("turbo:before-fetch-response", (event) => {
+    const win = doc.defaultView
+    guardResponse(event, doc, win && win.Turbo)
+  })
+  return true
+}
+
+if (typeof document !== "undefined") installReloadVisits(document)

data/app/models/studio/user_session.rb

@@ -1,21 +1,41 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Studio
   # One signed-in browser session: who, whether they were an admin, when it
   # started and when it was last seen. It is a cached record for the app's own
   # dashboard, kept on purpose without an IP, a user agent or a path.
   #
   # A new row starts after IDLE without a request. An open row is written at most
-  # once per THROTTLE, and the cookie remembers when, so a request inside that
-  # window runs no query at all.
+  # once per THROTTLE, and the cookie remembers when.
+  #
+  # A DEVICE SESSION YOU CAN END (docs/DEVICE_SESSIONS.md). The cookie store keeps
+  # the whole session in the browser, so a logout used to delete only the
+  # browser's copy: a copy of the pre-logout cookie still signed in. Each signed-in
+  # cookie now carries a random `sid` in its mark, and every row of that device
+  # session carries the same sid. A logout stamps `revoked_at` on those rows, and
+  # every signed-in request reads its sid's rows (one indexed query): a revoked
+  # row ends the sid for good, and so does no row at all: the request is signed
+  # out. Other devices have other sids, so they stay signed in.
   #
-  # Nil-safe, because the table comes from a migration the host runs: an app that
-  # has not run it records nothing and serves as before.
+  # Nil-safe, because the table and its columns come from migrations the host
+  # runs: an app without them records nothing, checks nothing and serves as
+  # before.
   class UserSession < ApplicationRecord
     self.table_name = "studio_user_sessions"
 
     IDLE = 30.minutes
     THROTTLE = 5.minutes
+    # A device session idle this long has its rows pruned, so its cookie no longer
+    # signs in: the user signs in again.
+    RETENTION = 90.days
+    PRUNE_EVERY = 1.hour
+    PRUNE_BATCH = 1_000
+    # A failed verdict writes at most one ErrorLog row per this window per
+    # process: a database fault fails every request, and the log must not add a
+    # write to each of them.
+    CHECK_FAILURE_LOG_EVERY = 5.minutes
 
     belongs_to :user, class_name: "::User", optional: true
 
@@ -27,50 +47,225 @@ module Studio
     def self.cookie_key = :"#{Studio.session_key}_session_mark"
 
     # Off under test unless a test asks: the row a first request writes would count in
-
     # every host's query-budget test, which measures the page and not this.
-
     cattr_accessor :record_in_test, default: false
 
+    # A signed-in cookie with no sid predates this change. Until this moment it is
+    # accepted and given a sid on its request, so the deploy signs nobody out;
+    # after it, such a cookie is signed out once. The bound matters: a copy of a
+    # pre-deploy cookie carries no sid, so without it that copy would stay
+    # replayable after the device logs out.
+    cattr_accessor :legacy_grace_until, default: Time.utc(2026, 12, 8)
 
-    def self.recording?
+    # When this process last pruned (prune_due!). Per process, so it costs nothing.
+    cattr_accessor :pruned_at, default: nil
 
-      !Rails.env.test? || record_in_test
+    # When this process last wrote an ErrorLog row for a failed verdict
+    # (log_check_failure). Per process, like pruned_at.
+    cattr_accessor :check_failure_logged_at, default: nil
 
+    def self.recording?
+      !Rails.env.test? || record_in_test
     end
 
-
     def self.available?
       connection.data_source_exists?(table_name)
     rescue ActiveRecord::ActiveRecordError, NoMethodError
       false
     end
 
+    # The table carries the sid and revoked_at columns. The schema cache and the
+    # model's column cache answer it, so a request pays no query for it.
+    def self.revocable?
+      return false unless connection.schema_cache.data_source_exists?(table_name)
+
+      names = column_names
+      names.include?("sid") && names.include?("revoked_at")
+    rescue ActiveRecord::ActiveRecordError, NoMethodError
+      false
+    end
+
+    # This app's mark in `store` (the session, or a plain Hash decoded from the
+    # cookie, as a cable connection reads it), as a string-keyed Hash.
+    def self.mark_in(store)
+      mark = store[cookie_key]
+      mark = store[cookie_key.to_s] if mark.nil? && store.is_a?(Hash)
+      mark.respond_to?(:to_h) ? mark.to_h.transform_keys(&:to_s) : {}
+    end
+
+    def self.new_sid = SecureRandom.urlsafe_base64(24)
+
+    # The verdict on a signed-in request, read before anything else runs. Answers
+    # [verdict, row]:
+    #
+    #   :live    the sid names a row that is not revoked (row is that row)
+    #   :ended   any row of the sid is revoked, or the sid has no row (pruned,
+    #            or never written); also a sid-less cookie past legacy_grace_until
+    #   :legacy  no sid, inside the grace: accepted, and track gives it one
+    #   :off     nothing to check (not recording, or no columns)
+    #
+    # One indexed query when the cookie carries a sid, none otherwise. A failure
+    # answers :off, so a database fault signs nobody out: the request's own user
+    # lookup needs the same database, and a copied cookie cannot cause the fault.
+    def self.verdict(store, now: Time.current)
+      return [:off, nil] unless recording? && revocable?
+
+      sid = mark_in(store)["sid"].presence
+      return [now < legacy_grace_until ? :legacy : :ended, nil] unless sid
+
+      # A revoked row sorts first: a row a request in flight wrote after the
+      # logout cannot bring the sid back.
+      row = where(sid: sid.to_s).order(Arel.sql("revoked_at IS NULL"), id: :desc).first
+      return [:ended, nil] if row.nil? || row.revoked_at
+
+      [:live, row]
+    rescue StandardError => e
+      Rails.logger&.warn("[user_session] verdict #{e.class}: #{e.message}")
+      log_check_failure(e, now)
+      [:off, nil]
+    end
+
+    # True when `store` names an ended device session (verdict :ended). The one
+    # check a host's ApplicationCable::Connection makes, since /cable reads the
+    # cookie outside the controller filter (docs/DEVICE_SESSIONS.md):
+    #
+    #   return nil if Studio::UserSession.respond_to?(:ended?) && Studio::UserSession.ended?(session)
+    #
+    # `store` is request.session or the Hash decoded from the cookie. :legacy and
+    # :off answer false, as they do for a page request. It never writes `store`.
+    def self.ended?(store, now: Time.current)
+      verdict(store, now: now).first == :ended
+    end
+
+    # Writes the verdict's failure to ErrorLog, at most once per
+    # CHECK_FAILURE_LOG_EVERY per process. The stamp is set before the write, so a
+    # write that fails too (the database is down) is not retried on every request.
+    # Never raises.
+    def self.log_check_failure(exception, now = Time.current)
+      return if check_failure_logged_at && check_failure_logged_at > now - CHECK_FAILURE_LOG_EVERY
+
+      self.check_failure_logged_at = now
+      ::ErrorLog.capture!(exception) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+    rescue StandardError => e
+      Rails.logger&.warn("[user_session] check failure not logged: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # Starts this device's session at a sign-in (ErrorHandling#set_app_session):
+    # writes its first row with a new sid and marks `store`, so the very next
+    # request is checked. A sign-in by the same user over a live sid keeps it: a
+    # re-auth is the same device session. The sid is read again first (one indexed
+    # query): a revoked sid, or one with no row, is never reused, so a sign-in on
+    # a copied cookie cannot bring an ended session back. A different user gets a
+    # new sid; the old one is not revoked, since a sign-in is not a logout. Answers
+    # the row, or nil. It raises on a failed write, so the caller can log it.
+    def self.start!(store, user, now: Time.current)
+      return unless user && recording? && revocable?
+
+      mark = mark_in(store)
+      return if mark["user"] == user.id && live_sid?(mark["sid"], user)
+
+      admin = user.respond_to?(:admin?) && user.admin?
+      row = create!(sid: new_sid, user_id: user.id, admin: admin ? true : false, started_at: now, last_seen_at: now)
+      store[cookie_key] = { "id" => row.id, "user" => user.id, "at" => now.to_i, "sid" => row.sid }
+      prune_due!(now)
+      row
+    end
+
+    # Ends this device's session: stamps revoked_at on every row of its sid and
+    # drops the mark from `store`. Other sids (other devices, and other apps on a
+    # shared cookie) are untouched. Answers the rows it revoked. It raises on a
+    # failed write, so the caller can log it (ErrorHandling#end_device_session).
+    def self.revoke!(store, now: Time.current)
+      sid = mark_in(store)["sid"].presence
+      store.delete(cookie_key)
+      return 0 unless sid && recording? && revocable?
+
+      where(sid: sid.to_s, revoked_at: nil).update_all(revoked_at: now, updated_at: now)
+    end
+
     # Records this request for `user`, reading and writing `store` (the session).
-    # Answers the row it wrote, or nil. Never raises: a request must not fail
-    # because its bookkeeping did.
-    def self.track(store, user, now: Time.current)
+    # `row` is the row verdict read for this request, so tracking adds no read of
+    # its own. Answers the row it wrote, or nil. Never raises: a request must not
+    # fail because its bookkeeping did.
+    def self.track(store, user, now: Time.current, row: nil)
       return if user.nil? || !recording?
 
-      mark = store[cookie_key]
-      mark = mark.to_h.transform_keys(&:to_s) if mark.respond_to?(:to_h)
-      same_user = mark.is_a?(Hash) && mark["user"] == user.id
-      seen = same_user ? Time.zone.at(mark["at"].to_i) : nil
-      return if seen && seen > now - THROTTLE
+      mark = mark_in(store)
+      same_user = mark["user"] == user.id
+      seen = same_user && mark["at"] ? Time.zone.at(mark["at"].to_i) : nil
+      revocable = revocable?
+      sid = same_user ? mark["sid"].presence : nil
+      # A sid-less cookie does not wait out the throttle: it gets its sid now.
+      return if seen && seen > now - THROTTLE && (sid || !revocable)
       return unless available?
 
-      row = same_user && seen > now - IDLE ? find_by(id: mark["id"], user_id: user.id) : nil
+      row = revocable && sid ? row_for_sid(sid, user, now, row) : legacy_row(mark, same_user, seen, user, now, revocable)
       if row
-        row.update_columns(last_seen_at: now)
+        changes = { last_seen_at: now }
+        changes[:sid] = sid = new_sid if revocable && sid.nil?
+        row.update_columns(changes)
       else
+        sid ||= new_sid if revocable
         admin = user.respond_to?(:admin?) && user.admin?
-        row = create!(user_id: user.id, admin: admin ? true : false, started_at: now, last_seen_at: now)
+        attrs = { user_id: user.id, admin: admin ? true : false, started_at: now, last_seen_at: now }
+        attrs[:sid] = sid if revocable
+        row = create!(attrs)
+        prune_due!(now)
       end
-      store[cookie_key] = { "id" => row.id, "user" => user.id, "at" => now.to_i }
+      store[cookie_key] = { "id" => row.id, "user" => user.id, "at" => now.to_i }.tap { |m| m["sid"] = sid if revocable }
       row
     rescue StandardError => e
       Rails.logger&.warn("[user_session] #{e.class}: #{e.message}")
       nil
     end
+
+    # True when `sid` has rows, all of them unrevoked, and the latest is `user`'s.
+    # One query on the sid index; a revoked row sorts first, as in verdict.
+    def self.live_sid?(sid, user)
+      return false if sid.blank?
+
+      row = where(sid: sid.to_s).order(Arel.sql("revoked_at IS NULL"), id: :desc).first
+      !row.nil? && row.revoked_at.nil? && row.user_id == user.id
+    end
+    private_class_method :live_sid?
+
+    # The open row to move for this sid: the one verdict read, else the latest by
+    # sid. Past IDLE nil, so a new row starts with the same sid.
+    def self.row_for_sid(sid, user, now, row)
+      row = nil unless row && row.sid == sid
+      row ||= where(sid: sid).order(id: :desc).first
+      row if row && row.user_id == user.id && row.revoked_at.nil? && row.last_seen_at > now - IDLE
+    end
+    private_class_method :row_for_sid
+
+    # The row a sid-less mark names (a cookie from before sids, or before this
+    # app's columns), inside IDLE. Under sids only a row with no sid of its own
+    # qualifies: it takes the cookie's new sid.
+    def self.legacy_row(mark, same_user, seen, user, now, revocable)
+      return unless same_user && seen && seen > now - IDLE
+
+      row = find_by(id: mark["id"], user_id: user.id)
+      row unless revocable && row&.sid.present?
+    end
+    private_class_method :legacy_row
+
+    # Deletes up to `batch` rows last seen before `before`. One statement on the
+    # last_seen_at index.
+    def self.prune!(now: Time.current, before: now - RETENTION, batch: PRUNE_BATCH)
+      where(id: where(arel_table[:last_seen_at].lt(before)).order(:id).limit(batch).select(:id)).delete_all
+    end
+
+    # Prunes at most once per PRUNE_EVERY per process, from the moment a row is
+    # created (a sign-in or a return after IDLE), so no host has to schedule a job.
+    def self.prune_due!(now = Time.current)
+      return if pruned_at && pruned_at > now - PRUNE_EVERY
+
+      self.pruned_at = now
+      prune!(now: now)
+    rescue StandardError => e
+      Rails.logger&.warn("[user_session] prune #{e.class}: #{e.message}")
+      nil
+    end
   end
 end