studio-engine 0.141.3 → 0.142.0

data/app/javascript/studio/in_page_links.js

@@ -37,12 +37,24 @@ export const STATE_KEY = "studioInPage"
 // The mark on a target that took tabindex=-1 for focus here; engine.css draws no ring on it.
 export const FOCUS_MARK = "data-in-page-focus"
 // No scroll for this long ends the scroll, where the browser has no scrollend event. Where it
-// has one, only scrollend ends a scroll that moved: on a slow main thread (a phone, or CI at
-// 8x CPU) a smooth scroll's frames come further apart than this, and a quiet spell ended the
-// jump at its first frame. Then the target moved and nothing aimed again.
+// has one, scrollend ends a scroll that moved (or the START_CAP_MS backstop below): on a slow
+// main thread (a phone, or CI at 8x CPU) a smooth scroll's frames come further apart than
+// this, and a quiet spell ended the jump at its first frame. Then the target moved and nothing
+// aimed again.
 export const SETTLE_MS = 150
 // A scroll the reader never sees move still ends: the cap for a scroll that never starts.
+// Where the browser has scrollend, it is also the backstop after each scroll event: a scroll
+// that scrollend never follows (a page that shortens, and the browser pulls the scroll back
+// with one scroll event and no scrollend) still ends. A slow frame (260ms at 8x CPU) does not.
 export const START_CAP_MS = 400
+// After the end, the target holds its place on the screen for this long: content above it
+// that grows or shrinks (a lazy frame the scroll passed, whose page lands later) moves the
+// page by the same amount, as scroll anchoring would. The body has anchoring off
+// (studio/_head: with it on, the navbar's collapse made the scroll bounce). The reader's own
+// input or any scroll the module did not make ends the hold at once. Growth later than this
+// is not followed: the window is bounded so a page that reflows long after a jump is the
+// reader's, not the jump's. At 8x CPU the lab's feed landed 0.5 to 1.7s after the end.
+export const HOLD_MS = 3000
 // A scroll aims again at a target that moved more than this, at most this many times.
 export const AIM_SLACK_PX = 2
 export const MAX_AIMS = 6
@@ -186,13 +198,67 @@ export function installInPageLinks(doc) {
     if (margin !== null) target.style.scrollMarginTop = inline
   }
   const pageTop = (target) => target.getBoundingClientRect().top + win.scrollY
+  const INPUTS = ["wheel", "touchstart", "keydown", "pointerdown"]
+
+  // After a jump's end: for HOLD_MS, a target that moved on the page moves the page with it,
+  // at once, so its place on the screen stays (scroll anchoring, for this one element). The
+  // check runs in the microtask after each change to the page's elements (a lazy frame's
+  // render), so no script and no frame sees the target out of place, and in each animation
+  // frame, for a size that changed with no new element (an image). It lets go at the first
+  // input, at any scroll that is not its own (the reader's scrollbar, an app's scrollTo, a
+  // clamp), at the next jump, at a Back or Forward, after MAX_AIMS moves, or at HOLD_MS.
+  const hold = (target) => {
+    if (!win.requestAnimationFrame) return
+    let held = win.scrollY
+    let top = target.getBoundingClientRect().top
+    let moves = 0
+    let frame = null
+    let timer = null
+    let observer = null
+    let done = false
+    const release = () => {
+      done = true
+      win.cancelAnimationFrame(frame)
+      win.clearTimeout(timer)
+      if (observer) observer.disconnect()
+      for (const name of INPUTS) win.removeEventListener(name, release, true)
+      if (settling === release) settling = null
+    }
+    const follow = () => {
+      if (done) return
+      // A scroll the hold did not make is the reader's or the app's: it lets go first.
+      if (Math.abs(win.scrollY - held) > AIM_SLACK_PX) return release()
+      // A target a render took out of the page has no place to keep.
+      if (target.isConnected === false) return release()
+      const now = target.getBoundingClientRect().top
+      if (Math.abs(now - top) <= AIM_SLACK_PX) return
+      if (moves >= MAX_AIMS) return release()
+      moves += 1
+      win.scrollBy({ top: now - top, behavior: "instant" })
+      held = win.scrollY
+      top = target.getBoundingClientRect().top
+    }
+    const check = () => {
+      follow()
+      if (!done) frame = win.requestAnimationFrame(check)
+    }
+    settling = release
+    if (win.MutationObserver) {
+      observer = new win.MutationObserver(follow)
+      observer.observe(doc.documentElement, { childList: true, subtree: true })
+    }
+    for (const name of INPUTS) win.addEventListener(name, release, { capture: true, passive: true })
+    timer = win.setTimeout(release, HOLD_MS)
+    frame = win.requestAnimationFrame(check)
+  }
 
   // One jump, from its start to its end. The browser fixes a smooth scroll's end where the
   // target was at the start. Content that grows on the way (a lazy frame the scroll passes,
   // the navbar's collapse) moves the target, so the scroll aims again, up to MAX_AIMS times,
   // until the reader takes over (a wheel, a touch, a key, a press). The end is the browser's
-  // scrollend where it has one, a quiet spell where not; then the end event, once. A scroll
-  // that never starts ends at the cap either way.
+  // scrollend where it has one (else START_CAP_MS after the last scroll event), a quiet spell
+  // where not; then the end event, once. A scroll that never starts ends at the cap either way. Then, unless the reader took over, the
+  // target holds its place for HOLD_MS (hold, above).
   const jump = (target, behavior) => {
     if (settling) settling()
     const hasScrollend = "onscrollend" in win
@@ -201,12 +267,15 @@ export function installInPageLinks(doc) {
     let aims = 0
     let reader = false
     let live = true
+    // A scroll event has come since the last aim. Chrome can send the scrollend of a scroll an
+    // aim replaced before the new scroll's first frame; that scrollend is not this aim's end.
+    let scrolled = false
     let aimed = pageTop(target)
     const takeOver = () => { reader = true }
-    const INPUTS = ["wheel", "touchstart", "keydown", "pointerdown"]
     const reaim = () => {
       if (reader || aims >= MAX_AIMS || Math.abs(pageTop(target) - aimed) <= AIM_SLACK_PX) return false
       aims += 1
+      scrolled = false
       scrollTo(target, behavior)
       aimed = pageTop(target)
       return true
@@ -220,28 +289,31 @@ export function installInPageLinks(doc) {
       // The target moved after the scroll stopped: aim once more and wait for that end.
       if (reaim()) return wait(START_CAP_MS)
       win.removeEventListener("scroll", onScroll)
-      win.removeEventListener("scrollend", end)
+      win.removeEventListener("scrollend", onScrollend)
       for (const name of INPUTS) win.removeEventListener(name, takeOver, true)
       win.clearTimeout(quiet)
       win.clearTimeout(cap)
       live = false
       if (settling === stop) settling = null
+      if (!reader) hold(target)
       doc.dispatchEvent(new win.CustomEvent(SCROLL_END_EVENT))
     }
     const onScroll = () => {
       win.clearTimeout(cap)
+      scrolled = true
       reaim()
-      // The scroll has started: with scrollend, it alone ends it (an aim's cap is spent too).
-      if (hasScrollend) win.clearTimeout(quiet)
-      else wait(SETTLE_MS)
+      // The scroll has started. With scrollend, scrollend ends it, and START_CAP_MS after the
+      // last scroll event is the backstop for a scroll that scrollend never follows.
+      wait(hasScrollend ? START_CAP_MS : SETTLE_MS)
     }
+    const onScrollend = () => { if (scrolled) end() }
     const stop = () => {
       reader = true
       end()
     }
     settling = stop
     win.addEventListener("scroll", onScroll, { passive: true })
-    if (hasScrollend) win.addEventListener("scrollend", end)
+    if (hasScrollend) win.addEventListener("scrollend", onScrollend)
     for (const name of INPUTS) win.addEventListener(name, takeOver, { capture: true, passive: true })
     cap = win.setTimeout(end, START_CAP_MS)
     scrollTo(target, behavior)
@@ -286,6 +358,8 @@ export function installInPageLinks(doc) {
       return
     }
     shownUrl = url
+    // The traversal's place wins over a jump or a hold still running.
+    if (settling) settling()
     // Turbo would start a restore visit; without Turbo the browser restores the scroll itself.
     if (event.state && event.state.turbo) {
       event.stopImmediatePropagation()

data/app/javascript/studio/modal_host.js

@@ -284,6 +284,170 @@ function focusTrap(env, held) {
   }
 }
 
+// ---- on-demand modals (Studio.modals) ---------------------------------------
+//
+// A host whose app registers modals with Studio.modals advertises them on its
+// template:
+//
+//   data-modal-host-remote-value='{"url":"/_studio/modals/__id__",
+//                                  "ids":["contest-rules",…],"prefetch":["auth"]}'
+//
+// and marks its card data-modal-host-card. open(id) for an advertised id whose
+// registration is not in the host yet fetches GET /_studio/modals/<id> once,
+// wraps the fragment in the same <template x-if> a layout would have rendered,
+// appends it to the card (in the host template's content, so every later mount
+// has it, and in a card already on screen), then opens. An id the host does not
+// advertise takes the plain open() path untouched.
+//
+// THE WAIT. A fetch that answers inside LOAD_DELAY_MS opens with no loading
+// state at all. A slower one opens the card with $store.modals._remote[id] =
+// 'loading' (the host's processing card), held at least MIN_LOAD_MS so it never
+// flashes, then clears the flag and the content takes its place. A failure sets
+// '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
+// (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.
+
+export const REMOTE_MODAL_ATTR = 'data-studio-remote-modal'
+export const LOAD_DELAY_MS = 150
+
+// The host template advertising on-demand modals, if this page has one.
+export function remoteHost(doc) {
+  return doc.querySelector ? doc.querySelector('template[data-modal-host-remote-value]') : null
+}
+
+// The advertised config, or null on a page without one (or with bad JSON).
+export function remoteConfig(doc) {
+  var el = remoteHost(doc)
+  if (!el) return null
+  try {
+    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 = []
+    return cfg
+  } catch (e) {
+    return null
+  }
+}
+
+// The <template x-if> a layout would have rendered around the partial. Ids are
+// held to [a-z0-9_-] by Studio::Modals, so splicing one into the expression
+// needs no escaping; anything else is refused before it gets here.
+export function remoteTemplate(doc, id, markup) {
+  var t = doc.createElement('template')
+  t.setAttribute(REMOTE_MODAL_ATTR, id)
+  t.setAttribute('x-if', "$store.modals.current()?.id === '" + id + "' && !$store.modals._remote['" + id + "']")
+  t.innerHTML = markup
+  return t
+}
+
+// Every card the fragment belongs in: the one inside the host template's
+// content, and any mounted on screen.
+function remoteCards(doc) {
+  var cards = []
+  var host = remoteHost(doc)
+  var inner = host && host.content && host.content.querySelector('[data-modal-host-card]')
+  if (inner) cards.push(inner)
+  var live = doc.querySelectorAll ? doc.querySelectorAll('[data-modal-host-card]') : []
+  for (var i = 0; i < live.length; i++) cards.push(live[i])
+  return cards
+}
+
+function hasRemote(card, id) {
+  var kids = card.children || []
+  for (var i = 0; i < kids.length; i++) {
+    if (kids[i].getAttribute && kids[i].getAttribute(REMOTE_MODAL_ATTR) === id) return true
+  }
+  return false
+}
+
+// Appends the registration to every card missing it. Answers whether the host
+// template now carries it (false: no marked card on this page).
+export function insertRemoteModal(doc, id, markup) {
+  var cards = remoteCards(doc)
+  if (cards.length === 0) return false
+  for (var i = 0; i < cards.length; i++) {
+    if (!hasRemote(cards[i], id)) cards[i].appendChild(remoteTemplate(doc, id, markup))
+  }
+  return true
+}
+
+export function remoteModalUrl(cfg, id) {
+  return cfg.url.replace('__id__', encodeURIComponent(id))
+}
+
+// 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.
+export function fetchRemoteModal(win, cfg, id) {
+  return win.fetch(remoteModalUrl(cfg, id), {
+    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)
+    }
+    return res.text()
+  })
+}
+
+// requestIdleCallback where the browser has it, else a timeout.
+export function whenIdle(win, fn) {
+  if (typeof win.requestIdleCallback === 'function') win.requestIdleCallback(fn, { timeout: 4000 })
+  else win.setTimeout(fn, 1500)
+}
+
+// The loader one shared store keeps in its closure.
+export function createRemoteModals(env) {
+  var doc = env.doc
+  var win = env.win
+  var pending = {}   // id -> Promise<markup>, while in flight or resolved
+  var ready = {}     // id -> markup, once resolved
+
+  function load(cfg, id) {
+    if (ready[id] !== undefined) return Promise.resolve(ready[id])
+    if (!pending[id]) {
+      pending[id] = fetchRemoteModal(win, cfg, id).then(function (markup) {
+        ready[id] = markup
+        return markup
+      }, function (err) {
+        delete pending[id]
+        throw err
+      })
+    }
+    return pending[id]
+  }
+
+  return {
+    // The config when id is advertised here, else null.
+    handles: function (id) {
+      if (typeof id !== 'string') return null
+      var cfg = remoteConfig(doc)
+      return (cfg && cfg.ids.indexOf(id) !== -1) ? cfg : null
+    },
+    load: load,
+    // Synchronous when the fragment is already here: inserts what this host
+    // lacks and answers true, so open() needs no wait.
+    insertIfReady: function (id) {
+      return ready[id] !== undefined && insertRemoteModal(doc, id, ready[id])
+    },
+    insert: function (id, markup) { return insertRemoteModal(doc, id, markup) },
+    prefetch: function () {
+      var cfg = remoteConfig(doc)
+      if (!cfg || typeof win.fetch !== 'function') return
+      cfg.prefetch.forEach(function (id) {
+        // A failed prefetch is retried by the open that needs it.
+        load(cfg, id).catch(function () {})
+      })
+    }
+  }
+}
+
 // ---- the shared host's store, $store.modals --------------------------------
 //
 // env is { doc, win }: the document, and the window that carries setTimeout,
@@ -293,13 +457,68 @@ export function createModalStore(env) {
   var held = { returnFocusTo: null, backdrop: null }
   var store = focusTrap(env, held)
   store.stack = []
+  // 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)
 
   // open(id, props, opts)
   //   opts.replace: swap the top entry. With a visible card, a directional
   //     slide: it exits right (modal-card-swap-out) and the new one enters
   //     left; opts.direction 'back' mirrors both. A plain mount when empty.
   //   otherwise: push. Closing the new card reveals the one beneath.
+  //   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)
+    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) {
+    var body = env.doc.body
+    var shown = false
+    var hold = null
+    var done = false
+    if (self._remote[id] === 'error') delete self._remote[id]
+
+    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)
+      self._remote[id] = 'loading'
+      openNow.call(self, id, props, opts)
+    }, LOAD_DELAY_MS)
+
+    function fail() {
+      if (done) return
+      done = true
+      win.clearTimeout && win.clearTimeout(timer)
+      if (env.doc.body !== body) return
+      self._remote[id] = 'error'
+      if (!shown) openNow.call(self, id, props, opts)
+    }
+
+    remote.load(cfg, id).then(function (markup) {
+      if (done) return
+      if (env.doc.body !== body) { done = true; win.clearTimeout && win.clearTimeout(timer); return }
+      if (!remote.insert(id, markup)) { fail(); return }
+      done = true
+      win.clearTimeout && win.clearTimeout(timer)
+      if (!shown) { openNow.call(self, id, props, opts); return }
+      hold.then(function () {
+        if (self._remote[id] === 'loading') delete self._remote[id]
+      })
+    }).catch(fail)
+  }
+
+  // Schedules the advertised prefetches once, when the browser idles.
+  if (env.doc && typeof env.doc.querySelector === 'function') {
+    whenIdle(win, function () { remote.prefetch() })
+  }
+
+  function openNow(id, props, opts) {
     props = props || {}
     opts = opts || {}
     var self = this

data/app/models/error_log.rb

@@ -1,9 +1,9 @@
 class ErrorLog < ApplicationRecord
-  # `slug` is unique (RequireSlugsOnEngineTables) and becomes NOT NULL a release
-  # later, so every insert carries one, including a host's bare
-  # `ErrorLog.create!`. Sluggable writes a unique placeholder before the insert
-  # and settles it to `error-log-<id>` right after, inside the create, once the
-  # id exists.
+  # `slug` is unique (RequireSlugsOnEngineTables) and refuses NULL (CHECK
+  # error_logs_slug_present, AddEngineNotNullChecks), so every insert carries
+  # one, including a host's bare `ErrorLog.create!`. Sluggable writes a unique
+  # placeholder before the insert and settles it to `error-log-<id>` right after,
+  # inside the create, once the id exists.
   include Sluggable
 
   belongs_to :target, polymorphic: true, optional: true

data/app/views/components/_empty_state.html.erb

@@ -1,7 +1,3 @@
 <%# locals: (message:, detail: nil) %>
-<div class="empty-state">
-  <p class="text-secondary text-lg"><%= message %></p>
-  <% if detail.present? %>
-    <p class="text-muted text-sm mt-1"><%= detail %></p>
-  <% end %>
-</div>
+<%# Kept for one release as a wrapper: Studio::EmptyStateComponent is the empty state now (docs/FRONT_END_STANDARD.md, "From partial to component"). -%>
+<%= render Studio::EmptyStateComponent.new(message: message, detail: detail) %>

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

@@ -212,9 +212,17 @@
     bound to this host by the modal-host controller on the template below. The
     store registers before Alpine starts; see that module's header. %>
 
+<%# ON-DEMAND MODALS (Studio.modals). Only when the app registers one does the
+    host advertise them (data-modal-host-remote-value), mark its card
+    (data-modal-host-card) and carry the loading and error cards below; an app
+    that registers none renders this partial exactly as before. studio/modal_host
+    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? %>
 <template x-if="$store.modals.current()"
           data-studio-controller="modal-host"
-          data-modal-host-store-value="modals">
+          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 %>>
   <%# 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
@@ -271,7 +279,8 @@
     <%# No max-w-* here — cardClasses() supplies exactly one, per modal id, from
         the CARD_WIDTHS registry (studio/modal_host). max-h/overflow are unrelated and stay. %>
     <div class="bg-surface rounded-xl border border-subtle shadow-2xl p-6 w-full max-h-[85dvh] overflow-y-auto"
-         :class="$store.modals.cardClasses()">
+         :class="$store.modals.cardClasses()"<% if studio_remote_modals %>
+         data-modal-host-card<% end %>>
       <%# Consumer-provided content registrations. Each block typically
           contains a <template x-if="$store.modals.current().id === 'X'">
           render "modals/X" </template>.
@@ -299,6 +308,29 @@
       <% if lookup_context.exists?("host_extras", ["modals"], true) %>
         <%= render "modals/host_extras" %>
       <% end %>
+
+      <%# 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. %>
+      <% if studio_remote_modals %>
+        <template x-if="$store.modals._remote && $store.modals._remote[$store.modals.current()?.id] === 'loading'">
+          <div data-modal-remote-state="loading">
+            <%= 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">
+            <%= render "studio/modals/blocks/error_card",
+                  title: "Couldn't open this",
+                  message: "Check your connection and try again.",
+                  icon_emoji: "⚠️",
+                  cta_label: "Close",
+                  cta_close: true %>
+          </div>
+        </template>
+      <% end %>
     </div>
   </div>
 </template>

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

@@ -0,0 +1,5 @@
+<%# One on-demand modal's content, as Studio::ModalsController serves it: the
+    registered partial with its locals, resolved in THIS view, and nothing else.
+    No layout, no script: studio/modal_host wraps it in the host's
+    <template x-if> on the client. %>
+<%= render @studio_modal.partial, @studio_modal.locals_for(self) %>

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

@@ -4,10 +4,13 @@
     The previews ARE the specimens, so this list cannot drift from the components.
     An app that does not draw the gallery here (lookbook not in its bundle, or
     production without Studio.lookbook_in_production) says so instead of linking
-    to a 404. -%>
+    to a 404. Above the list, style/_primitives draws the Button, EmptyState and
+    Table components live on every app, gallery or not. -%>
 <section id="components" class="section-target space-y-6">
   <%= render "studio/section_header", title: "Components" %>
-  <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
+  <p class="text-muted text-sm max-w-2xl">The UI primitives every app renders, live, then one preview per state in the component gallery.</p>
+
+  <%= render "style/primitives" %>
 
   <% if Studio.lookbook_mounted? %>
     <ul class="grid gap-4 sm:grid-cols-2" data-component-previews>

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

@@ -11,7 +11,7 @@
 <section class="space-y-4" data-test="style-glass">
   <div>
     <h3 class="type-h4 text-heading">Glass</h3>
-    <p class="text-sm text-secondary mt-1">Each one is opt-in per app.</p>
+    <p class="text-sm text-secondary mt-1">The standard for a new app. An existing app turns each switch on itself.</p>
   </div>
   <div class="grid gap-4 md:grid-cols-2">
     <%= render layout: "style/specimen",
@@ -64,6 +64,14 @@
         </div>
       </div>
     <% end %>
+    <%= render layout: "style/specimen",
+          locals: { trick: "glass", variant: "tile",
+                    disabled: !surface_on, disabled_label: "surface style is off on this app" } do %>
+      <div class="flex flex-wrap items-center gap-3" data-test="style-lit-tiles">
+        <a href="#tricks" class="lit-tile inline-flex min-h-12 items-center bg-primary px-5 text-xs font-bold uppercase tracking-wide text-white">.lit-tile</a>
+        <a href="#tricks" class="lit-tile-soft inline-flex min-h-12 items-center border border-subtle px-5 text-xs font-bold uppercase tracking-wide text-heading">.lit-tile-soft</a>
+      </div>
+    <% end %>
     <%= render layout: "style/specimen",
           locals: { trick: "icon" } do %>
       <ul class="grid grid-cols-4 gap-3 w-full text-heading" data-test="style-glass-icons">

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

@@ -0,0 +1,106 @@
+<%# locals: () -%>
+<%# The engine's UI primitives, drawn live: every tone, size and state of
+    Studio::ButtonComponent, Studio::EmptyStateComponent and
+    Studio::TableComponent. Rendered from the components themselves, never a
+    copy of their markup, so a change to a component changes its specimen.
+
+    LIGHT AND DARK. Each specimen renders once and follows the page's theme: the
+    theme tokens are scoped to html and html.dark (Studio::ThemeResolver), and
+    nothing scopes a panel back to light inside a dark page. Flip the theme to
+    see the other one; e2e/ui_primitives_screenshots.spec.js captures both.
+
+    e2e/ui_primitives_screenshots.spec.js screenshots each [data-specimen] block
+    (the lab page /lab/ui_primitives renders this partial). Renaming one moves a
+    baseline. -%>
+<%
+  tones = Studio::ButtonComponent::TONES.keys
+  sizes = Studio::ButtonComponent::SIZES.keys
+  plus = tag.svg(tag.path(d: "M10 4a1 1 0 0 1 1 1v4h4a1 1 0 1 1 0 2h-4v4a1 1 0 1 1-2 0v-4H5a1 1 0 1 1 0-2h4V5a1 1 0 0 1 1-1Z"),
+                 class: "h-4 w-4", viewBox: "0 0 20 20", fill: "currentColor", aria: { hidden: true })
+  people = [
+    { name: "Ada Lovelace", role: "Admin", tasks: 12, status: "passed" },
+    { name: "Grace Hopper", role: "Builder", tasks: 7, status: "blocked" },
+    { name: "Katherine Johnson", role: "Reviewer", tasks: 3, status: "waiting" }
+  ]
+  status_tones = { "passed" => :success, "blocked" => :danger, "waiting" => :warning }
+  columns = [
+    { key: :name, label: "Member", sortable: true },
+    { key: :role, label: "Role" },
+    { key: :tasks, label: "Tasks", sortable: true, align: :right },
+    { key: :status, label: "Status", align: :center,
+      cell: ->(row) { render Studio::BadgeComponent.new(text: row[:status], tone: status_tones.fetch(row[:status])) } }
+  ]
+  sort_url = ->(key, direction) { "?sort=#{key}&direction=#{direction}#components" }
+-%>
+<div class="space-y-6" data-primitives>
+  <div class="card p-5 space-y-3" data-specimen="button-tones">
+    <h3 class="type-h4 text-heading">Button · tones</h3>
+    <div class="flex flex-wrap items-center gap-3">
+      <% tones.each do |tone| %>
+        <%= render Studio::ButtonComponent.new(label: tone.to_s.capitalize, tone: tone) %>
+      <% end %>
+    </div>
+  </div>
+
+  <div class="card p-5 space-y-3" data-specimen="button-sizes">
+    <h3 class="type-h4 text-heading">Button · sizes</h3>
+    <% tones.each do |tone| %>
+      <div class="flex flex-wrap items-center gap-3">
+        <% sizes.each do |size| %>
+          <%= render Studio::ButtonComponent.new(label: "#{tone.to_s.capitalize} #{size}", tone: tone, size: size) %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+
+  <div class="card p-5 space-y-3" data-specimen="button-states">
+    <h3 class="type-h4 text-heading">Button · disabled, loading, icon, link</h3>
+    <div class="flex flex-wrap items-center gap-3">
+      <% tones.each do |tone| %>
+        <%= render Studio::ButtonComponent.new(label: tone.to_s.capitalize, tone: tone, disabled: true) %>
+      <% end %>
+    </div>
+    <div class="flex flex-wrap items-center gap-3">
+      <% tones.each do |tone| %>
+        <%= render Studio::ButtonComponent.new(label: tone.to_s.capitalize, tone: tone, loading: true) %>
+      <% end %>
+      <%= render Studio::ButtonComponent.new(label: "Save", type: "submit", loading: true, busy_label: "Saving…") %>
+    </div>
+    <div class="flex flex-wrap items-center gap-3">
+      <%= render(Studio::ButtonComponent.new(label: "New task")) { |button| button.with_icon { plus } } %>
+      <%= render Studio::ButtonComponent.new(label: "Read the docs", tone: :quiet, href: "#components") %>
+      <%= render Studio::ButtonComponent.new(label: "Disabled link", tone: :quiet, href: "#components", disabled: true) %>
+    </div>
+  </div>
+
+  <div class="grid gap-6 md:grid-cols-2">
+    <div class="space-y-3" data-specimen="empty-state">
+      <h3 class="type-h4 text-heading">Empty state · message and detail</h3>
+      <%= render Studio::EmptyStateComponent.new(message: "No errors logged yet.",
+            detail: "Errors appear here when ErrorLog.capture! records one.") %>
+    </div>
+    <div class="space-y-3" data-specimen="empty-state-action">
+      <h3 class="type-h4 text-heading">Empty state · icon and action</h3>
+      <%= render(Studio::EmptyStateComponent.new(detail: "Invite someone to start the team.")) do |empty| %>
+        <% empty.with_icon { plus } %>
+        <% empty.with_action(label: "Invite a member", href: "#components") %>
+        No members yet.
+      <% end %>
+    </div>
+  </div>
+
+  <div class="space-y-3" data-specimen="table">
+    <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) %>
+    </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.") %>
+    </div>
+  </div>
+</div>