studio-engine 0.95.0 → 0.96.0

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

@@ -7,10 +7,9 @@
 
       resolveAt = max(min_duration, actual_completion)
 
-  This ships the convention on window.StudioModals, defined ONCE here and
-  rendered by BOTH the shared modal host (studio/modals/_host) and the living
-  style guide (style/_modals) — so every consumer app and the /admin/style demo
-  page share a single definition:
+  studio/modal_host publishes it on window.StudioModals on every page, merged
+  over anything an app defined first, so every consumer app and the
+  /admin/style demo page share a single definition:
 
     MIN_LOAD_MS  — the standard default minimum (1400 ms). A caller may pass its
                    own, but reach for this so every load modal feels consistent.
@@ -29,27 +28,7 @@
                      min_duration exactly:
                        StudioModals.holdAtLeast(StudioModals.MIN_LOAD_MS).then(advance);
 
-  Idempotent (|| guards): never clobber a definition an app already shipped, and
-  safe to render more than once on a page.
+  THIS PARTIAL RENDERS NOTHING. It carried the convention as an inline script
+  until the modal host moved to studio/modal_host; it stays, empty, so an app
+  that still renders it by name gets no missing-template error.
 %>
-<script>
-  (function () {
-    window.StudioModals = window.StudioModals || {};
-    // Standard minimum-visible duration for a load spinner, in ms. ~1200–1500
-    // reads as "processing → done"; below ~1s the spinner flashes and reads as a
-    // glitch. Callers may override per-modal, but default to this for consistency.
-    window.StudioModals.MIN_LOAD_MS = window.StudioModals.MIN_LOAD_MS || 1400;
-    // holdAtLeast(minMs).then(cb) — cb fires at max(minMs, elapsed-since-call).
-    // Stamp the moment a loading view becomes visible; the anti-flicker floor.
-    window.StudioModals.holdAtLeast = window.StudioModals.holdAtLeast || function (minMs) {
-      var startedAt = Date.now();
-      return {
-        then: function (callback) {
-          var remaining = Math.max(0, minMs - (Date.now() - startedAt));
-          if (remaining === 0) { callback(); return; }
-          setTimeout(callback, remaining);
-        }
-      };
-    };
-  })();
-</script>

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

@@ -24,6 +24,9 @@
 
   Both go away when the page owns its host.
 
+  The behaviour (the stack, the focus trap shared with the app's host, the
+  cleanup) is studio/modal_host; this partial renders markup only.
+
   Animations come from the shared motion layer
   (app/assets/tailwind/studio_engine/engine-motion.css) — the .modal-card-* and
   .modal-backdrop-* classes — rather than an inline copy, so this stays small.
@@ -95,263 +98,17 @@
   body.modal-open { overflow: visible; }
 </style>
 
-<script>
-  (function() {
-    var STORE_NAME    = '<%= scoped_store %>';
-    // Keep in sync with .modal-card-unmount in engine-motion.css — the entry is
-    // spliced off the stack only after the exit animation has played.
-    var CLOSE_ANIM_MS = 220;
-
-    // window.StudioModals.holdAtLeast(ms) — the minimum-visible-duration
-    // convention shared with the app-level host, so a spinner can't flash past
-    // the user. Defined defensively: this page may be the only host on it.
-    window.StudioModals = window.StudioModals || {};
-    window.StudioModals.holdAtLeast = window.StudioModals.holdAtLeast || function(minMs) {
-      var startedAt = Date.now();
-      return {
-        then: function(callback) {
-          var remaining = Math.max(0, minMs - (Date.now() - startedAt));
-          if (remaining === 0) { callback(); return; }
-          setTimeout(callback, remaining);
-        }
-      };
-    };
-
-    // Named, so the dual-guard below can call it directly on a Turbo visit.
-    // Alpine's deferred script fires alpine:init exactly ONCE per full document
-    // load; this registration lives in a PAGE BODY, so it was absent during that
-    // one init. Without the guard, a Turbo Drive visit to this page leaves the
-    // store undefined and every x-data on it throws.
-    var _returnFocusTo = null;
-    // The backdrop node, kept in the same closure and for the same proxy reason.
-    var _backdropEl = null;
-
-    function registerScopedStore() {
-      if (Alpine.store(STORE_NAME)) return;
-
-      Alpine.store(STORE_NAME, {
-        stack: [],
-
-        // FOCUS — the same contract as the shared host (studio/modals/_host).
-        // Both hosts render [role=dialog]; a fix in only one of them leaves every
-        // page that brings its own store still trapping keyboard users behind an
-        // overlay, which is the "engine-wide" half of this defect.
-        //
-        // The return target is held in the closure below, NOT on the store: an
-        // Alpine store is a reactive Proxy, so a DOM node assigned to it reads back
-        // as a proxy and every identity check against it (===, contains) is false.
-        captureFocus: function(el) {
-          _returnFocusTo = document.activeElement;
-          _backdropEl = el;
-          if (el && el.focus) el.focus();
-        },
-
-        // RE-FOCUS AFTER A REPLACE, without re-capturing the return target. See
-        // the long note in _host.html.erb: captureFocus runs from x-init on the
-        // backdrop, and a replace keeps current() truthy, so the outer template
-        // never re-mounts and x-init never re-runs. The inner content DOES
-        // re-mount and unmounts the focused control, activeElement falls back to
-        // the document body, and the tab handler bound on the backdrop stops seeing
-        // the key. (Written out rather than as a literal tag: this comment ships
-        // inside the rendered script, and studio/emails asserts the page emits no
-        // body element of its own — a tag in prose trips it.)
-        // _returnFocusTo is untouched on purpose — re-capturing would overwrite
-        // the opener with a node inside the dialog.
-        refocus: function() {
-          var run = function() {
-            if (_backdropEl && _backdropEl.focus && document.contains(_backdropEl)) {
-              _backdropEl.focus();
-            }
-          };
-          if (window.Alpine && window.Alpine.nextTick) window.Alpine.nextTick(run);
-          else setTimeout(run, 0);
-        },
-
-        releaseFocus: function() {
-          var target = _returnFocusTo;
-          _returnFocusTo = null;
-          _backdropEl = null;
-          if (target && target.focus && document.contains(target)) target.focus();
-        },
-
-        focusables: function(el) {
-          if (!el) return [];
-          var sel = 'a[href], button:not([disabled]), input:not([disabled]), ' +
-                    'select:not([disabled]), textarea:not([disabled]), [tabindex]';
-          return Array.prototype.slice.call(el.querySelectorAll(sel)).filter(function(n) {
-            return n.tabIndex >= 0 && n.offsetParent !== null;
-          });
-        },
-
-        cycleFocus: function(el, event) {
-          var items = this.focusables(el);
-          if (items.length === 0) { if (el && el.focus) el.focus(); return; }
-
-          var idx = items.indexOf(document.activeElement);
-          var next;
-          if (event && event.shiftKey) {
-            next = idx <= 0 ? items[items.length - 1] : items[idx - 1];
-          } else {
-            next = (idx === -1 || idx === items.length - 1) ? items[0] : items[idx + 1];
-          }
-          next.focus();
-        },
-
-        dialogLabel: function() {
-          var entry = this.current();
-          if (!entry) return 'Dialog';
-          var p = entry.props || {};
-          // TRIMMED, not merely truthy. `title: '   '` is a truthy string, so it used to
-          // pass straight through — and the accessible-name computation then trims it to
-          // empty and announces a bare "dialog", the exact outcome this fallback chain
-          // exists to prevent. An empty string already fell through (it is falsy); a
-          // whitespace-only one did not, which is the more likely typo of the two.
-          var named = function(v) {
-            return (typeof v === 'string' && v.trim() !== '') ? v : null;
-          };
-          return named(p.ariaLabel) || named(p.title) || String(entry.id).replace(/[-_]/g, ' ');
-        },
-
-        // open(id, props, opts) — opts.replace swaps the top entry in place
-        // (what submitFormWithProgress does to turn crop-photo into saving).
-        open: function(id, props, opts) {
-          props = props || {};
-          opts  = opts  || {};
-          var entry = { id: id, props: props };
-
-          // Did this call re-mount the INNER content template without re-mounting the
-          // OUTER one? That is the whole question the focus trap turns on.
-          var remounted = false;
-          if (opts.replace && this.stack.length > 0) {
-            this.stack.splice(this.stack.length - 1, 1, entry);
-            remounted = true;
-          } else {
-            // THE COMMENT THIS REPLACES SAID "only on a REPLACE", on the premise that a
-            // fresh push takes current() falsy -> truthy so the outer template mounts and
-            // x-init captures for us. That is TRUE only when the stack was EMPTY, and
-            // silently false for a stacked push: current() was already truthy, so the
-            // outer template does not re-mount, x-init never re-runs, and the inner
-            // template unmounts whatever was focused. Focus lands on the document body — not a
-            // descendant of the backdrop — so the @keydown.tab handler bound there stops
-            // firing and native tabbing walks straight onto the page behind.
-            remounted = this.stack.length > 0;
-            this.stack.push(entry);
-          }
-          this._sync();
-          if (remounted) this.refocus();
-        },
-
-        swap: function(id, props, opts) {
-          opts = opts || {};
-          opts.replace = true;
-          this.open(id, props, opts);
-        },
-
-        // Flip _closing so the exit animation plays, then splice.
-        close: function() {
-          var entry = this.current();
-          if (!entry) return;
-
-          var self = this;
-          entry._closing = true;
-          setTimeout(function() {
-            var index = self.stack.indexOf(entry);
-            if (index !== -1) self.stack.splice(index, 1);
-            self._sync();
-            // Only when the LAST modal leaves — a stacked flow unmounts one dialog
-            // and mounts the next, and restoring in between yanks focus out of a
-            // flow the user is still inside.
-            //
-            // NOT RESTORING IS NOT THE SAME AS DOING NOTHING. Closing down TO an
-            // underlying modal re-mounts the inner template, so focus falls to the document body
-            // with that dialog still open — the trap is off while the user is still
-            // inside it. The gate was right; the else was missing.
-            if (self.stack.length === 0) self.releaseFocus();
-            else self.refocus();
-          }, CLOSE_ANIM_MS);
-        },
-
-        closeAll: function() {
-          // Teardown path (Turbo/bfcache): drop the target rather than restoring
-          // into a document that is about to be replaced.
-          _returnFocusTo = null;
-          this.stack = [];
-          this._sync();
-        },
-
-        // Keeps dismissible: false entries — a still-in-flight upload must not
-        // silently lose the card its promise will resolve against.
-        closeAllDismissible: function() {
-          this.stack = this.stack.filter(function(entry) {
-            return entry.props && entry.props.dismissible === false;
-          });
-          this._sync();
-          // Same re-mount, same release: a surviving non-dismissible card is still on
-          // screen and the cards dropped from under it took focus with them. Nothing is
-          // done when the stack empties — deliberately unlike close(): this is the
-          // Turbo/bfcache teardown path, where closeAll() already declines to restore
-          // into a document about to be replaced.
-          if (this.stack.length > 0) this.refocus();
-        },
-
-        // isOpen(id) — on the stack in ANY lifecycle state, including a card
-        // mid-close (close() flips _closing at once and splices only after
-        // CLOSE_ANIM_MS). isLive() below is the "still up" question.
-        isOpen: function(id) {
-          return this.stack.some(function(entry) { return entry.id === id; });
-        },
-
-        // isLive(id) / isLive([id, ...]) — on the stack and NOT on its way
-        // out. Mirrors the shared host's primitive so a page-scoped store
-        // answers the same question the same way; see studio/modals/_host
-        // for the full lifecycle rationale. Tests _closing ALONE: a leaving
-        // swap() entry carries _swappingOut AND _closing, so _swappingOut on
-        // its own must never count as leaving.
-        isLive: function(id) {
-          var ids = Array.isArray(id) ? id : [id];
-          return this.stack.some(function(entry) {
-            return entry && !entry._closing && ids.indexOf(entry.id) !== -1;
-          });
-        },
-
-        current: function() {
-          return this.stack.length ? this.stack[this.stack.length - 1] : null;
-        },
-
-        // Mount on open, unmount while closing. _settled pins the entry after
-        // its first render so a stale Alpine re-evaluation cannot re-fire the
-        // bounce-in keyframe mid-life (which reads as a flash).
-        cardClasses: function() {
-          var entry = this.current();
-          if (!entry) return '';
-          if (entry._closing) return 'modal-card-unmount';
-          if (!entry._settled) { entry._settled = true; }
-          return 'modal-card-mount';
-        },
-
-        _sync: function() {
-          document.body.classList.toggle('modal-open', this.stack.length > 0);
-        }
-      });
-    }
-
-    if (window.Alpine) { registerScopedStore(); }
-    else { document.addEventListener('alpine:init', registerScopedStore); }
-
-    // bfcache + Turbo snapshot cleanup, so a modal left open does not reappear
-    // on a back navigation.
-    function clearStaleScopedModals() {
-      if (!window.Alpine || !Alpine.store) return;
-
-      var store = Alpine.store(STORE_NAME);
-      if (store && typeof store.closeAllDismissible === 'function') store.closeAllDismissible();
-    }
-    window.addEventListener('pageshow', function(e) { if (e.persisted) clearStaleScopedModals(); });
-    document.addEventListener('turbo:before-cache', clearStaleScopedModals);
-  })();
-</script>
-
-<template x-if="$store.<%= scoped_store %>.current()">
+<%# THE STORE IS NOT HERE. $store.<store>, its focus trap and its bfcache / Turbo
+    snapshot cleanup are studio/modal_host (createScopedModalStore), bound to this
+    host by the modal-host controller on the template below. The module registers
+    the store from the template's data attributes before Alpine starts on a full
+    load and before a Turbo visit renders this page, so a page that brings its own
+    host needs no script of its own. %>
+
+<template x-if="$store.<%= scoped_store %>.current()"
+          data-studio-controller="modal-host"
+          data-modal-host-store-value="<%= scoped_store %>"
+          data-modal-host-scoped-value="true">
   <div class="fixed inset-0 z-[var(--z-modal)] flex items-center justify-center p-4 modal-backdrop-mount"
        :class="$store.<%= scoped_store %>.current()?._closing && 'modal-backdrop-unmount'"
        style="background:rgba(0,0,0,0.6)"

data/app/views/studio/modals/auth/_resend_footer.html.erb

@@ -14,8 +14,8 @@
   ERROR INK, not a static red. The error paragraph is text-danger-ink, the
   per-theme red Studio::ThemeResolver derives to a 4.5:1 target. It replaced
   text-red-400. Measured through the resolver on turf-monster's real palette
-  (primary 4BAF50), on the modal card, which is bg-surface: danger-ink is 4.50
-  on the dark card 3C3853 and 5.76 on the light card ffffff, clearing AA on
+  (primary 4BAF50), on the modal card, which is bg-surface: danger-ink is 4.89
+  on the dark card 3C3853 and 6.49 on the light card ffffff, clearing AA on
   both; text-red-400 was 3.86 and 2.89, failing both. Those are Tailwind v4's
   red-400, about FF6467, which is what these apps compile; the v3 hex F87171
   gives 4.03 and 2.77 and fails the same way. No STATIC red clears AA

data/app/views/studio/modals/blocks/_processing_card.html.erb

@@ -1,7 +1,7 @@
 <%#
   Reusable processing / loading card. Spinner + title + optional message.
 
-  Minimum-visible-duration convention (studio/modals/_load_convention):
+  Minimum-visible-duration convention (studio/modal_host, window.StudioModals):
   a load spinner must show for AT LEAST a floor, but longer if the real async
   runs longer — resolveAt = max(min_duration, actual_completion) — so it never
   flashes past the user ("did anything happen?") yet never cuts a slow op short.

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

@@ -212,9 +212,8 @@
         var SWAP_IN_MS    = 220;
 
         // THE LIVE REGISTRY IS window.ModalAnimations, NOT THIS TABLE. This is a
-        // fallback only, for the case where the guide renders without the shared
-        // host (studio/modals/_host) that publishes the registry — both consumer
-        // layouts mount it, so in practice the lookup below always finds it.
+        // fallback only, for the case where studio/modal_host, which publishes
+        // the registry on every page, failed to load.
         //
         // It used to be a hard-coded local copy, and that made the Enter/Leave
         // simulator below a LIAR: the simulator builds its controls from the live
@@ -362,11 +361,10 @@
   </script>
 
   <%# The minimum-visible-duration convention (window.StudioModals.holdAtLeast +
-      MIN_LOAD_MS) — the SAME single definition the shared modal host renders, so
-      the demo load modals here (payment/entry processing, on-chain tx, saving)
-      honor resolveAt = max(min_duration, actual) and auto-resolve after
-      min_duration in demo mode. A consumer app already has it via the host. %>
-  <%= render "studio/modals/load_convention" %>
+      MIN_LOAD_MS) is studio/modal_host's, published on every page, so the demo
+      load modals here (payment/entry processing, on-chain tx, saving) honor
+      resolveAt = max(min_duration, actual) and auto-resolve after min_duration
+      in demo mode. %>
 
   <%# Cropper.js + the cropPhotoModal factory — makes the Profile crop / upload
       modals openable on this page (loads cropper.js via <script defer> and
@@ -1642,7 +1640,7 @@
         </div>
       </div>
 
-      <%# The anti-flicker floor from studio/modals/_load_convention. %>
+      <%# The anti-flicker floor from studio/modal_host (window.StudioModals.holdAtLeast). %>
       <div class="card p-5 space-y-3">
         <h4 class="text-heading font-semibold text-sm">Hold at least</h4>
         <p class="text-secondary text-xs">
@@ -1806,13 +1804,12 @@
         });
       }
 
-      // WHEN TO BUILD. window.ModalAnimations is published by the shared host's
-      // inline script, which a host layout may render AFTER this one — so the
-      // build waits for the rest of the body either way:
-      //   full load   — DOMContentLoaded, the host script has run by then;
+      // WHEN TO BUILD. window.ModalAnimations is published by studio/modal_host,
+      // a module, which runs after the document has parsed and before
+      // DOMContentLoaded, so the build waits for the rest of the load either way:
+      //   full load   — DOMContentLoaded, the module has run by then;
       //   Turbo visit — DOMContentLoaded already fired and never fires again, so
-      //                 fall through to a macrotask, which runs after the body
-      //                 swap finishes inserting its scripts.
+      //                 fall through to a macrotask; the registry is already up.
       // turbo:load covers the remaining visits; the build is idempotent, so the
       // overlap between these paths is redundant work and nothing worse.
       if (document.readyState === 'loading') {

data/db/migrate/20261008120000_add_recording_to_studio_knowledge_docs.rb

@@ -0,0 +1,19 @@
+# A meeting's recording, stored beside its transcript. The document row stays
+# the transcript (s3_key); these four columns point at ONE recording object in
+# the same private bucket, written by Studio::KnowledgeDoc#attach_recording!.
+#
+# recording_source_url is the external page the recording came from (the
+# notetaker's share page), kept as a link. It is never fetched.
+#
+# Installed per consumer; do not hand-copy. An app that has not installed this
+# yet keeps working: Studio::KnowledgeDoc#recording? answers false without the
+# columns.
+class AddRecordingToStudioKnowledgeDocs < ActiveRecord::Migration[7.2]
+  def change
+    add_column :studio_knowledge_docs, :recording_key, :string
+    add_column :studio_knowledge_docs, :recording_mime_type, :string
+    add_column :studio_knowledge_docs, :recording_byte_size, :bigint
+    add_column :studio_knowledge_docs, :recording_source_url, :text
+    add_index :studio_knowledge_docs, :recording_key, unique: true
+  end
+end

data/lib/studio/component_gallery.rb

@@ -16,6 +16,8 @@ module Studio
   #    engine never requires it; a host adds `gem "lookbook"` after
   #    studio-engine). Such an app draws it in development and test, and in
   #    production only if it also sets Studio.lookbook_in_production = true.
+  #    A host that lists lookbook BEFORE studio-engine draws nothing and is
+  #    told so at boot (LOAD_ORDER_WARNING).
   #    Everywhere else there is no route, no ViewComponent preview route, no
   #    /lookbook-assets middleware, and no Lookbook in memory.
   # 2. WHO SEES IT. An admin with a live session. Anyone else gets 404, not a
@@ -40,6 +42,11 @@ module Studio
     # preview's Ruby and template) and :params (live inputs from the URL).
     MAIN_PANELS = %i[preview output].freeze
     DRAWER_PANELS = %i[notes].freeze
+    # Printed at boot by a host whose bundle loads lookbook before the engine.
+    LOAD_ORDER_WARNING =
+      "studio-engine: lookbook was required before studio-engine, so the component gallery " \
+      "(#{MOUNT_PATH}) is NOT mounted. Move `gem \"lookbook\"` below `gem \"studio-engine\"` " \
+      "in the Gemfile and restart."
 
     module_function
 
@@ -48,10 +55,13 @@ module Studio
     # lib/studio/engine.rb).
     mattr_accessor :lookbook_loaded_before_engine, default: false
 
-    # Whether this app draws the gallery. Pure: the env, the flag and whether
-    # lookbook is loaded are passed in, so the rule unit-tests without Rails.
-    def mounted?(env:, in_production:, lookbook_loaded:)
+    # Whether this app draws the gallery. Pure: the env, the flag, whether
+    # lookbook is loaded and whether it loaded in order are passed in, so the
+    # rule unit-tests without Rails. Out of order it is not drawn: Lookbook
+    # turned previews on before ViewComponent decided its preview routes.
+    def mounted?(env:, in_production:, lookbook_loaded:, load_order_ok: true)
       return false unless lookbook_loaded
+      return false unless load_order_ok
 
       !env.to_s.casecmp?("production") || in_production == true
     end

data/lib/studio/email_image_generator.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Studio
+  # The "Email image generator" link at the top of /admin/emails: where an
+  # operator goes to make a new banner with the app's own artwork. Each app
+  # points it at its own generator, from config/initializers/studio.rb:
+  #
+  #   config.email_manager_generator_url = "https://example.com/email-art"
+  #   # or, worked out per request:
+  #   config.email_manager_generator_url = ->(request) { "#{request.base_url}/admin/email-art" }
+  #
+  #   config.email_manager_generator_label       = "Header generator"   # optional
+  #   config.email_manager_generator_description = "Open it, copy ..."  # optional
+  #
+  # Unset, nil or blank means no link, and the page renders exactly as it did
+  # before the setting existed.
+  #
+  # The URL is written into an href, so only an absolute http or https URL with
+  # a host is accepted. A configured String that is anything else (a
+  # `javascript:` URL, a relative path, a bare word) raises at boot, where the
+  # mistake is cheap to see. A callable is judged on what it RETURNS, at render
+  # time, and an unusable answer renders no link rather than breaking the page.
+  #
+  # Pure Ruby, so it loads and unit-tests without Rails.
+  module EmailImageGenerator
+    DEFAULT_LABEL = "Email image generator"
+
+    # Generic on purpose: every consuming app shows it unless it says otherwise.
+    DEFAULT_DESCRIPTION = "Make a new header with %<app>s's character model: " \
+                          "open the generator, copy the prompt, paste it into Claude Code."
+
+    SCHEMES = %w[http https].freeze
+
+    # Whitespace, a control character, a quote, an angle bracket or a backslash
+    # anywhere. URI's parser tolerates several of these, a browser strips tab and
+    # newline from an href and reads "\\" as "/", and the view escapes the rest
+    # anyway; a URL that carries one is refused rather than reasoned about.
+    UNSAFE_CHARACTER = /[\x00-\x20\x7f"'<>\\`]/
+
+    # The link to render: url, label and description, all plain strings (the
+    # view escapes them).
+    Link = Struct.new(:url, :label, :description, keyword_init: true)
+
+    module_function
+
+    # An absolute http(s) URL with a host.
+    def web_url?(value)
+      return false unless value.is_a?(String)
+
+      string = value.strip
+      return false if string.empty? || string.match?(UNSAFE_CHARACTER)
+
+      uri = URI.parse(string)
+      SCHEMES.include?(uri.scheme.to_s.downcase) && !uri.host.to_s.empty?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # The setter's check. nil, a blank String and a callable pass; any other
+    # value must be a web URL.
+    def validate_url!(value)
+      return if value.nil? || value.respond_to?(:call)
+      return if value.is_a?(String) && value.strip.empty?
+      return if web_url?(value)
+
+      raise ArgumentError,
+            "Studio.email_manager_generator_url must be an http(s) URL, a callable returning one, " \
+            "or nil (got #{value.inspect})."
+    end
+
+    # What the setter stores: nil for blank, a stripped String, or the callable.
+    def normalize_url(value)
+      validate_url!(value)
+      return value if value.respond_to?(:call)
+
+      string = value.to_s.strip
+      string.empty? ? nil : string
+    end
+
+    # The URL for this request, or nil when there is no usable one. A callable
+    # receives the request (or nothing, if it takes no argument).
+    def resolve_url(configured, request = nil)
+      value =
+        if configured.respond_to?(:call)
+          call_configured(configured, request)
+        else
+          configured
+        end
+      web_url?(value) ? value.strip : nil
+    end
+
+    # A callable that raises draws no link rather than a 500 on /admin/emails;
+    # the exception goes to ErrorLog when the host has one (this file is pure Ruby).
+    def call_configured(callable, request)
+      arity = callable.respond_to?(:arity) ? callable.arity : 1
+      arity.zero? ? callable.call : callable.call(request)
+    rescue StandardError => e
+      begin
+        ::ErrorLog.capture!(e) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+      rescue StandardError
+        nil
+      end
+      nil
+    end
+
+    # The Link to render, or nil when no link is configured.
+    def link(url:, label: nil, description: nil, app_name: nil, request: nil)
+      resolved = resolve_url(url, request)
+      return nil if resolved.nil?
+
+      Link.new(
+        url: resolved,
+        label: present(label) || DEFAULT_LABEL,
+        description: present(description) || format(DEFAULT_DESCRIPTION, app: present(app_name) || "this app")
+      )
+    end
+
+    def present(value)
+      string = value.to_s.strip
+      string.empty? ? nil : string
+    end
+  end
+end

data/lib/studio/engine.rb

@@ -8,7 +8,7 @@ require_relative "component_gallery"
 # view_component is required first: its after_initialize, which decides whether
 # to draw its own preview routes, must run before Lookbook's, which turns
 # previews on for its own use. Studio::ComponentGallery.load_order_ok? records
-# the order this file saw.
+# the order this file saw; out of order, the gallery is not mounted.
 Studio::ComponentGallery.lookbook_loaded_before_engine = defined?(::Lookbook::Engine) ? true : false
 require "view_component"
 
@@ -148,10 +148,7 @@ module Studio
     initializer "studio.component_gallery", after: "lookbook.assets.serve" do
       next unless Studio::ComponentGallery.lookbook_loaded?
 
-      unless Studio::ComponentGallery.load_order_ok?
-        warn "studio-engine: lookbook was required before studio-engine; list it after " \
-             "studio-engine in the Gemfile so ViewComponent decides its preview routes first"
-      end
+      warn Studio::ComponentGallery::LOAD_ORDER_WARNING unless Studio::ComponentGallery.load_order_ok?
       Studio::ComponentGallery.configure_lookbook!(::Lookbook.config)
       config.app_middleware.delete(::Rack::Static)
     end