studio-engine 0.143.2 → 0.144.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d143f0f1859ecc3107721013965ab60cfdc991f7bee318fee274361278e98cc1
-  data.tar.gz: 32c057de7990555e9a8ff3a54963ba6916e0bba30fc26489a46c783def9fb5f8
+  metadata.gz: 98d7d512ad7dbca4f6610b95f82ea7c0975450f9150522a4a68e89df5f392bf5
+  data.tar.gz: 8b2e116b30cc9a8d7d927a1f1bfd1eb155fc02d7cbbbbc0f6dccd4f33b41446e
 SHA512:
-  metadata.gz: d0857709512f2a2180b6d1c25aeb9c886ba6708550cc00560243d5881d0422e900c77145823e31018aab7d334133deb8087fc3cbcaebfa79a5ef332ce15ecef1
-  data.tar.gz: d500cb012588520e9c8d76974f9a5f8189560288216b584a6712a609393b0dbed749e10bf1b33bb590932dbfc4cadf632a86ad448053dafa476fbb956a78128b
+  metadata.gz: 0c58133319c6e482aca21bbfe8a5478c59b285b01ce5b1cbeed3136dd9e64138d94c5a3cfec3f590f6ddf35dd7bc1084271efc078faa7e3cb868b162af9f1d15
+  data.tar.gz: 7aba5316e9c073cd58359bac595c3ef9d2f9b02cecedadfa80131d9effc6b343a86c5d0df89db380bc2b17e2bd59a66ba5215e976fd8b0a3b3986e8fbcbe1caa

data/CHANGELOG.md

@@ -4,6 +4,22 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.144.0 — 2026-11-11
+
+### Added
+
+- **`Studio::SystemTestCase`, one shared system-test base.** The browser harness fixes that each app carried on its own now ship in the gem: the window resets to `desktop_size` before every test, `evaluate_async_script` gives back the script timeout Capybara 3.40.0 leaves at 2s, a phone viewport's DevTools emulation is cleared after every test, and Selenium gets a 180s read timeout. Helpers `phone_viewport!`, `assert_viewport_width` and `clear_emulation` come with it. An app adopts with `require "studio/system_test_case"` and `class ApplicationSystemTestCase < Studio::SystemTestCase`, keeps its own settings, setup, helpers and tests, and opts out of one hook by name with `skip_harness_hook :name, reason:`, which is logged. `lib/studio.rb` does not load it. See `docs/SYSTEM_TESTS.md`.
+- **`Studio::TableComponent` takes `caption:` and `aria_label:`, and its scroll wrapper is keyboard-scrollable.** The wrapper is always `tabindex="0"` with an inset focus ring, so a keyboard user can focus it and scroll a wide table with the arrow keys. `caption:` renders a visually hidden `<caption>`; `aria_label:` labels the table without one. Either one also makes the wrapper a labelled `role="region"`. Pass one on every table.
+- **`Studio::ButtonComponent` gains `tone: :outline`** (`btn-outline`: a primary border, unfilled until hover), drawn in light and dark on `/admin/style` and pinned by the screenshot baselines.
+
+### Changed
+
+- **`Studio::ButtonComponent`'s default `md` size puts its label on the type scale.** It now adds the new `btn-md` utility: body size (1x `--type-base`, 16px; 14px under `type-dense`) at a 1.25 line height, so the button grows no taller. A bare `.btn` keeps `text-sm`, so hand-built buttons do not move. A host that relied on the 14px component label sees it at 16px.
+
+### Fixed
+
+- **On-demand modals (`Studio.modals`) are hardened before Turf adopts them.** A fetch that does not answer within `Studio.modals.fetch_timeout_ms` (default 8000) is aborted and shows the error card, which now has Try again and a Close that works on a card opened `dismissible: false`. The fragment cache is dropped when the session changes by Turbo visit (sign-in, sign-out, a user switch), keyed on `Studio::Modals.session_marker`, so no cached fragment carries a dead CSRF token or the prior user's data. A fragment containing a `<script>` is refused, not inserted (the reason shows on the card in development and test). The loading card is `role="status"`. Prefetch also runs after each Turbo visit. No change for a consumer: `$store.modals.open(id, props, opts)` is unchanged; set `fetch_timeout_ms` in the initializer to change the wait.
+
 ## 0.143.2 — 2026-11-10
 
 ## 0.143.1 — 2026-11-10

data/Gemfile

@@ -29,6 +29,13 @@ group :development, :test do
   # Rails.application directly rather than growing Rails-app scaffolding inside a
   # test fixture. Not a runtime dependency — consuming apps bring their own server.
   gem "puma", ">= 6.0"
+
+  # Capybara and selenium-webdriver drive Studio::SystemTestCase's own tests
+  # (test/lib/system_test_case_test.rb, test/system/). The gem does not declare
+  # them: lib/studio.rb never loads lib/studio/system_test_case.rb, and every
+  # host that inherits the base bundles both in its own test group.
+  gem "capybara", ">= 3.39"
+  gem "selenium-webdriver", ">= 4.20"
 end
 
 # solana-studio backs the style guide's THREE web3 specimens (Connect wallet and

data/README.md

@@ -55,6 +55,7 @@ resolved.
 - **Connections**: generic OAuth 2.0 tooling to connect a third-party account. A host declares each provider with `Studio.define_connection` (endpoints, static or per-account; scopes; form or HTTP Basic client auth; a rotating, cached or client-credentials refresh policy). The engine gives it `Studio::Connection` (one table, tokens encrypted, `bin/rails g studio:connections`), the connect, callback and disconnect actions (`Studio::ConnectionFlow`) behind the host's admin guard, `Studio.draw_connection_routes`, an exact-key log filter, and a stand-in for the e2e lane. The tooling names no provider; the engine's own definitions are the Integrations below. See [`docs/CONNECTIONS.md`](docs/CONNECTIONS.md).
 - **Integrations**: ready connection definitions on that tooling for QuickBooks, Egnyte and Microsoft 365: the URLs, scopes, token behaviour and a minimal describe, never a reader. A host turns one on with `Studio.enable_integration :quickbooks, env: { client_id: "...", client_secret: "..." }` (env var names) and mounts the admin page with `Studio.draw_integrations_routes(self)`: a list with each status and Connect, and one page per integration with Disconnect and a host panel for the host's own live read. See [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
 - **Surveys**: define a survey in app code (`config/surveys/*.rb`, `Studio.define_survey`) with six question types — emoji scale, 1–5 rating, single and multiple choice, short and long text — and the engine serves it at `/surveys/:slug`: one question per screen, autosave, resume, keyboard shortcuts, and a no-JavaScript fallback. `config.on_survey_completed` and `config.survey_ref_resolver` let the app fire its own goals and attribute email arrivals. An admin panel at `/admin/surveys` breaks results down per question and exports CSV. Opt in with `config.draw_survey_routes = true` and `config.draw_admin_survey_routes = true`. See [`docs/SURVEYS.md`](docs/SURVEYS.md).
+- **System tests**: `Studio::SystemTestCase`, the one Capybara base every host's `ApplicationSystemTestCase` inherits (`require "studio/system_test_case"`). It resets the window before each test, restores the script timeout Capybara 3.40.0's `evaluate_async_script` leaves at 2s, clears phone emulation after each test, and gives Selenium a 180s read timeout. An app keeps its own settings (`phone_width`), setup, helpers and tests, and opts out of one hook by name with `skip_harness_hook`, which is logged. See [`docs/SYSTEM_TESTS.md`](docs/SYSTEM_TESTS.md).
 
 ## Tailwind
 
@@ -309,6 +310,7 @@ size and state live (Components section), and the gallery has a preview per stat
 <%= render Studio::ButtonComponent.new(label: "Save", type: "submit") %>
 <%= render Studio::ButtonComponent.new(label: "Delete", tone: :danger, size: :sm) %>
 <%= render Studio::ButtonComponent.new(label: "Docs", tone: :quiet, href: docs_path) %>
+<%= render Studio::ButtonComponent.new(label: "Export", tone: :outline) %>
 <%= render Studio::ButtonComponent.new(label: "Save", type: "submit", loading: true, busy_label: "Saving…") %>
 
 <%= render(Studio::EmptyStateComponent.new(detail: "Invite someone to start.")) do |empty| %>
@@ -318,6 +320,7 @@ size and state live (Components section), and the gallery has a preview per stat
 
 <%= render Studio::TableComponent.new(
       rows: @users, sort: params[:sort], direction: params[:direction], empty: "No users yet.",
+      caption: "Team members",
       columns: [
         { key: :name, label: "User", sortable: true },
         { key: :created_at, label: "Joined", align: :right, cell: ->(u) { l(u.created_at.to_date) } }
@@ -326,11 +329,19 @@ size and state live (Components section), and the gallery has a preview per stat
 
 - **Button.** Tones map onto the shipped utilities: `primary` is `btn-primary`,
   `secondary` is `btn-secondary` (the success role, or the app's
-  `--btn-secondary-*` retune), `quiet` is `btn-neutral`, `danger` is `btn-danger`.
-  Sizes are `btn-sm`, bare `btn` and `btn-lg`. `loading:` uses the aria-busy
+  `--btn-secondary-*` retune), `quiet` is `btn-neutral`, `danger` is `btn-danger`,
+  `outline` is `btn-outline` (a primary border, unfilled until hover).
+  Sizes are `btn-sm`, `btn-md` and `btn-lg`. `btn-md` puts the medium label on
+  the type scale at body size (1x `--type-base`); a bare `btn` keeps `text-sm`,
+  so hand-built buttons do not move. `loading:` uses the aria-busy
   contract (docs/LOADER.md): the button is `aria-busy` and disabled and shows the
   pending spinner. A submit button always carries the hidden spinner, so a Turbo
   form that marks itself busy shows it with no script. A link cannot be loading.
+  **A busy form hides the icon on every button in it**, not only on the submit
+  button: the aria-busy contract hides every `[data-loader-idle]` under the busy
+  element, and the icon slot is idle content. A Cancel or Back button with an
+  icon inside the form loses its icon while the form submits. Put such a button
+  outside the form, or give it no icon.
 - **Empty state.** The `.empty-state` card, the message at `type-body`, the
   detail at `type-fine`, an optional icon, and at most one action, which is a
   `Studio::ButtonComponent`. `framed: false` drops the card. The
@@ -341,7 +352,10 @@ size and state live (Components section), and the gallery has a preview per stat
   `sort_url:` takes a callable for another URL shape. No rows renders one row with
   a bare empty state. On a phone the table scrolls sideways, as every engine table
   does; `min_width:` sets where. `sticky_header: true` adds
-  `data-sticky-table-header`.
+  `data-sticky-table-header`. Give every table a name: `caption:` renders a
+  visually hidden `<caption>`, `aria_label:` labels the table without one. The
+  scroll wrapper is always `tabindex="0"`, so a keyboard user can scroll it, and a
+  name also makes it a labelled `role="region"`.
 
 ### The page header — `studio/_page_header`
 
@@ -737,11 +751,22 @@ change: `$store.modals.open("contest_rules", props)` works as before.
 |--------|---------|
 | `partial:` | The content partial, as the layout rendered it. The two rules below still apply (one root, no double quote in `x-data`). |
 | `auth:` | `:any` (default) or `:user`. A `:user` modal answers `401` to a signed-out request and is never prefetched for one. |
-| `prefetch:` | `true` fetches the modal when the browser idles after load (`requestIdleCallback`, else a timeout), so it opens with no wait. Use it for a modal opened on most visits. |
+| `prefetch:` | `true` fetches the modal when the browser idles after load and after every Turbo visit (`requestIdleCallback`, else a timeout), so it opens with no wait. Use it for a modal opened on most visits. |
 | `locals:` | A Hash, a Symbol naming a helper the view answers (an existing `*_modal_locals` helper), or a callable taking the view. Resolved per request, in the view. |
 
 Ids are lower-case letters, digits, `-` and `_`.
 
+**Locals run in the modal endpoint, not on the page.** The view that resolves
+`locals:` belongs to `Studio::ModalsController`, so it has the helpers and the
+session (`current_user`, `logged_in?`) but none of the page's instance
+variables. A `*_modal_locals` helper that reads `@contest` or any other
+page-scoped ivar gets `nil` there. Such a helper cannot move as it is: derive
+what it needs from the session or the user, or keep that modal in the layout.
+
+**The fetch timeout.** `Studio.modals.fetch_timeout_ms` (default `8000`) is how
+long the host waits for a fragment. Set it in the initializer:
+`Studio.modals.fetch_timeout_ms = 12_000`.
+
 **What happens.** The host advertises the registered ids on its template
 (`data-modal-host-remote-value`). `open(id)` for one that is not in the page
 yet fetches `GET /_studio/modals/<id>` (`Studio::ModalsController`), wraps the
@@ -749,12 +774,41 @@ fragment in the same `<template x-if>` a layout would render, appends it to the
 card, and opens. A fetch that answers within 150 ms opens with no loading state.
 A slower one opens the card with the engine's processing card, held at least
 `StudioModals.MIN_LOAD_MS`, then the content replaces it. A failed fetch (a
-network error, a `500`, a `401`, or a host filter's redirect) shows the
-engine's error card, whose button closes; the next open tries again.
-
-The fragment is held for the page's lifetime, across Turbo visits: a later open
-inserts it from memory into the new page's host, once, with no second request.
-A fetch that lands after a Turbo visit opens nothing on the new page.
+network error, a `500`, a `401`, a host filter's redirect, or no answer within
+`fetch_timeout_ms`) shows the engine's error card. **Try again** re-runs the
+fetch with the card in place; **Close** closes it, even on a card opened
+`dismissible: false` (Escape and the backdrop still respect that flag). The next
+open tries again too. The loading card is `role="status"` (`aria-live`
+polite); the error card is `role="alert"`.
+
+**A fragment with a `<script>` is refused**, never inserted: it shows the error
+card. In development and test the card names the reason; in production it shows
+the generic line. Nothing is logged to the console either way; the endpoint
+records an `ErrorLog` row instead, once per modal id per process. Put behaviour in a module or a Stimulus
+controller.
+
+The fragment is held across Turbo visits: a later open inserts it from memory
+into the new page's host, once, with no second request. A fetch that lands
+after a Turbo visit opens nothing on the new page.
+
+**The cache follows the session.** A fragment can carry the viewer's data and a
+form's CSRF token. The host advertises a session marker
+(`Studio::Modals.session_marker`: a digest of the session id and the user id
+under `Studio.session_key`). The browser compares it on every open and every
+`turbo:load`. When it changes (sign-out, a sign-in, a user switch, by Turbo
+visit, or a `session:changed` from studio/session that is a real identity
+change: `signed_out`, `changed`, or another viewer's identities, never the first
+seating at load or a `stale` → `authenticated` revalidation), the browser drops
+every cached fragment, every fetch in flight and every template already
+inserted, so the next open fetches fresh. A modal open at that moment keeps its
+template until it closes: a card is never emptied in place. The session id is
+what `reset_session` rotates, and the CSRF secret rotates with it; the user id
+catches a sign-in that keeps the session. The `csrf-token` meta is not used: it
+is masked anew on every render, so it would empty the cache on every visit.
+
+**Prefetch** runs when the browser idles after the first load and again after
+every Turbo visit (`turbo:load`). An id already cached or in flight is not
+fetched twice.
 
 **What does not change.** An id the registry does not name takes the old
 synchronous `open()` path, and an app that registers nothing renders the host
@@ -766,8 +820,8 @@ One difference for a registered id: during the first open's fetch,
 with no layout. It skips the host's `require_authentication` so an `:any`
 modal serves a signed-out visitor, and answers a `:user` modal's signed-out
 request with a bare `401`, never the `/login` redirect. Each answer is
-`private` with `Vary: Cookie` and an ETag. A fragment carries no script, so
-the page's CSP is unchanged. Only the shared host (`$store.modals`) loads on
+`private` with `Vary: Cookie` and an ETag. A fragment carries no script (the
+browser refuses one that does), so the page's CSP is unchanged. Only the shared host (`$store.modals`) loads on
 demand; a scoped host renders its modals as before.
 
 **Do not do both.** An id that the registry names and the layout still

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

@@ -1709,6 +1709,15 @@ body.modal-open .studio-app-banner {
   @apply px-8 py-3 text-base rounded-xl shadow-sm;
 }
 
+/* The medium button's label on the type scale: body size (1x --type-base), where a
+   bare .btn keeps text-sm (14px, off the scale) so no host's hand-built button moves.
+   Studio::ButtonComponent size: :md adds it. The 1.25 line height holds the bare
+   .btn's 20px line, so the button grows no taller. Follows type-dense like type-body. */
+@utility btn-md {
+  font-size: calc(var(--type-base, 16px) * 1);
+  line-height: 1.25;
+}
+
 /* A busy button (Studio::ButtonComponent loading:, or a submit Turbo marks busy) is
    disabled so it takes no second click, but it is working, not unavailable: it keeps
    its full colour and shows the progress cursor. The busy words sit in the button's

data/app/components/previews/studio/button_component_preview.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module Studio
-  # Every state Studio::ButtonComponent can show: the four tones, the three
+  # Every state Studio::ButtonComponent can show: the five tones, the three
   # sizes, a link, an icon, disabled and loading. No @param tags: the gallery
   # takes no input.
   class ButtonComponentPreview < ViewComponent::Preview
-    # The four tones, at the default size.
+    # The five tones, at the default size.
     def tones
       render_with_template(locals: { tones: Studio::ButtonComponent::TONES.keys })
     end

data/app/components/previews/studio/table_component_preview/rows.html.erb

@@ -10,5 +10,5 @@
 %>
 <div class="card overflow-hidden" data-specimen="table">
   <%= render Studio::TableComponent.new(rows: rows, columns: columns, sort: sort, direction: direction,
-        sort_url: ->(key, dir) { "?sort=#{key}&direction=#{dir}" }, empty: "No members yet.", min_width: 520) %>
+        sort_url: ->(key, dir) { "?sort=#{key}&direction=#{dir}" }, empty: "No members yet.", min_width: 520, caption: "Team members") %>
 </div>

data/app/components/studio/button_component.rb

@@ -6,6 +6,7 @@ module Studio
   #   render Studio::ButtonComponent.new(label: "Save")
   #   render Studio::ButtonComponent.new(label: "Delete", tone: :danger, size: :sm)
   #   render Studio::ButtonComponent.new(label: "Docs", tone: :quiet, href: "/docs")
+  #   render Studio::ButtonComponent.new(label: "Export", tone: :outline)
   #   render Studio::ButtonComponent.new(label: "Save", type: "submit", loading: true, busy_label: "Saving…")
   #   render(Studio::ButtonComponent.new(label: "New")) { |b| b.with_icon { plus_svg } }
   #
@@ -18,7 +19,12 @@ module Studio
   #               secondary  btn-secondary  the success role, or the app's retune
   #               quiet      btn-neutral    a second action: Cancel, Back, Next
   #               danger     btn-danger     a destructive action
-  #   size        sm  btn-sm · md  btn · lg  btn-lg
+  #               outline    btn-outline    a bordered, unfilled action on the
+  #                                         primary colour; it fills on hover
+  #   size        sm  btn-sm · md  btn-md · lg  btn-lg
+  #
+  # md's label sits on the type scale at body size (btn-md, 1x --type-base); a
+  # bare .btn keeps text-sm, so a host's hand-built buttons do not move.
   #
   # Its public surface, which a release changes only with a Breaking line in the
   # changelog (docs/FRONT_END_STANDARD.md, "A primitive's public surface"):
@@ -36,7 +42,9 @@ module Studio
   # always carries the pending loader, hidden, so a Turbo form that marks itself
   # aria-busy shows it with no script here. The icon is the idle content and
   # gives way to the loader; busy_label: words replace the label while busy.
-  # A link cannot be busy, so loading: with href: is refused.
+  # A link cannot be busy, so loading: with href: is refused. A busy FORM hides
+  # the icon on every button inside it, not just the submit (engine-motion.css,
+  # :where(form, button)[aria-busy] [data-loader-idle]); README, "UI Primitives".
   #
   # Every class string is written out whole: Tailwind finds utilities by scanning
   # source text, and engine.css adds app/components to every host's scan.
@@ -53,12 +61,13 @@ module Studio
       primary: "btn-primary",
       secondary: "btn-secondary",
       quiet: "btn-neutral",
-      danger: "btn-danger"
+      danger: "btn-danger",
+      outline: "btn-outline"
     }.freeze
 
     SIZES = {
       sm: "btn-sm",
-      md: nil,
+      md: "btn-md",
       lg: "btn-lg"
     }.freeze
 

data/app/components/studio/table_component.html.erb

@@ -1,5 +1,6 @@
-<div class="<%= Studio::TableComponent::WRAPPER %>" data-table>
+<%= tag.div(**wrapper_attributes) do %>
   <%= tag.table(**table_attributes) do %>
+    <% if caption %><caption class="<%= Studio::TableComponent::CAPTION %>"><%= caption %></caption><% end %>
     <thead class="<%= Studio::TableComponent::HEAD %>">
       <tr>
         <% columns.each do |column| %>
@@ -29,4 +30,4 @@
       <% end %>
     </tbody>
   <% end %>
-</div>
+<% end %>

data/app/components/studio/table_component.rb

@@ -12,7 +12,8 @@ module Studio
   #       { key: :created_at, label: "Joined", align: :right, cell: ->(user) { l(user.created_at.to_date) } }
   #     ],
   #     sort: params[:sort], direction: params[:direction],
-  #     empty: "No users yet."
+  #     empty: "No users yet.",
+  #     caption: "Team members"
   #   )
   #
   # A column is a Hash: key: (required), label: (required), sortable: (false),
@@ -32,21 +33,36 @@ module Studio
   # (admin_model_table, the emails index): the table keeps its columns and its
   # wrapper scrolls. min_width: sets the width under which it scrolls.
   #
+  # A NAME AND A KEYBOARD SCROLL. The scroll wrapper takes tabindex="0", so a
+  # keyboard user can focus it and scroll it with the arrow keys (WCAG 2.1.1; axe's
+  # scrollable-region-focusable), and it shows a focus ring inside its edge, so a
+  # card's overflow-hidden cannot clip it.
+  # caption: renders a <caption> (visually hidden: the page's own heading is the
+  # visible title) and aria_label: labels the table without one. Either one also
+  # makes the wrapper a named role="region", so a screen reader announces what it
+  # entered. With neither, the wrapper stays focusable but takes no role: a
+  # region with no name is noise. Pass one.
+  #
   # Its public surface, which a release changes only with a Breaking line in the
   # changelog (docs/FRONT_END_STANDARD.md, "A primitive's public surface"):
   #   inputs   rows:, columns:, id:, sort:, direction:, sort_url:, sort_param:,
-  #            direction_param:, empty:, min_width:, sticky_header:
+  #            direction_param:, empty:, min_width:, sticky_header:,
+  #            caption:, aria_label:
   #   data-*   data-table on the wrapper; data-table-sort-key on a sortable
   #            header; data-table-empty on the empty row; data-sticky-table-header
   #            on the table when sticky_header: (studio/sticky_table_header)
-  #   aria-*   aria-sort on the sorted header
+  #   aria-*   aria-sort on the sorted header; aria-label on the table
+  #            (aria_label:) and on the wrapper, role="region" (caption: or
+  #            aria_label:)
+  #   tabindex tabindex="0" on the wrapper
   #
   # Every class string is written out whole: Tailwind finds utilities by scanning
   # source text, and engine.css adds app/components to every host's scan.
   class TableComponent < ViewComponent::Base
     strip_trailing_whitespace
 
-    WRAPPER = "overflow-x-auto"
+    WRAPPER = "overflow-x-auto focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary"
+    CAPTION = "sr-only"
     TABLE = "w-full type-body"
     HEAD = "bg-surface-alt text-muted type-fine uppercase tracking-wide"
     BODY = "divide-y divide-subtle"
@@ -71,7 +87,8 @@ module Studio
     attr_reader :rows, :columns, :empty
 
     def initialize(rows:, columns:, id: nil, sort: nil, direction: nil, sort_url: nil, sort_param: "sort",
-                   direction_param: "direction", empty: "Nothing here yet.", min_width: nil, sticky_header: false)
+                   direction_param: "direction", empty: "Nothing here yet.", min_width: nil, sticky_header: false,
+                   caption: nil, aria_label: nil)
       super()
       raise ArgumentError, "Studio::TableComponent needs at least one column" if columns.blank?
 
@@ -86,12 +103,29 @@ module Studio
       @empty = empty
       @min_width = min_width
       @sticky_header = sticky_header ? true : false
+      @caption = caption.presence
+      @aria_label = aria_label.presence
+    end
+
+    attr_reader :caption
+
+    # The name the wrapper's region announces: the caption, else aria_label:.
+    def accessible_name = @caption || @aria_label
+
+    def wrapper_attributes
+      attrs = { class: WRAPPER, tabindex: "0", data: { table: "" } }
+      if accessible_name
+        attrs[:role] = "region"
+        attrs[:aria] = { label: accessible_name }
+      end
+      attrs
     end
 
     def table_attributes
       attrs = { class: TABLE, id: @id }
       attrs[:style] = "min-width: #{@min_width.to_i}px" if @min_width
       attrs[:data] = { sticky_table_header: "" } if @sticky_header
+      attrs[:aria] = { label: @aria_label } if @aria_label && !@caption
       attrs.compact
     end
 

data/app/controllers/studio/modals_controller.rb

@@ -22,7 +22,14 @@ module Studio
   # so it is private: Rails' default for a dynamic GET (max-age=0, private,
   # must-revalidate, with an ETag) is kept, and Vary: Cookie is added so no
   # cache answers one session with another's fragment. The browser holds the
-  # fragment for the page's lifetime anyway (studio/modal_host).
+  # fragment across Turbo visits and drops it when the host's session marker
+  # changes (Studio::Modals.session_marker, studio/modal_host).
+  #
+  # NO SCRIPT. studio/modal_host refuses a fragment that carries a <script>.
+  # The browser says nothing in production, so the refusal is recorded here,
+  # as an ErrorLog row, where it is seen. The fragment is still sent: the
+  # browser's refusal (with its reason on the card in development) is the
+  # behaviour; this is the record.
   class ModalsController < ::ApplicationController
     skip_before_action :require_authentication, raise: false
 
@@ -37,10 +44,34 @@ module Studio
       # the host's error page for the browser to mistake for a fragment.
       response.headers["X-Studio-Modal"] = entry.id
       response.headers["Vary"] = [response.headers["Vary"], "Cookie"].compact.join(", ")
+      record_script_fragment(entry) if response.body.to_s.match?(SCRIPT_TAG)
     end
 
     private
 
+    SCRIPT_TAG = %r{<script[\s>/]}i
+
+    # Ids already recorded in this process: one row per bad modal, not one per
+    # request (a prefetched bad fragment would otherwise write a row on every
+    # page view).
+    RECORDED_SCRIPT_IDS = Set.new
+    RECORDED_SCRIPT_LOCK = Mutex.new
+
+    def self.forget_recorded_scripts! = RECORDED_SCRIPT_LOCK.synchronize { RECORDED_SCRIPT_IDS.clear }
+
+    # A best-effort record: logging never breaks the answer.
+    def record_script_fragment(entry)
+      return unless defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+      return unless RECORDED_SCRIPT_LOCK.synchronize { RECORDED_SCRIPT_IDS.add?(entry.id) }
+
+      error = RuntimeError.new("Studio.modals #{entry.id}: #{entry.partial} renders a <script>; " \
+                               "studio/modal_host refuses it. Move the behaviour to a module or a Stimulus controller.")
+      error.set_backtrace(caller)
+      ::ErrorLog.capture!(error)
+    rescue StandardError
+      nil
+    end
+
     def studio_modal_viewer_signed_in?
       respond_to?(:logged_in?, true) && logged_in?
     end

data/app/javascript/studio/modal_host.js

@@ -306,15 +306,50 @@ function focusTrap(env, held) {
 // 'error' (the host's error card) and forgets the fetch, so the next open
 // retries. So for the first LOAD_DELAY_MS of a first open, isOpen(id) is false.
 //
-// THE CACHE lives for the page's lifetime: fragments by id, beside the store,
-// not on it. A Turbo visit brings a fresh host without the inserted templates
+// THE TIMEOUT. A fetch that has not answered in cfg.timeout_ms (the server's
+// Studio.modals.fetch_timeout_ms, else DEFAULT_FETCH_TIMEOUT_MS) is aborted and
+// shows the error card. Its Try again (retryRemote) re-runs the fetch with the
+// card in place; its Close calls close() directly, so a card opened
+// dismissible: false still has a way out.
+//
+// THE CACHE: fragments by id, beside the store, not on it, keyed on the
+// session. A Turbo visit brings a fresh host without the inserted templates
 // (or a snapshot clone with them), so insertion checks the host every time and
 // inserts only what is missing; that check is what keeps a Turbo visit from
 // inserting a modal twice. A fetch that resolves after a Turbo visit replaced
 // the body (doc.body changed) opens nothing on the new page.
+//
+// THE SESSION KEY. A fragment can carry the viewer's data and a form's CSRF
+// token, and a Turbo visit across sign-in, sign-out or a user switch keeps the
+// document, and with it this cache. So the host advertises cfg.session, a
+// digest of the session id and the signed-in user id (Studio::Modals.
+// session_marker), and every open and every turbo:load compares it: a change
+// drops every cached fragment, every fetch in flight, and every template
+// already inserted on this page, except the template of a modal open now,
+// which goes when it closes (a card is never emptied in place).
+// studio/session's session:changed drops them too, but only on a real
+// identity change (sessionIdentityChange), never on the first seating or a
+// stale -> authenticated revalidation. Why that signal: the session id is what
+// reset_session rotates, and the CSRF secret rotates with it, so a cached form
+// token goes stale exactly when it changes; the user id catches a sign-in
+// that keeps the session. The page's csrf-token meta would not do: it is
+// masked afresh on every render, so it would empty the cache on every visit.
+//
+// THE SCRIPT RULE. A fragment containing a <script> is refused, never
+// inserted: an inserted script would run (or not) by accident of how Alpine
+// clones the template, and it carries no CSP nonce. It shows the error card;
+// with cfg.debug (development and test) the card names the reason. There is
+// no console output in either case: the endpoint records it server-side in an
+// ErrorLog row (Studio::ModalsController).
+//
+// PREFETCH runs when the browser idles after the first load AND after every
+// Turbo visit (turbo:load), so a page reached by Turbo prefetches what it
+// flags, for the viewer it was rendered for.
 
 export const REMOTE_MODAL_ATTR = 'data-studio-remote-modal'
 export const LOAD_DELAY_MS = 150
+export const DEFAULT_FETCH_TIMEOUT_MS = 8000
+export const REMOTE_ERROR_TEXT = 'Check your connection and try again.'
 
 // The host template advertising on-demand modals, if this page has one.
 export function remoteHost(doc) {
@@ -329,6 +364,8 @@ export function remoteConfig(doc) {
     var cfg = JSON.parse(el.getAttribute('data-modal-host-remote-value'))
     if (!cfg || typeof cfg.url !== 'string' || !Array.isArray(cfg.ids)) return null
     if (!Array.isArray(cfg.prefetch)) cfg.prefetch = []
+    if (!(cfg.timeout_ms > 0)) cfg.timeout_ms = DEFAULT_FETCH_TIMEOUT_MS
+    if (typeof cfg.session !== 'string') cfg.session = ''
     return cfg
   } catch (e) {
     return null
@@ -381,18 +418,61 @@ export function remoteModalUrl(cfg, id) {
   return cfg.url.replace('__id__', encodeURIComponent(id))
 }
 
+// A refused fragment's error. Its message is shown only with cfg.debug.
+function remoteError(message) {
+  var err = new Error(message)
+  err.studioModal = true
+  return err
+}
+
+// True when the markup carries a <script> element. A text match, not a parse:
+// the fragment is server-rendered, so this guards an app's own mistake, and a
+// false positive (the word in an attribute) errs on the safe side.
+export function fragmentHasScript(markup) {
+  return /<script[\s>\/]/i.test(String(markup))
+}
+
 // One fetch. Rejects unless the answer is the fragment the endpoint sends
 // (X-Studio-Modal names the id): a host filter's redirect to a full page, or a
-// 401, is an error, never a modal.
+// 401, is an error, never a modal. Rejects too when nothing answers inside
+// cfg.timeout_ms (the request is aborted where the browser can), and when the
+// fragment carries a <script>.
 export function fetchRemoteModal(win, cfg, id) {
-  return win.fetch(remoteModalUrl(cfg, id), {
+  var ms = cfg.timeout_ms > 0 ? cfg.timeout_ms : DEFAULT_FETCH_TIMEOUT_MS
+  var controller = typeof win.AbortController === 'function' ? new win.AbortController() : null
+  var init = {
     credentials: 'same-origin',
     headers: { 'Accept': 'text/html', 'X-Requested-With': 'XMLHttpRequest' }
-  }).then(function (res) {
-    if (!res.ok || !res.headers || res.headers.get('X-Studio-Modal') !== id) {
-      throw new Error('studio/modal_host: ' + id + ' answered ' + res.status)
+  }
+  if (controller) init.signal = controller.signal
+
+  return new Promise(function (resolve, reject) {
+    var settled = false
+    var timer = win.setTimeout(function () {
+      if (settled) return
+      settled = true
+      if (controller) { try { controller.abort() } catch (e) {} }
+      reject(remoteError('studio/modal_host: ' + id + ' did not answer in ' + ms + 'ms'))
+    }, ms)
+    function finish(fn, value) {
+      if (settled) return
+      settled = true
+      if (win.clearTimeout) win.clearTimeout(timer)
+      fn(value)
     }
-    return res.text()
+
+    win.fetch(remoteModalUrl(cfg, id), init).then(function (res) {
+      if (!res.ok || !res.headers || res.headers.get('X-Studio-Modal') !== id) {
+        throw remoteError('studio/modal_host: ' + id + ' answered ' + res.status)
+      }
+      return res.text()
+    }).then(function (markup) {
+      if (fragmentHasScript(markup)) {
+        throw remoteError('studio/modal_host: ' + id + ' was refused: its fragment carries a <script>. ' +
+                          'Move the behaviour to a module or a Stimulus controller.')
+      }
+      finish(resolve, markup)
+    }).catch(function (err) { finish(reject, err) })
   })
 }
 
@@ -402,21 +482,142 @@ export function whenIdle(win, fn) {
   else win.setTimeout(fn, 1500)
 }
 
-// The loader one shared store keeps in its closure.
-export function createRemoteModals(env) {
+// Removes the inserted registrations from this page's cards (the session
+// changed, so what they carry is stale), except those whose id is in keep:
+// the modals on the stack now, which must never be emptied in place. Answers
+// the ids it kept.
+function removeRemoteModals(doc, keep) {
+  keep = keep || []
+  var kept = []
+  var cards = remoteCards(doc)
+  for (var i = 0; i < cards.length; i++) {
+    var kids = Array.prototype.slice.call(cards[i].children || [])
+    for (var k = 0; k < kids.length; k++) {
+      var kidId = kids[k].getAttribute ? kids[k].getAttribute(REMOTE_MODAL_ATTR) : null
+      if (kidId !== null && keep.indexOf(kidId) !== -1) {
+        if (kept.indexOf(kidId) === -1) kept.push(kidId)
+        continue
+      }
+      if (kidId !== null) {
+        if (typeof cards[i].removeChild === 'function') cards[i].removeChild(kids[k])
+        else if (typeof kids[k].remove === 'function') kids[k].remove()
+      }
+    }
+  }
+  return kept
+}
+
+// THE SETTLED STATES of studio/session (docs/SESSION_DRIFT.md). A settled
+// event whose fingerprint (user + bound identities) differs from the last is an
+// identity change; rehydrated is one ("possibly as someone new"); stale is not.
+var SETTLED_SESSION_STATES = ['anonymous', 'authenticated', 'signed_out', 'changed', 'rehydrated']
+
+// Is this session:changed detail a REAL change of who is viewing? studio/session
+// sends the event on every transition, including the first seating on page
+// load (previous null) and stale -> authenticated when a hidden tab returns,
+// and neither may throw the cache away. lastIdentity is the identity string
+// the previous settled event carried (null before the first). Answers
+// { real, identity }: identity is the string to remember.
+export function sessionIdentityChange(detail, lastIdentity) {
+  var d = detail || {}
+  var snap = d.snapshot || {}
+  var identity = snap.state === 'anonymous' || snap.state === 'signed_out' || d.state === 'anonymous' || d.state === 'signed_out'
+    ? 'anonymous'
+    : (snap.fingerprint || JSON.stringify(snap.identities || {}))
+  // First seating, or the store has no state yet: remember, never drop.
+  if (d.previous === null || d.previous === undefined || !d.state) return { real: false, identity: identity }
+  // Someone else observed (changed) or the server reports nobody (signed_out).
+  if (d.state === 'changed' || (d.state === 'signed_out' && d.previous !== 'signed_out')) {
+    return { real: true, identity: identity }
+  }
+  // A settled state with a different identity than the last one seen.
+  if (SETTLED_SESSION_STATES.indexOf(d.state) !== -1 && lastIdentity !== null && identity !== lastIdentity) {
+    return { real: true, identity: identity }
+  }
+  // stale, or a return to the same identity: revalidation.
+  return { real: false, identity: SETTLED_SESSION_STATES.indexOf(d.state) !== -1 ? identity : lastIdentity }
+}
+
+// The loader one shared store keeps in its closure. openIds() answers the ids
+// on the store's stack now: their templates survive a drop until they close.
+export function createRemoteModals(env, openIds) {
   var doc = env.doc
   var win = env.win
+  var openNowIds = typeof openIds === 'function' ? openIds : function () { return [] }
+  var staleOpen = []  // ids whose stale template was kept because they were open
   var pending = {}   // id -> Promise<markup>, while in flight or resolved
   var ready = {}     // id -> markup, once resolved
+  var session = null // the cfg.session the cache was filled under
+  var generation = 0 // bumped by a drop, so a fetch from before it caches nothing
+
+  // Drops the cache at once. The templates go too, except those of modals on
+  // the stack now: a card is never emptied in place (a dismissible: false one
+  // would leave the viewer with no way out). Those go when they close (flush).
+  function drop() {
+    pending = {}
+    ready = {}
+    generation++
+    staleOpen = removeRemoteModals(doc, openNowIds())
+  }
+
+  // Removes each kept stale template whose modal has left the stack. Called
+  // whenever the stack changes.
+  function flush() {
+    if (staleOpen.length === 0) return
+    var open = openNowIds()
+    var keep = staleOpen.filter(function (id) { return open.indexOf(id) !== -1 })
+    if (keep.length === staleOpen.length) return
+    // Only the kept ids are stale; every other inserted template is fresh.
+    var gone = staleOpen.filter(function (id) { return keep.indexOf(id) === -1 })
+    var cards = remoteCards(doc)
+    for (var i = 0; i < cards.length; i++) {
+      var kids = Array.prototype.slice.call(cards[i].children || [])
+      for (var k = 0; k < kids.length; k++) {
+        var kidId = kids[k].getAttribute ? kids[k].getAttribute(REMOTE_MODAL_ATTR) : null
+        if (kidId !== null && gone.indexOf(kidId) !== -1) {
+          if (typeof cards[i].removeChild === 'function') cards[i].removeChild(kids[k])
+          else if (typeof kids[k].remove === 'function') kids[k].remove()
+        }
+      }
+    }
+    staleOpen = keep
+  }
+
+  // Drops the cache when the advertised session differs from the one it was
+  // filled under. The first config seen only sets the key.
+  function sync(cfg) {
+    if (!cfg) return
+    if (session === null) { session = cfg.session; return }
+    if (cfg.session === session) return
+    session = cfg.session
+    drop()
+  }
+
+  // studio/session's session:changed drops the cache too, for a change that
+  // happens without a page render to carry a new marker, but ONLY on a real
+  // identity change (sessionIdentityChange): the event also fires on the
+  // first seating at every load and on stale -> authenticated revalidation,
+  // which must keep a finished prefetch and an open card. The host's marker
+  // (sync, on every open and turbo:load) stays the primary signal.
+  var lastIdentity = null
+  if (doc && typeof doc.addEventListener === 'function') {
+    doc.addEventListener('session:changed', function (event) {
+      var verdict = sessionIdentityChange(event && event.detail, lastIdentity)
+      lastIdentity = verdict.identity
+      if (verdict.real) drop()
+    })
+  }
 
   function load(cfg, id) {
+    sync(cfg)
     if (ready[id] !== undefined) return Promise.resolve(ready[id])
     if (!pending[id]) {
-      pending[id] = fetchRemoteModal(win, cfg, id).then(function (markup) {
-        ready[id] = markup
+      var gen = generation
+      var mine = pending[id] = fetchRemoteModal(win, cfg, id).then(function (markup) {
+        if (gen === generation) ready[id] = markup
         return markup
       }, function (err) {
-        delete pending[id]
+        if (pending[id] === mine) delete pending[id]
         throw err
       })
     }
@@ -424,10 +625,11 @@ export function createRemoteModals(env) {
   }
 
   return {
-    // The config when id is advertised here, else null.
+    // The config when id is advertised here, else null. Checks the session.
     handles: function (id) {
       if (typeof id !== 'string') return null
       var cfg = remoteConfig(doc)
+      sync(cfg)
       return (cfg && cfg.ids.indexOf(id) !== -1) ? cfg : null
     },
     load: load,
@@ -437,8 +639,10 @@ export function createRemoteModals(env) {
       return ready[id] !== undefined && insertRemoteModal(doc, id, ready[id])
     },
     insert: function (id, markup) { return insertRemoteModal(doc, id, markup) },
+    flush: flush,
     prefetch: function () {
       var cfg = remoteConfig(doc)
+      sync(cfg)
       if (!cfg || typeof win.fetch !== 'function') return
       cfg.prefetch.forEach(function (id) {
         // A failed prefetch is retried by the open that needs it.
@@ -460,7 +664,19 @@ export function createModalStore(env) {
   // id -> 'loading' | 'error' for an on-demand modal; read by the host's
   // loading and error cards and by each fetched registration's x-if.
   store._remote = {}
-  var remote = createRemoteModals(env)
+  // id -> the reason the last load failed, shown on the error card only when
+  // the host advertises debug (development and test).
+  store._remoteReason = {}
+  var remote = createRemoteModals(env, function () {
+    return store.stack.map(function (entry) { return entry.id })
+  })
+  // Every stack change (open, close, swap, sweep) goes through _sync, so a
+  // stale template kept for an open card is removed once that card leaves.
+  var baseSync = store._sync
+  store._sync = function () {
+    baseSync.call(this)
+    remote.flush()
+  }
 
   // open(id, props, opts)
   //   opts.replace: swap the top entry. With a visible card, a directional
@@ -470,52 +686,95 @@ export function createModalStore(env) {
   //   An on-demand id not yet in the host loads first (openRemote below).
   store.open = function (id, props, opts) {
     var cfg = remote.handles(id)
-    if (cfg && !remote.insertIfReady(id)) return openRemote(this, cfg, id, props, opts)
+    if (cfg && !remote.insertIfReady(id)) return openRemote(this, cfg, id, props, opts, false)
     return openNow.call(this, id, props, opts)
   }
 
-  // The first open of an on-demand id. Never throws and never leaves a promise
-  // unhandled: every outcome is the modal, the loading card, or the error card.
-  function openRemote(self, cfg, id, props, opts) {
+  // The error card's Try again: re-runs the current entry's fetch with the
+  // entry left where it is, showing the loading card meanwhile.
+  store.retryRemote = function () {
+    var entry = this.current()
+    if (!entry || this._remote[entry.id] !== 'error') return
+    var cfg = remote.handles(entry.id)
+    if (!cfg) return
+    // Try again unmounts the focused button, so focus goes back to the
+    // backdrop each time the card's content changes (here and in openRemote).
+    if (remote.insertIfReady(entry.id)) { delete this._remote[entry.id]; this.refocus(); return }
+    openRemote(this, cfg, entry.id, entry.props, null, true)
+    this.refocus()
+  }
+
+  // The error card's message: the generic line, or with cfg.debug the reason.
+  store.remoteErrorText = function () {
+    var entry = this.current()
+    var reason = entry && this._remoteReason[entry.id]
+    return reason || REMOTE_ERROR_TEXT
+  }
+
+  // The first open of an on-demand id (or a retry, when inPlace: the entry is
+  // already on the stack). Never throws and never leaves a promise unhandled:
+  // every outcome is the modal, the loading card, or the error card.
+  function openRemote(self, cfg, id, props, opts, inPlace) {
     var body = env.doc.body
-    var shown = false
+    var shown = !!inPlace
     var hold = null
     var done = false
+    var timer = null
     if (self._remote[id] === 'error') delete self._remote[id]
+    delete self._remoteReason[id]
+    var minLoad = function () { return (win.StudioModals && win.StudioModals.MIN_LOAD_MS) || MIN_LOAD_MS }
 
-    var timer = win.setTimeout(function () {
-      if (done || env.doc.body !== body) return
-      shown = true
-      hold = holdAtLeast((win.StudioModals && win.StudioModals.MIN_LOAD_MS) || MIN_LOAD_MS)
+    if (inPlace) {
+      hold = holdAtLeast(minLoad())
       self._remote[id] = 'loading'
-      openNow.call(self, id, props, opts)
-    }, LOAD_DELAY_MS)
+    } else {
+      timer = win.setTimeout(function () {
+        if (done || env.doc.body !== body) return
+        shown = true
+        hold = holdAtLeast(minLoad())
+        self._remote[id] = 'loading'
+        openNow.call(self, id, props, opts)
+      }, LOAD_DELAY_MS)
+    }
 
-    function fail() {
+    function stopTimer() { if (timer !== null && win.clearTimeout) win.clearTimeout(timer) }
+    // Only while this modal is on top: a late answer must not pull focus off another card.
+    function refocusIfTop() { var top = self.current(); if (top && top.id === id) self.refocus() }
+
+    function fail(err) {
       if (done) return
       done = true
-      win.clearTimeout && win.clearTimeout(timer)
+      stopTimer()
       if (env.doc.body !== body) return
+      if (cfg.debug && err && err.studioModal) self._remoteReason[id] = err.message
       self._remote[id] = 'error'
       if (!shown) openNow.call(self, id, props, opts)
+      else refocusIfTop()
     }
 
     remote.load(cfg, id).then(function (markup) {
       if (done) return
-      if (env.doc.body !== body) { done = true; win.clearTimeout && win.clearTimeout(timer); return }
+      if (env.doc.body !== body) { done = true; stopTimer(); return }
       if (!remote.insert(id, markup)) { fail(); return }
       done = true
-      win.clearTimeout && win.clearTimeout(timer)
+      stopTimer()
       if (!shown) { openNow.call(self, id, props, opts); return }
       hold.then(function () {
-        if (self._remote[id] === 'loading') delete self._remote[id]
+        if (self._remote[id] === 'loading') { delete self._remote[id]; refocusIfTop() }
       })
     }).catch(fail)
   }
 
-  // Schedules the advertised prefetches once, when the browser idles.
+  // Schedules the advertised prefetches when the browser idles: once now, for
+  // the first load, and again after every Turbo visit. load() shares one
+  // request per id, so the first load's turbo:load adds no second fetch.
   if (env.doc && typeof env.doc.querySelector === 'function') {
     whenIdle(win, function () { remote.prefetch() })
+    if (typeof env.doc.addEventListener === 'function') {
+      env.doc.addEventListener('turbo:load', function () {
+        whenIdle(win, function () { remote.prefetch() })
+      })
+    }
   }
 
   function openNow(id, props, opts) {

data/app/views/studio/modals/_host.html.erb

@@ -219,10 +219,19 @@
     fetches a registered id the first time it opens and inserts its
     <template x-if> into the card. See the README, "Modals on demand". %>
 <% studio_remote_modals = Studio.modals.any? %>
+<% if studio_remote_modals
+     studio_remote_session = respond_to?(:controller) && controller.respond_to?(:session) ? controller.session : nil
+     studio_remote_config = Studio.modals.client_config(
+       url_template: studio_modal_path(id: "0").delete_suffix("0") + "__id__",
+       logged_in: respond_to?(:logged_in?) && logged_in?,
+       session: Studio::Modals.session_marker(studio_remote_session),
+       debug: defined?(Rails) && Rails.respond_to?(:env) && (Rails.env.development? || Rails.env.test?)
+     )
+   end %>
 <template x-if="$store.modals.current()"
           data-studio-controller="modal-host"
           data-modal-host-store-value="modals"<% if studio_remote_modals %>
-          data-modal-host-remote-value="<%= Studio.modals.client_config(url_template: studio_modal_path(id: "0").delete_suffix("0") + "__id__", logged_in: respond_to?(:logged_in?) && logged_in?).to_json %>"<% end %>>
+          data-modal-host-remote-value="<%= studio_remote_config.to_json %>"<% end %>>
   <%# Backdrop + card use CSS keyframe animations (NOT Alpine
       x-transition), all shipped in the inline style block above. On
       mount, the .modal-backdrop-mount + card mount classes fire fade-in
@@ -312,22 +321,28 @@
       <%# The on-demand states, keyed on $store.modals._remote[id], which only
           studio/modal_host sets and only for a registered id: 'loading' while a
           slow first fetch runs (the processing card, held MIN_LOAD_MS so it
-          never flashes), 'error' when the fetch fails (the error card, whose
-          button closes). Fetched registrations are appended after these. %>
+          never flashes; role="status", so a screen reader hears it politely),
+          'error' when the fetch fails, times out (Studio.modals.fetch_timeout_ms)
+          or is refused (the error card: Try again re-runs the fetch in place,
+          Close closes). Close calls close() directly, so it works on a card
+          opened dismissible: false too, which Escape and the backdrop do not
+          close. Fetched registrations are appended after these. %>
       <% if studio_remote_modals %>
         <template x-if="$store.modals._remote && $store.modals._remote[$store.modals.current()?.id] === 'loading'">
-          <div data-modal-remote-state="loading">
+          <div data-modal-remote-state="loading" role="status" aria-live="polite">
             <%= render "studio/modals/blocks/processing_card", title: "Loading…" %>
           </div>
         </template>
         <template x-if="$store.modals._remote && $store.modals._remote[$store.modals.current()?.id] === 'error'">
-          <div data-modal-remote-state="error">
+          <div data-modal-remote-state="error" @studio-modal-retry="$store.modals.retryRemote()">
             <%= render "studio/modals/blocks/error_card",
                   title: "Couldn't open this",
-                  message: "Check your connection and try again.",
+                  message_key: "$store.modals.remoteErrorText()",
                   icon_emoji: "⚠️",
-                  cta_label: "Close",
-                  cta_close: true %>
+                  cta_label: "Try again",
+                  cta_event: "studio-modal-retry",
+                  secondary_label: "Close",
+                  secondary_close: true %>
           </div>
         </template>
       <% end %>

data/app/views/style/_primitives.html.erb

@@ -93,14 +93,15 @@
     <h3 class="type-h4 text-heading">Table · sorted by member, a badge cell</h3>
     <div class="card overflow-hidden">
       <%= render Studio::TableComponent.new(rows: people, columns: columns, sort: "name", direction: "asc",
-            sort_url: sort_url, min_width: 520) %>
+            sort_url: sort_url, min_width: 520, caption: "Team members, sorted by member") %>
     </div>
   </div>
 
   <div class="space-y-3" data-specimen="table-empty">
     <h3 class="type-h4 text-heading">Table · no rows</h3>
     <div class="card overflow-hidden">
-      <%= render Studio::TableComponent.new(rows: [], columns: columns, sort_url: sort_url, empty: "No members yet.") %>
+      <%= render Studio::TableComponent.new(rows: [], columns: columns, sort_url: sort_url, empty: "No members yet.",
+            aria_label: "Team members") %>
     </div>
   </div>
 </div>

data/lib/studio/modals.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Studio
   # The on-demand modal registry: modals the shared host (studio/modals/_host)
   # fetches the first time they open, instead of the layout rendering every
@@ -22,11 +24,14 @@ module Studio
   #             (one root element; see the README's "Modal host" rules).
   #   auth:     :any (default) or :user. A :user modal answers 401 to a
   #             signed-out request, and is never prefetched for one.
-  #   prefetch: true fetches the modal when the browser idles after load, for a
-  #             modal that should open with no wait (the sign-in card).
+  #   prefetch: true fetches the modal when the browser idles after load and
+  #             after every Turbo visit, for a modal that should open with no
+  #             wait (the sign-in card).
   #   locals:   the partial's locals. A Hash, a Symbol naming a helper the view
   #             answers (Turf's existing *_modal_locals helpers), or a callable
-  #             taking the view. Resolved per request, inside the view.
+  #             taking the view. Resolved per request, inside the view of
+  #             Studio::ModalsController: helpers and the session are there,
+  #             the page's instance variables (@contest) are not.
   module Modals
     AUTH_LEVELS = %i[any user].freeze
 
@@ -54,8 +59,23 @@ module Studio
     end
 
     class Registry
+      # How long studio/modal_host waits for a fragment before it gives up and
+      # shows the error card (with Try again and Close), in milliseconds.
+      DEFAULT_FETCH_TIMEOUT_MS = 8000
+
+      # Settable from the initializer: Studio.modals.fetch_timeout_ms = 12_000.
+      attr_reader :fetch_timeout_ms
+
       def initialize
         @entries = {}
+        @fetch_timeout_ms = DEFAULT_FETCH_TIMEOUT_MS
+      end
+
+      def fetch_timeout_ms=(value)
+        ms = Integer(value)
+        raise ArgumentError, "Studio.modals.fetch_timeout_ms must be positive, got #{value.inspect}" unless ms.positive?
+
+        @fetch_timeout_ms = ms
       end
 
       def register(id, partial:, auth: :any, prefetch: false, locals: nil)
@@ -85,16 +105,48 @@ module Studio
       # What the host template advertises to studio/modal_host. Every id, so a
       # signed-out open of a :user modal still reaches the endpoint and shows
       # the error card; prefetch only what this viewer may load.
-      def client_config(url_template:, logged_in:)
+      #
+      # session: the marker studio/modal_host keys its fragment cache on (see
+      # Modals.session_marker). debug: true in development and test, where a
+      # refused fragment names its reason on the error card.
+      def client_config(url_template:, logged_in:, session: nil, debug: false)
         {
           url: url_template,
           ids: ids,
-          prefetch: entries.select { |e| e.prefetch && (!e.user_only? || logged_in) }.map(&:id)
+          prefetch: entries.select { |e| e.prefetch && (!e.user_only? || logged_in) }.map(&:id),
+          timeout_ms: fetch_timeout_ms,
+          session: session.to_s,
+          debug: debug == true
         }
       end
     end
   end
 
+  module Modals
+    # THE SESSION MARKER. A fetched fragment can carry the viewer's data and a
+    # form's CSRF token, and studio/modal_host keeps it for the page's life. A
+    # Turbo visit across sign-in, sign-out or a user switch keeps that page, so
+    # the browser compares this marker on every open and every turbo:load and
+    # drops its cache when it changes.
+    #
+    # It digests two things the request already has:
+    #   - the session id, which reset_session rotates (sign-out, and the
+    #     sign-ins that reset), and with it the session's CSRF secret: a cached
+    #     form token stops being valid exactly when this changes;
+    #   - the signed-in user id under Studio.session_key, which a sign-in that
+    #     does NOT reset the session (an OAuth or wallet sign-in) still changes.
+    # Digested so neither value reaches the page. A request with no session
+    # (a view rendered outside a controller) answers the digest of nothing:
+    # a constant, so the cache simply lives for the page, as before.
+    def self.session_marker(session)
+      sid = session.respond_to?(:id) ? session.id.to_s : ""
+      uid = session.respond_to?(:[]) ? session[Studio.session_key].to_s : ""
+      Digest::SHA256.hexdigest("#{sid}|#{uid}")[0, 16]
+    rescue StandardError
+      Digest::SHA256.hexdigest("|")[0, 16]
+    end
+  end
+
   def self.modals
     @modals ||= Modals::Registry.new
   end

data/lib/studio/system_test_case.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# Studio::SystemTestCase: the one browser-test base every host app inherits.
+#
+# A host's test/application_system_test_case.rb becomes:
+#
+#   require "test_helper"
+#   require "studio/system_test_case"
+#
+#   class ApplicationSystemTestCase < Studio::SystemTestCase
+#     driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1000]
+#   end
+#
+# It owns the harness bugs that were fixed app by app, so a fix ships once, in
+# the gem, to every app. Detail and the customization API: docs/SYSTEM_TESTS.md.
+#
+# lib/studio.rb does NOT require this file. It needs Capybara and
+# selenium-webdriver, which a host bundles in its test group and the gem does
+# not declare. The host requires it from its system-test base only.
+require "action_dispatch/system_test_case"
+require "capybara/selenium/driver"
+
+module Studio
+  class SystemTestCase < ActionDispatch::SystemTestCase
+    # The harness hooks this base runs, by name. A subclass opts out of one by
+    # name, with a reason (skip_harness_hook); every other hook still runs.
+    HOOKS = {
+      reset_window: "setup: resize the window to desktop_size. The browser outlives " \
+                    "the test, so a resize leaks into the next test (commercial-welding " \
+                    "went red under one seed).",
+      restore_script_timeout: "around evaluate_async_script: give back the script " \
+                              "timeout. Capybara 3.40.0 sets it to default_max_wait_time " \
+                              "(2s) and never restores it (voicebox ContrastSystemTest).",
+      clear_emulation: "teardown: clear the DevTools device-metrics and emulated-media " \
+                       "overrides (phone_viewport!, a dark-mode or reduced-motion test), " \
+                       "so neither leaks into the next test."
+    }.freeze
+
+    # Selenium's stock read budget is Net::HTTP's 60s. A cold Chrome launch on a
+    # slow CI runner can pass it, and the run dies with Net::ReadTimeout in
+    # whichever test the seed put first (hub PR #2494).
+    DEFAULT_READ_TIMEOUT = 180
+    DEFAULT_DESKTOP_SIZE = [1400, 1000].freeze
+
+    # Thread-local switch the restore_script_timeout hook reads. The prepend on
+    # Capybara's driver is global; this key makes the opt-out per test class.
+    SCRIPT_TIMEOUT_KEY = :studio_system_test_restore_script_timeout
+
+    # The window every test starts in. Set it through driven_by's screen_size,
+    # so the browser's launch size and the reset size are one number.
+    class_attribute :desktop_size, instance_accessor: false, default: DEFAULT_DESKTOP_SIZE
+    # The phone viewport phone_viewport! and assert_viewport_width default to.
+    class_attribute :phone_width, instance_accessor: false, default: 390
+    class_attribute :phone_height, instance_accessor: false, default: 844
+    # { hook name => reason } for the hooks this class opted out of.
+    class_attribute :skipped_harness_hooks, instance_accessor: false, default: {}.freeze
+
+    class << self
+      # Rails' driven_by, with two additions. screen_size also becomes
+      # desktop_size, the size reset_window restores. A Selenium driver gets a
+      # 180s read timeout unless options: names its own :timeout.
+      def driven_by(driver = :selenium, using: :headless_chrome, screen_size: DEFAULT_DESKTOP_SIZE,
+                    options: {}, &capabilities)
+        self.desktop_size = Array(screen_size).dup.freeze
+        options = { timeout: DEFAULT_READ_TIMEOUT }.merge(options) if driver.to_sym == :selenium
+        super(driver, using: using, screen_size: screen_size, options: options, &capabilities)
+      end
+
+      # Opt this class (and its subclasses) out of one harness hook. The name
+      # must be in HOOKS and the reason must say why; both are logged once, so a
+      # skipped fix is never silent.
+      def skip_harness_hook(name, reason:)
+        name = name.to_sym
+        unless HOOKS.key?(name)
+          raise ArgumentError, "unknown harness hook #{name.inspect}; the hooks are #{HOOKS.keys.map(&:inspect).join(', ')}"
+        end
+        raise ArgumentError, "skip_harness_hook #{name.inspect} needs a reason:" if reason.to_s.strip.empty?
+
+        self.skipped_harness_hooks = skipped_harness_hooks.merge(name => reason.to_s.strip).freeze
+        warn "[Studio::SystemTestCase] #{self.name || inspect} skips the #{name} hook: #{reason.to_s.strip}"
+      end
+
+      def harness_hook?(name)
+        !skipped_harness_hooks.key?(name.to_sym)
+      end
+
+      # Read by the driver prepend below. nil (no Studio test running on this
+      # thread) means on: the restore is a pure bug fix.
+      def restore_script_timeout?
+        Thread.current[SCRIPT_TIMEOUT_KEY] != false
+      end
+    end
+
+    # Capybara 3.40.0's evaluate_async_script sets the browser's script timeout
+    # to Capybara.default_max_wait_time (2s) and never sets it back. The browser
+    # outlives the test, so every later execute_script in the run has 2s, not the
+    # driver's 30s. This gives back the timeout it borrowed (voicebox PR #35).
+    module RestoresScriptTimeout
+      def evaluate_async_script(script, *args)
+        return super unless Studio::SystemTestCase.restore_script_timeout?
+
+        timeouts = browser.manage.timeouts
+        previous = timeouts.script_timeout
+        super
+      ensure
+        timeouts.script_timeout = previous if previous
+      end
+    end
+    Capybara::Selenium::Driver.prepend(RestoresScriptTimeout)
+
+    driven_by :selenium, using: :headless_chrome, screen_size: DEFAULT_DESKTOP_SIZE
+
+    # The base's setup runs before any setup a subclass declares, so an app's
+    # own setup always starts in the reset window.
+    setup do
+      Thread.current[SCRIPT_TIMEOUT_KEY] = self.class.harness_hook?(:restore_script_timeout)
+      reset_window if self.class.harness_hook?(:reset_window) && browser_window?
+    end
+
+    # Teardown callbacks run in reverse: a subclass's teardown runs first, then
+    # this one.
+    teardown do
+      clear_emulation if self.class.harness_hook?(:clear_emulation) && devtools?
+    ensure
+      Thread.current[SCRIPT_TIMEOUT_KEY] = nil
+    end
+
+    def reset_window
+      page.driver.browser.manage.window.resize_to(*self.class.desktop_size)
+    end
+
+    # A real phone-width viewport. Headless Chrome will not size its window
+    # under 500px, so resize_to(390, ...) gives a 500px page and a "390px" check
+    # passes at the wrong width. DevTools device-metrics emulation sets the
+    # viewport itself. After each visit, before you measure, call
+    # assert_viewport_width. The clear_emulation hook clears it in teardown.
+    def phone_viewport!(width = self.class.phone_width, height = self.class.phone_height)
+      page.driver.browser.execute_cdp("Emulation.setDeviceMetricsOverride",
+                                      width: width, height: height, deviceScaleFactor: 1, mobile: true)
+    end
+
+    # Reads clientWidth, not innerWidth: under mobile emulation innerWidth grows
+    # to fit a page that overflows, so a check against it passes vacuously.
+    # Phone widths only: a desktop Linux Chrome takes 15px of clientWidth for
+    # its scrollbar.
+    def assert_viewport_width(width = self.class.phone_width)
+      assert_equal width, evaluate_script("document.documentElement.clientWidth"), "the viewport is #{width}px"
+    end
+
+    # Clears both DevTools overrides a test may set: the phone viewport and the
+    # emulated media (prefers-color-scheme, prefers-reduced-motion, print).
+    def clear_emulation
+      page.driver.browser.execute_cdp("Emulation.clearDeviceMetricsOverride")
+      page.driver.browser.execute_cdp("Emulation.setEmulatedMedia", media: "", features: [])
+    end
+
+    private
+
+    # A real browser window: Selenium, not rack_test. A subclass driven by
+    # rack_test skips the browser hooks without opting out.
+    def browser_window?
+      page.driver.respond_to?(:browser) && page.driver.browser.respond_to?(:manage)
+    end
+
+    # A Chromium browser that takes DevTools commands.
+    def devtools?
+      browser_window? && page.driver.browser.respond_to?(:execute_cdp)
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.143.2"
+  VERSION = "0.144.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.143.2
+  version: 0.144.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -1022,6 +1022,7 @@ files:
 - lib/studio/survey.rb
 - lib/studio/survey/breakdown.rb
 - lib/studio/survey/export.rb
+- lib/studio/system_test_case.rb
 - lib/studio/tailwind_entry.rb
 - lib/studio/theme_resolver.rb
 - lib/studio/tricks.rb