studio-engine 0.91.2 → 0.92.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 270fe9f569b46f626593afa13ce7cf925f23e783541f76e06d6a465d06837278
-  data.tar.gz: 40f8eefcec2e4eee79baa652da57aca97a6b49b794fab4fb3ca166dd3f27333d
+  metadata.gz: 33eb1f55bd158e9d6c588739db65fbef1a5ba8b707b1e0c0469b539d3e6643fa
+  data.tar.gz: f3c5845a77976e33edc87e04da3de0e08fd890203f901352a3b419ee3f58f489
 SHA512:
-  metadata.gz: ae76749cc7fd004b7a93b2108d0af84e21645b1801f50be212d0d5346d503f8d3355fea7c3350ab74a059edbcfc4d60163b245ae34c7f4c68a249e1115b5588f
-  data.tar.gz: 683b4be2cb7b68b01c167db0e3973aefe9b0dd133b8ddb200f5d76f387d19dc1bff6378204fc0e34c4716e1b08bd9e0d08b4f572e40d3b2c15d007e97a6ba48e
+  metadata.gz: ec17e35ab084a92080f6bc9fa9565cd5ca6a2f71c8f9f75311ef32f1955c140d9391ed34fa78adcffa8fb84892e043074cf5d7cd89b9f09418edf4af72007b9c
+  data.tar.gz: 411eed22d765f4fa318805debbd117353b38f6d518d69b411673bca76d73375812d9f0baa36f69fa1ab25f55976302fe8d37f9ffe5231a4fbd9bfc4002e1b5e8

data/CHANGELOG.md

@@ -4,6 +4,67 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.92.1 — 2026-10-07
+
+### Added
+
+- **The engine owns `error_logs`, `theme_settings` and `image_caches`.** Three
+  migrations (`ensure_error_logs_table`, `ensure_theme_settings_table`,
+  `ensure_image_caches_table`) create each table when it is absent and, on an app
+  that already has it, add only the engine columns it lacks, as nullable columns;
+  nothing is altered or dropped and no index is added. Adopt with
+  `bin/rails studio_engine:install:migrations` and `bin/rails db:migrate`; the
+  release's lock bump does both. Hosts no longer copy these tables from
+  `docs/NEW_APP_SETUP.md`.
+- **A boot check names a missing engine column** (`Studio::HostSchema`). It
+  raises `Studio::HostSchemaError` in development and test, and logs (and reports
+  to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
+  overrides. Extra host columns are never reported, and rake tasks skip it.
+
+### Fixed
+
+- **A theme save no longer raises on apps without `theme_settings.slug`**
+  (Cyvasse, McRitchie Industries and Moms App): `ensure_theme_settings_table`
+  adds the column `ThemeSetting` writes on every save.
+
+## 0.92.0 — 2026-10-06
+
+### Added
+
+- **ViewComponent comes with the engine.** It is a runtime dependency, so an
+  app renders the engine's components with no Gemfile line of its own. Lookbook
+  is not: an app that wants the component gallery adds
+  `gem "lookbook", group: [:development, :test]` after studio-engine (ungrouped,
+  with `Studio.lookbook_in_production`, for a live gallery). Without it the app
+  loads no Lookbook code, which keeps tens of megabytes out of every production
+  process. The front-end standard (`docs/FRONT_END_STANDARD.md`) now names a
+  primitive's public surface (its inputs, its `data-*` hooks and its named CSS
+  classes) and what a change to it takes: a Breaking line here and a
+  consumer-CI run against every consumer before publish.
+- **`Studio::BadgeComponent`, the first component.** It takes `text:`,
+  `data_board_count:`, and either `tone:` (one of the five status roles,
+  `success`, `warning`, `danger`, `primary`, `muted`, with the same chip classes
+  as the hub's `status_tone`) or `scheme:` (the palette the badge partial took).
+  The `components/badge` partial now renders the component and its output is
+  unchanged, so no caller changes this release. `engine.css` adds the engine's
+  `app/components` to every host's Tailwind scan.
+- **The component gallery at `/admin/style/components`.** Lookbook over the
+  engine's previews, with a Components section on `/admin/style` linking each
+  state. A signed-in admin gets it; a visitor or non-admin gets 404. It shows
+  the rendered output only (no Source or Params panel). It is drawn only where
+  the app's bundle loads lookbook: in development and test, and in production
+  only with `Studio.lookbook_in_production = true`. No app draws ViewComponent's
+  preview routes in production. ViewComponent's own preview pages move to
+  `/admin/style/previews`, behind the same wall.
+- **The engine's own importmap pins.** The engine's `config/importmap.rb` pins
+  each module under `app/javascript/studio` as `studio/<name>` (not preloaded),
+  and the `studio.importmap` initializer draws it into every host that has
+  importmap-rails, before the host's own map, so a host pin of the same name
+  wins. No host edit. The first module is `studio/local_path`, the browser twin
+  of `Studio::LocalPath.local?`.
+- **Consumer CI runs Cyvasse's suite** against each engine change, beside the
+  hub, Turf Monster and McRitchie Industries.
+
 ## 0.91.2 — 2026-10-06
 
 ### Security

data/Gemfile

@@ -102,3 +102,11 @@ end
 group :development, :test do
   gem "solana-studio", ">= 0.5.3"
 end
+
+# importmap-rails is the dummy host's importmap, so the engine's pin contract
+# (config/importmap.rb, drawn in by the studio.importmap initializer) is tested
+# against the real gem every consumer runs. Not a runtime dependency: the
+# initializer skips a host without importmap-rails (a footer-only consumer).
+group :development, :test do
+  gem "importmap-rails", ">= 2.0"
+end

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

@@ -28,6 +28,14 @@
   their local copies for this import.
 */
 
+/* -- Components: in every host's class scan --------------------------------
+   The engine's ViewComponent classes (app/components) carry their colour
+   classes in Ruby, and a host's Tailwind config scans only the engine's
+   app/views. This adds app/components to the scan of every host that imports
+   this file, with no host edit. The path is relative to this file.
+   test/integration/component_tailwind_source_test.rb proves it compiles. */
+@source "../../../components";
+
 /* -- Layer scale ------------------------------------------------------------
    The ONE stacking order every Studio app shares. Read the ORDER, not the
    number: the tier is the contract, the integer is an implementation detail.

data/app/components/previews/studio/badge_component_preview/schemes.html.erb

@@ -0,0 +1,5 @@
+<div class="flex flex-wrap gap-2">
+  <% schemes.each do |scheme| %>
+    <%= render Studio::BadgeComponent.new(text: scheme, scheme: scheme) %>
+  <% end %>
+</div>

data/app/components/previews/studio/badge_component_preview/tones.html.erb

@@ -0,0 +1,5 @@
+<div class="flex flex-wrap gap-2">
+  <% tones.each do |tone| %>
+    <%= render Studio::BadgeComponent.new(text: tone.to_s, tone: tone) %>
+  <% end %>
+</div>

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Studio
+  # Every state Studio::BadgeComponent can show: the five status tones, every
+  # legacy scheme including the stage ladder, the neutral default, and the board
+  # count hook. No @param tags: the gallery takes no input.
+  class BadgeComponentPreview < ViewComponent::Preview
+    # The five status roles, as a hub view passes them from status_tone_role.
+    def tones
+      render_with_template(locals: { tones: Studio::BadgeComponent::TONES.keys })
+    end
+
+    # The palette the components/badge partial takes, stage ladder included.
+    def schemes
+      render_with_template(locals: { schemes: Studio::BadgeComponent::SCHEMES.keys })
+    end
+
+    # No tone and no scheme: the neutral scheme.
+    def default
+      render Studio::BadgeComponent.new(text: "neutral")
+    end
+
+    # A board column's count, which studio/board updates through
+    # data-board-count.
+    def board_count
+      render Studio::BadgeComponent.new(text: "12", scheme: "stage-fresh", data_board_count: "fresh")
+    end
+  end
+end

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

@@ -0,0 +1 @@
+<%= content_tag :span, text, class: "badge #{colour_classes}", data: (data_board_count ? { board_count: data_board_count } : nil) %>

data/app/components/studio/badge_component.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Studio
+  # A short label in a pill: a count, a repo name, a stage, a status.
+  #
+  #   render Studio::BadgeComponent.new(text: "3")
+  #   render Studio::BadgeComponent.new(text: "passed", tone: :success)
+  #   render Studio::BadgeComponent.new(text: "news", scheme: "stage-fresh")
+  #
+  # 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   text:, tone: or scheme:, data_board_count:
+  #   classes  .badge plus the tone's or scheme's colour classes
+  #   data-*   data-board-count, the studio/board count target (its updateCounts
+  #            sets the badge's text)
+  #
+  # tone: is one of the five status roles every app shares (TONES). Its classes
+  # are the hub's status_tone chip, minus the `border` width .badge already sets,
+  # so a hub view passes `tone: status_tone_role(status)` and gets the colour the
+  # rest of the page uses for that status. Tokens only, so it reads in both themes.
+  #
+  # scheme: is the palette the components/badge partial took (SCHEMES), including
+  # the stage-* pipeline ladder, and renders exactly what that partial rendered.
+  # An unknown scheme renders FALLBACK, as the partial did.
+  #
+  # Pass tone: or scheme:, not both. Neither renders the neutral scheme.
+  #
+  # 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 BadgeComponent < ViewComponent::Base
+    strip_trailing_whitespace
+
+    TONES = {
+      success: "bg-success/10 text-success-ink border-success/40",
+      warning: "bg-warning/10 text-warning-ink border-warning/40",
+      danger: "bg-danger/10 text-danger-ink border-danger/40",
+      primary: "bg-primary/10 text-heading border-primary/40",
+      muted: "bg-surface-alt text-muted border-subtle"
+    }.freeze
+
+    SCHEMES = {
+      "success" => "bg-mint/10 text-mint border-mint/30",
+      "danger" => "bg-red-600/10 text-red-400 border-red-600/30",
+      "warning" => "bg-yellow-500/10 text-yellow-400 border-yellow-500/30",
+      "info" => "bg-blue-500/10 text-blue-500 border-blue-500/30",
+      "violet" => "bg-violet/10 text-violet border-violet/30",
+      "primary" => "bg-primary/10 text-primary border-primary/30",
+      "orange" => "bg-orange-500/10 text-orange-500 border-orange-500/30",
+      "emerald" => "bg-emerald-500/10 text-emerald-500 border-emerald-500/30",
+      "gray" => "bg-gray-500/10 text-gray-400 border-gray-500/30",
+      # The pipeline ladder News and Content share, first stage to archived.
+      "stage-fresh" => "bg-blue-500/10 text-blue-500 border-blue-500/30",
+      "stage-shaping" => "bg-yellow-500/10 text-yellow-400 border-yellow-500/30",
+      "stage-structured" => "bg-mint/10 text-mint border-mint/30",
+      "stage-refined" => "bg-emerald-500/10 text-emerald-500 border-emerald-500/30",
+      "stage-cohered" => "bg-violet/10 text-violet border-violet/30",
+      "stage-shipped" => "bg-emerald-500/10 text-emerald-500 border-emerald-500/30",
+      "stage-closed" => "bg-gray-500/10 text-gray-400 border-gray-500/30",
+      "neutral" => "bg-surface-alt text-secondary border-subtle"
+    }.freeze
+
+    FALLBACK = "bg-surface-alt text-body border-subtle"
+
+    attr_reader :text, :data_board_count
+
+    def initialize(text:, tone: nil, scheme: nil, data_board_count: nil)
+      super()
+      raise ArgumentError, "Studio::BadgeComponent takes tone: or scheme:, not both" if tone && scheme
+      if tone && !TONES.key?(tone.to_s.to_sym)
+        raise ArgumentError, "unknown tone #{tone.inspect}; expected one of #{TONES.keys.join(', ')}"
+      end
+
+      @text = text
+      @tone = tone&.to_s&.to_sym
+      @scheme = scheme
+      @data_board_count = data_board_count
+    end
+
+    def colour_classes
+      return TONES.fetch(@tone) if @tone
+
+      SCHEMES.fetch((@scheme || "neutral").to_s, FALLBACK)
+    end
+  end
+end

data/app/controllers/studio/component_previews_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Studio
+  # ViewComponent's preview controller, behind the admin wall. ViewComponent
+  # draws its own preview pages at Studio::ComponentGallery::PREVIEWS_ROUTE
+  # wherever previews are on (development and test), and Lookbook renders every
+  # preview in the gallery through this same controller. Anyone but a signed-in
+  # admin gets 404, so neither path shows a component to a visitor even if a
+  # route is drawn that the gallery's router constraint does not cover.
+  #
+  # It inherits ViewComponent's controller (Rails::ApplicationController), not
+  # the host's ApplicationController, so the host's own before_actions do not
+  # run inside a preview render.
+  class ComponentPreviewsController < ::ViewComponentsController
+    prepend_before_action :require_gallery_admin
+
+    private
+
+    def require_gallery_admin
+      head :not_found unless Studio::ComponentGallery.admin_request?(request)
+    end
+  end
+end

data/app/javascript/studio/local_path.js

@@ -0,0 +1,19 @@
+// The one rule for "is this a path on THIS site?", in the browser. It is the
+// twin of Studio::LocalPath.local? (lib/studio/local_path.rb), and
+// test/lib/studio/local_path_js_parity_test.rb holds the two to the same rows.
+//
+// A local path begins with exactly one "/" and carries no control character and
+// no backslash. Each clause closes a way a browser leaves the site: no leading
+// "/" is a scheme or a relative path, "//x" is another host, a backslash is read
+// as "/", and the URL parser strips tab and newline, so a control character can
+// hide a second "/".
+//
+// Pinned for every host as "studio/local_path" (config/importmap.rb).
+
+// A control character (C0 or DEL) or a backslash anywhere in the path.
+const UNSAFE_CHARACTER = /[\u0000-\u001f\u007f\\]/
+
+export function isLocalPath(path) {
+  const string = path == null ? "" : String(path)
+  return string.startsWith("/") && !string.startsWith("//") && !UNSAFE_CHARACTER.test(string)
+}

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

@@ -1,37 +1,6 @@
-<%# locals: (text:, scheme: "neutral", data_board_count: nil) %>
-<%#
-  Stage roles (stage-fresh ... stage-closed) form a shared pipeline palette
-  used by News and Content (and any future pipelines). Mapping:
-    stage-fresh      → first stage (blue)
-    stage-shaping    → 2nd stage    (yellow)
-    stage-structured → 3rd stage    (mint)
-    stage-refined    → 4th stage    (emerald)
-    stage-cohered    → 5th stage    (violet)
-    stage-shipped    → published    (emerald)
-    stage-closed     → archived/done (gray)
-%>
-<%
-  scheme_classes = case scheme.to_s
-    when "success"          then "bg-mint/10 text-mint border-mint/30"
-    when "danger"           then "bg-red-600/10 text-red-400 border-red-600/30"
-    when "warning"          then "bg-yellow-500/10 text-yellow-400 border-yellow-500/30"
-    when "info"             then "bg-blue-500/10 text-blue-500 border-blue-500/30"
-    when "violet"           then "bg-violet/10 text-violet border-violet/30"
-    when "primary"          then "bg-primary/10 text-primary border-primary/30"
-    when "orange"           then "bg-orange-500/10 text-orange-500 border-orange-500/30"
-    when "emerald"          then "bg-emerald-500/10 text-emerald-500 border-emerald-500/30"
-    when "gray"             then "bg-gray-500/10 text-gray-400 border-gray-500/30"
-    when "stage-fresh"      then "bg-blue-500/10 text-blue-500 border-blue-500/30"
-    when "stage-shaping"    then "bg-yellow-500/10 text-yellow-400 border-yellow-500/30"
-    when "stage-structured" then "bg-mint/10 text-mint border-mint/30"
-    when "stage-refined"    then "bg-emerald-500/10 text-emerald-500 border-emerald-500/30"
-    when "stage-cohered"    then "bg-violet/10 text-violet border-violet/30"
-    when "stage-shipped"    then "bg-emerald-500/10 text-emerald-500 border-emerald-500/30"
-    when "stage-closed"     then "bg-gray-500/10 text-gray-400 border-gray-500/30"
-    when "neutral"          then "bg-surface-alt text-secondary border-subtle"
-    else                         "bg-surface-alt text-body border-subtle"
-    end
-%>
-<%# data_board_count wires the badge as a studio/board count target (updateCounts sets
-    its textContent) — additive + opt-in, so every existing caller renders identically. %>
-<span class="badge <%= scheme_classes %>"<% if local_assigns[:data_board_count] %> data-board-count="<%= data_board_count %>"<% end %>><%= text %></span>
+<%# locals: (text:, scheme: "neutral", data_board_count: nil) -%>
+<%# The badge is Studio::BadgeComponent; this partial keeps every existing
+    `render "components/badge"` call working for one release and renders exactly
+    what it rendered before. New code renders the component, which also takes
+    tone: (the shared status roles). -%>
+<%= render Studio::BadgeComponent.new(text: text, scheme: scheme, data_board_count: data_board_count) %>

data/app/views/layouts/studio/component_preview.html.erb

@@ -0,0 +1,16 @@
+<%# The page a component preview renders in, in the gallery and on
+    ViewComponent's own preview pages: the host's theme tokens and stylesheets,
+    so a preview looks as it does in the app, and nothing else: no navbar, no
+    session, no script. -%>
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= studio_theme_css_tag if respond_to?(:studio_theme_css_tag) %>
+    <%= stylesheet_link_tag "tailwind", "application" %>
+  </head>
+  <body class="bg-page text-body p-6">
+    <%= yield %>
+  </body>
+</html>

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

@@ -0,0 +1,37 @@
+<%# locals: () -%>
+<%# Components: every ViewComponent preview the gallery serves, each state a link
+    to its page in the gallery (Lookbook at Studio::ComponentGallery::MOUNT_PATH).
+    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. -%>
+<section id="components" class="space-y-6" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+  <div class="space-y-1">
+    <h2 class="text-2xl font-bold text-heading">Components</h2>
+    <p class="text-muted text-sm max-w-2xl">
+      The engine's ViewComponent classes, one preview per state, in the component gallery.
+    </p>
+  </div>
+
+  <% if Studio.lookbook_mounted? %>
+    <ul class="grid gap-4 sm:grid-cols-2" data-component-previews>
+      <% Lookbook.previews.each do |preview| %>
+        <li class="card p-5 space-y-3" data-component-preview="<%= preview.lookup_path %>">
+          <p class="font-semibold text-heading"><%= preview.label %></p>
+          <div class="flex flex-wrap gap-2">
+            <% preview.scenarios.each do |scenario| %>
+              <%= link_to scenario.label, scenario.url_path, class: "btn btn-neutral btn-sm" %>
+            <% end %>
+          </div>
+        </li>
+      <% end %>
+    </ul>
+    <%= link_to "Open the component gallery", Studio::ComponentGallery::MOUNT_PATH, class: "btn btn-primary btn-sm" %>
+  <% else %>
+    <p class="empty-state">
+      This app does not serve the component gallery here. It needs lookbook in its bundle
+      (<code class="font-mono text-2xs">gem "lookbook"</code> after studio-engine), and in
+      production <code class="font-mono text-2xs">Studio.lookbook_in_production</code> too.
+    </p>
+  <% end %>
+</section>

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

@@ -3,14 +3,16 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Four ENGINE sections, reached by the sticky section nav below and rendered
+     Five ENGINE sections, reached by the sticky section nav below and rendered
      as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the folded-in /admin/theme editor, and the
      live preview), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
-     copy-paste-for-an-agent snippets), and Tasks (the shared board primitive).
+     copy-paste-for-an-agent snippets), Tasks (the shared board primitive), and
+     Components (the ViewComponent previews, linking into the gallery at
+     /admin/style/components).
 
-     A FIFTH section is the host app's own, and appears only on an app that asks
+     A SIXTH section is the host app's own, and appears only on an app that asks
      for it: define app/views/style/host/_modals.html.erb in the consuming app
      and the guide grows a section (and a nav pill) for that app's own modals,
      between Modals and Tricks. The gem still renders the section chrome; the app
@@ -46,7 +48,8 @@
   sections << ["host-modals", Studio.app_name] if host_modals
   sections += [
     ["tricks", "Tricks"],
-    ["tasks",  "Tasks"]
+    ["tasks",  "Tasks"],
+    ["components", "Components"]
   ]
 %>
 <div class="max-w-6xl mx-auto px-4 pb-16">
@@ -87,6 +90,7 @@
     <% end %>
     <%= render "style/tricks" %>
     <%= render "style/tasks" %>
+    <%= render "style/components" %>
   </div>
 </div>
 

data/config/importmap.rb

@@ -0,0 +1,13 @@
+# The engine's importmap pins, drawn into every host by the studio.importmap
+# initializer (lib/studio/engine.rb) before the host's own config/importmap.rb.
+#
+# One `pin` per module under app/javascript/studio, named "studio/<name>", and
+# none preloaded: a page fetches a module only when something imports it.
+#
+# `pin`, not `pin_all_from`, so a host can override one: importmap-rails expands
+# a pin_all_from directory AFTER every plain pin, so a directory pin would beat
+# the host's own `pin` of the same name. Plain pins are last-drawn-wins, and the
+# host's map is drawn last.
+Studio::Engine.javascript_module_logical_paths.each do |logical_path|
+  pin logical_path.delete_suffix(".js"), to: logical_path, preload: false
+end

data/db/migrate/20261006120001_ensure_error_logs_table.rb

@@ -0,0 +1,66 @@
+# The engine owns the shape of `error_logs`: ErrorLog and the /error_logs pages
+# write and read the columns below on every host.
+#
+# A host that predates this migration already has the table, built by its own
+# migration from docs/NEW_APP_SETUP.md, and the hosts disagree on details (turf
+# has NOT NULL on message, an index on created_at and no unique index on slug).
+# So the migration is a baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with its indexes;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added, because a host's indexes and NOT NULLs
+#     are its own, and a unique index built during a release-phase migrate can
+#     fail on existing rows or lock a large table.
+#
+# On every consumer that existed when this shipped, the second branch adds
+# nothing. Studio::HostSchema checks the same columns at boot.
+class EnsureErrorLogsTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:error_logs)
+      create_table :error_logs do |t|
+        t.string :slug
+        t.text :message
+        t.text :inspect
+        t.text :backtrace
+        t.string :target_type
+        t.bigint :target_id
+        t.string :target_name
+        t.string :parent_type
+        t.bigint :parent_id
+        t.string :parent_name
+
+        t.timestamps
+      end
+
+      add_index :error_logs, :slug, unique: true
+      add_index :error_logs, %i[target_type target_id]
+      add_index :error_logs, %i[parent_type parent_id]
+      return
+    end
+
+    add_column :error_logs, :slug,        :string,   if_not_exists: true
+    add_column :error_logs, :message,     :text,     if_not_exists: true
+    add_column :error_logs, :inspect,     :text,     if_not_exists: true
+    add_column :error_logs, :backtrace,   :text,     if_not_exists: true
+    add_column :error_logs, :target_type, :string,   if_not_exists: true
+    add_column :error_logs, :target_id,   :bigint,   if_not_exists: true
+    add_column :error_logs, :target_name, :string,   if_not_exists: true
+    add_column :error_logs, :parent_type, :string,   if_not_exists: true
+    add_column :error_logs, :parent_id,   :bigint,   if_not_exists: true
+    add_column :error_logs, :parent_name, :string,   if_not_exists: true
+    add_column :error_logs, :created_at,  :datetime, if_not_exists: true
+    add_column :error_logs, :updated_at,  :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own, and
+  # dropping it would destroy the host's error history. It refuses instead.
+  def down
+    return unless table_exists?(:error_logs)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureErrorLogsTable cannot tell whether it created error_logs or found the host's own; " \
+          "drop the table by hand if this app truly owns none of its rows."
+  end
+end

data/db/migrate/20261006120002_ensure_theme_settings_table.rb

@@ -0,0 +1,63 @@
+# The engine owns the shape of `theme_settings`: ThemeSetting and /admin/theme
+# write the columns below on every host.
+#
+# `slug` is the column this migration exists for. ThemeSetting includes
+# Sluggable, whose before_save writes `slug` on every save, and the setup doc's
+# hand-copied migration omitted it, so a theme save raises on any host built
+# from that doc (cyvasse, mcritchie-industries and moms-app when this shipped).
+# The slug is "theme-<app_name>", derived on save; existing rows keep a NULL
+# slug until their next save, and nothing looks a theme up by slug.
+#
+# A baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with its unique app_name index;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added.
+#
+# Studio::HostSchema checks the same columns at boot.
+class EnsureThemeSettingsTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:theme_settings)
+      create_table :theme_settings do |t|
+        t.string :app_name, null: false
+        t.string :slug
+        t.string :primary
+        t.string :dark
+        t.string :light
+        t.string :accent1
+        t.string :accent2
+        t.string :warning
+        t.string :danger
+
+        t.timestamps
+      end
+
+      add_index :theme_settings, :app_name, unique: true
+      return
+    end
+
+    add_column :theme_settings, :app_name,   :string,   if_not_exists: true
+    add_column :theme_settings, :slug,       :string,   if_not_exists: true
+    add_column :theme_settings, :primary,    :string,   if_not_exists: true
+    add_column :theme_settings, :dark,       :string,   if_not_exists: true
+    add_column :theme_settings, :light,      :string,   if_not_exists: true
+    add_column :theme_settings, :accent1,    :string,   if_not_exists: true
+    add_column :theme_settings, :accent2,    :string,   if_not_exists: true
+    add_column :theme_settings, :warning,    :string,   if_not_exists: true
+    add_column :theme_settings, :danger,     :string,   if_not_exists: true
+    add_column :theme_settings, :created_at, :datetime, if_not_exists: true
+    add_column :theme_settings, :updated_at, :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own theme. It
+  # refuses instead.
+  def down
+    return unless table_exists?(:theme_settings)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureThemeSettingsTable cannot tell whether it created theme_settings or found the host's own; " \
+          "drop the table or the slug column by hand if this app truly owns neither."
+  end
+end

data/db/migrate/20261006120003_ensure_image_caches_table.rb

@@ -0,0 +1,63 @@
+# The engine owns the shape of `image_caches`: ImageCache, Studio::ImageCache
+# and Studio::EmailCatalog write the columns below on every host.
+#
+# Hosts that cache images already have the table (from their own migration);
+# hosts that never did (cyvasse and moms-app when this shipped) get it here, so
+# the email banner and logo uploads work on every app.
+#
+# A baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with the owner nullable (an
+#     app-global image has no owner) and the indexes that back ImageCache's
+#     uniqueness validations;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added.
+#
+# Studio::HostSchema checks the same columns at boot.
+class EnsureImageCachesTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:image_caches)
+      create_table :image_caches do |t|
+        t.string :owner_type
+        t.bigint :owner_id
+        t.string :purpose, null: false
+        t.string :variant, null: false
+        t.string :s3_key, null: false
+        t.string :source_url
+        t.string :content_type
+        t.integer :bytes
+
+        t.timestamps
+      end
+
+      add_index :image_caches, %i[owner_type owner_id], name: "index_image_caches_on_owner"
+      add_index :image_caches, :s3_key, unique: true
+      add_index :image_caches, %i[owner_type owner_id purpose variant], unique: true,
+                name: "idx_image_caches_owner_purpose_variant"
+      return
+    end
+
+    add_column :image_caches, :owner_type,   :string,   if_not_exists: true
+    add_column :image_caches, :owner_id,     :bigint,   if_not_exists: true
+    add_column :image_caches, :purpose,      :string,   if_not_exists: true
+    add_column :image_caches, :variant,      :string,   if_not_exists: true
+    add_column :image_caches, :s3_key,       :string,   if_not_exists: true
+    add_column :image_caches, :source_url,   :string,   if_not_exists: true
+    add_column :image_caches, :content_type, :string,   if_not_exists: true
+    add_column :image_caches, :bytes,        :integer,  if_not_exists: true
+    add_column :image_caches, :created_at,   :datetime, if_not_exists: true
+    add_column :image_caches, :updated_at,   :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own cache. It
+  # refuses instead.
+  def down
+    return unless table_exists?(:image_caches)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureImageCachesTable cannot tell whether it created image_caches or found the host's own; " \
+          "drop the table by hand if this app truly owns none of its rows."
+  end
+end

data/lib/studio/component_gallery.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "active_support/security_utils"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/module/attribute_accessors"
+
+module Studio
+  # The component gallery: Lookbook, mounted by Studio.routes at
+  # /admin/style/components, rendering the ViewComponent previews under the
+  # engine's app/components/previews (docs/FRONT_END_STANDARD.md, "Components").
+  #
+  # Three rules hold it, each here so the routes, the engine initializers and
+  # the preview controller read one answer:
+  #
+  # 1. WHERE IT IS DRAWN. Only in an app whose bundle loads lookbook (the
+  #    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.
+  #    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
+  #    redirect, so the gallery's existence is not advertised. The check runs
+  #    in the router (AdminConstraint), because Lookbook's controllers inherit
+  #    ActionController::Base and never run the host's before_actions.
+  # 3. WHAT IT SHOWS. The rendered preview and its HTML. The Source and Params
+  #    panels are switched off, embeds are off, pages are off, and no preview
+  #    declares a @param tag, so the gallery shows no Ruby and accepts no input.
+  module ComponentGallery
+    MOUNT_PATH = "/admin/style/components"
+    # ViewComponent's own preview pages, moved from /rails/view_components to
+    # sit behind the same wall (Studio::ComponentPreviewsController).
+    PREVIEWS_ROUTE = "/admin/style/previews"
+    PREVIEWS_CONTROLLER = "Studio::ComponentPreviewsController"
+    # Lookbook's UI references its scripts and styles at this absolute path.
+    ASSETS_PATH = "/lookbook-assets"
+    # The layout each preview renders in: the host's stylesheets and theme, no
+    # navbar, no script.
+    PREVIEW_LAYOUT = "studio/component_preview"
+    # Only the panels that show output. Lookbook's defaults add :source (the
+    # preview's Ruby and template) and :params (live inputs from the URL).
+    MAIN_PANELS = %i[preview output].freeze
+    DRAWER_PANELS = %i[notes].freeze
+
+    module_function
+
+    # Whether the engine saw Lookbook already loaded when it was required, which
+    # means the host listed lookbook BEFORE studio-engine (set by
+    # 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:)
+      return false unless lookbook_loaded
+
+      !env.to_s.casecmp?("production") || in_production == true
+    end
+
+    # Whether the host's bundle loaded Lookbook. The engine never requires it.
+    def lookbook_loaded?
+      defined?(::Lookbook::Engine) ? true : false
+    end
+
+    # Lookbook required after view_component, so ViewComponent's after_initialize
+    # draws (or does not draw) its preview routes before Lookbook turns previews on.
+    def load_order_ok?
+      !lookbook_loaded_before_engine
+    end
+
+    # Whether this request comes from an admin with a live session. It reads the
+    # same two facts the engine's own gate reads: the user id under
+    # Studio.session_key (Studio::ErrorHandling#current_user), and, for a User
+    # with a session_token column, a cookie token that matches it
+    # (#verify_session_token). It fails closed: no session, no user, a non-admin,
+    # or a stale token all answer false.
+    def admin_request?(request)
+      session = request.session
+      key = Studio.session_key
+      user_id = session[key.to_s] || session[key.to_sym]
+      return false if user_id.blank?
+      return false unless defined?(::User)
+
+      user = ::User.find_by(id: user_id)
+      return false unless user.respond_to?(:admin?) && user.admin?
+      return true unless user.respond_to?(:session_token)
+
+      token = user.session_token.to_s
+      token.present? && ActiveSupport::SecurityUtils.secure_compare(token, session[:session_token].to_s)
+    end
+
+    # The directory Lookbook's own Rack::Static served ASSETS_PATH from.
+    def lookbook_assets_root
+      ::Lookbook::Engine.root.join("public/lookbook-assets").to_s
+    end
+
+    # The routing constraint on the mount. A request it refuses matches no
+    # route, which Rails answers 404.
+    class AdminConstraint
+      def matches?(request)
+        ComponentGallery.admin_request?(request)
+      end
+    end
+
+    # The settings that keep the gallery to output only (rule 3). Applied by
+    # the studio.component_gallery initializer, before the host's own
+    # initializers, so a host can still change one deliberately.
+    def configure_lookbook!(config)
+      config.project_name = "Components"
+      config.preview_inspector.main_panels = MAIN_PANELS
+      config.preview_inspector.drawer_panels = DRAWER_PANELS
+      config.preview_embeds.enabled = false
+      config.page_paths = []
+      config.live_updates = false
+      config.debug_menu = false
+      # Parse previews on the first gallery request, not at boot: an app that
+      # never opens the gallery pays nothing for it.
+      config.lazy_load_previews_and_pages = true
+      config
+    end
+  end
+end

data/lib/studio/engine.rb

@@ -1,4 +1,16 @@
 require_relative "log_rotation"
+require_relative "component_gallery"
+# Components (docs/FRONT_END_STANDARD.md). Required here, not left to the host's
+# Gemfile, because every app takes ViewComponent through this engine.
+#
+# Lookbook, the gallery, is NOT required here: an app that wants it bundles it
+# (see the gemspec), and Bundler.require loads it. Listed AFTER studio-engine, so
+# 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.
+Studio::ComponentGallery.lookbook_loaded_before_engine = defined?(::Lookbook::Engine) ? true : false
+require "view_component"
 
 module Studio
   class Engine < ::Rails::Engine
@@ -71,6 +83,77 @@ module Studio
       # US set ships — every other country's badge renders an emoji flag, which
       # costs no bytes at all.
       app.config.assets.precompile += Studio::Engine.subdivision_flag_logical_paths
+
+      # The engine's ES modules (app/javascript), which config/importmap.rb pins.
+      # On the asset paths so an importmap pin resolves on sprockets and propshaft
+      # alike, and enumerated for sprockets' precompile list like the banners.
+      javascript_root = Studio::Engine.root.join("app/javascript").to_s
+      if app.config.assets.respond_to?(:paths) && app.config.assets.paths.is_a?(Array)
+        app.config.assets.paths << javascript_root unless app.config.assets.paths.map(&:to_s).include?(javascript_root)
+      end
+      app.config.assets.precompile += Studio::Engine.javascript_module_logical_paths
+    end
+
+    # ---- THE ENGINE'S IMPORTMAP PINS ------------------------------------------
+    #
+    # A host draws the engine's pins with no edit of its own: this adds the
+    # engine's config/importmap.rb to importmap-rails' list of maps BEFORE
+    # importmap-rails draws them (its "importmap" initializer appends the host's
+    # config/importmap.rb last). The host's map is drawn after the engine's, so a
+    # host that pins the same name wins. This is the mechanism importmap-rails
+    # documents for engines ("Composing import maps").
+    #
+    # The contract a module joins by being here:
+    #   - it lives under app/javascript/studio/ and is pinned as "studio/<name>";
+    #   - pins are NOT preloaded, so a page fetches only the modules it imports;
+    #   - its logical asset path shares the studio/ prefix with the classic
+    #     scripts in app/assets/javascripts/studio, so a module may not reuse one
+    #     of those names (test/integration/engine_importmap_pins_test.rb).
+    # A host without importmap-rails (a footer-only consumer) skips this.
+    initializer "studio.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << Studio::Engine.root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << Studio::Engine.root.join("app/javascript")
+    end
+
+    # ---- COMPONENTS AND THE GALLERY -------------------------------------------
+    #
+    # ViewComponent reads its preview settings in "view_component.set_configs",
+    # so these land first. The previews live in app/components/previews, which
+    # is its own autoload root (below): Studio::BadgeComponentPreview, not
+    # Previews::Studio::BadgeComponentPreview. ViewComponent's own preview pages
+    # move behind the admin wall (PREVIEWS_ROUTE, PREVIEWS_CONTROLLER), and each
+    # preview renders in a layout carrying the host's stylesheets.
+    paths.add "app/components/previews", autoload: true
+
+    initializer "studio.view_component", before: "view_component.set_configs" do |app|
+      previews = app.config.view_component.previews
+      preview_path = Studio::Engine.root.join("app/components/previews").to_s
+      previews.paths << preview_path unless previews.paths.include?(preview_path)
+      previews.route = Studio::ComponentGallery::PREVIEWS_ROUTE
+      previews.controller = Studio::ComponentGallery::PREVIEWS_CONTROLLER
+      previews.default_layout = Studio::ComponentGallery::PREVIEW_LAYOUT
+    end
+
+    # Lookbook's settings, before Lookbook's after_initialize reads them and
+    # before the host's config/initializers, so a host can still change one.
+    #
+    # It also takes Lookbook's UI assets off the public middleware stack.
+    # Lookbook serves /lookbook-assets through a Rack::Static it adds for every
+    # request; Studio.routes serves the same files from inside the admin
+    # constraint instead, so an app that does not draw the gallery serves none
+    # of Lookbook and a visitor never learns it is there. The delete matches by
+    # class, so a host cannot add a Rack::Static of its own (none does).
+    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
+      Studio::ComponentGallery.configure_lookbook!(::Lookbook.config)
+      config.app_middleware.delete(::Rack::Static)
     end
 
     # Logical asset paths ("emails/magic-link.png") for every default banner the
@@ -82,6 +165,16 @@ module Studio
         .sort
     end
 
+    # Logical asset paths ("studio/local_path.js") for every ES module the
+    # engine pins (config/importmap.rb).
+    def self.javascript_module_logical_paths
+      base = File.expand_path("../../app/javascript", __dir__)
+      Dir[File.join(base, "**/*.js")]
+        .select { |path| File.file?(path) }
+        .map { |path| path.delete_prefix("#{base}/") }
+        .sort
+    end
+
     # Logical asset paths ("state-flags/wa.svg") for every subdivision flag the
     # gem ships.
     # Both the vector art and the small rasters behind it: the badge renders one
@@ -205,6 +298,14 @@ module Studio
          ::User.ancestors.include?(::ActiveRecord::Base)
         Studio.validate_user_contract!(::User)
       end
+
+      # The host's error_logs, theme_settings and image_caches carry every
+      # column the engine's models write (Studio::HostSchema). Skipped in a
+      # rake task, which boots to migrate rather than to serve.
+      if Studio.active_record? && !Studio::HostSchema.inside_rake_task?
+        Studio::HostSchema.check!
+      end
     end
+
   end
 end

data/lib/studio/host_schema.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Studio
+  # The columns the engine's models write on tables the HOST holds: error_logs,
+  # theme_settings and image_caches. The engine's Ensure*Table migrations create
+  # or complete those tables; this checks, at boot, that the host has actually
+  # run them, so a missing column is named at startup instead of surfacing later
+  # as a 500 on the first save that writes it (a theme save on a host without
+  # theme_settings.slug was the case that prompted it).
+  #
+  # The check is one-directional: it looks only for REQUIRED columns that are
+  # absent. Extra columns, extra indexes, a different NOT NULL or a different
+  # type are the host's business and never reported.
+  #
+  # HOW LOUD, per environment (Studio.host_schema_check):
+  #
+  #   :raise  development and test, by default. A developer or a CI suite sees
+  #           Studio::HostSchemaError at boot with the table, the column and the
+  #           two commands that fix it.
+  #   :log    every other environment (production, and QA, which runs as
+  #           production), by default. Rails.logger.error plus a Sentry message
+  #           when the host loads sentry-ruby. It never raises there, for two
+  #           reasons. Heroku's release phase boots the app to run db:migrate,
+  #           the very command that adds the column, so a raise at boot would
+  #           make the fix undeployable. And a missing column breaks the one
+  #           surface that writes it (an admin theme save, an email banner
+  #           upload); taking every page down to report it trades a small
+  #           outage for a total one.
+  #   false   off.
+  #
+  # The check never runs inside a rake task (db:migrate, install:migrations,
+  # assets:precompile): those boot the app precisely to change or ignore the
+  # schema, and a report there would be wrong by the time the task finishes. It
+  # also stays quiet when the database cannot be reached; it has nothing to say
+  # about a schema it cannot read.
+  module HostSchema
+    REQUIRED_COLUMNS = {
+      "error_logs" => %w[
+        slug message inspect backtrace
+        target_type target_id target_name
+        parent_type parent_id parent_name
+        created_at updated_at
+      ].freeze,
+      "theme_settings" => %w[
+        app_name slug primary dark light accent1 accent2 warning danger
+        created_at updated_at
+      ].freeze,
+      "image_caches" => %w[
+        owner_type owner_id purpose variant s3_key source_url content_type bytes
+        created_at updated_at
+      ].freeze
+    }.freeze
+
+    MODES = [:raise, :log, false].freeze
+
+    module_function
+
+    # { "table" => ["missing", "columns"] } for every required table that is
+    # absent (all its columns listed) or short of a column. Empty when the host
+    # satisfies the contract.
+    def missing_columns(connection)
+      REQUIRED_COLUMNS.each_with_object({}) do |(table, required), missing|
+        present = connection.table_exists?(table) ? connection.columns(table).map(&:name) : []
+        absent = required - present
+        missing[table] = absent if absent.any?
+      end
+    end
+
+    def message(missing)
+      lines = missing.map do |table, columns|
+        if columns == REQUIRED_COLUMNS[table]
+          "  #{table}: the table is missing"
+        else
+          "  #{table}: missing #{columns.join(', ')}"
+        end
+      end
+
+      <<~MSG
+        studio-engine: this app's database is missing columns the engine's models write.
+
+        #{lines.join("\n")}
+
+        Install and run the engine's migrations (they create a missing table, add
+        a missing column and change nothing else):
+
+          bin/rails studio_engine:install:migrations
+          bin/rails db:migrate
+
+        Set Studio.host_schema_check = false in config/initializers/studio.rb to
+        silence this check.
+      MSG
+    end
+
+    # The mode in force: the host's Studio.host_schema_check, or :raise in
+    # development and test and :log everywhere else.
+    def mode(setting: Studio.host_schema_check, env: Rails.env)
+      return setting unless setting.nil?
+
+      env.development? || env.test? ? :raise : :log
+    end
+
+    # The boot hook. Returns the missing-columns hash it found (empty when the
+    # host is whole or the check was skipped) and acts on it per `mode`.
+    def check!(connection: nil, mode: self.mode, logger: Rails.logger)
+      return {} if mode == false
+
+      missing =
+        begin
+          if connection
+            missing_columns(connection)
+          else
+            ActiveRecord::Base.connection_pool.with_connection { |conn| missing_columns(conn) }
+          end
+        rescue ActiveRecord::ActiveRecordError => e
+          logger&.debug("[studio-engine] host schema check skipped: #{e.class}: #{e.message}")
+          return {}
+        end
+      return missing if missing.empty?
+
+      text = message(missing)
+      raise Studio::HostSchemaError, text if mode == :raise
+
+      logger&.error("[studio-engine] #{text}")
+      report_to_sentry(text)
+      missing
+    end
+
+    # True while a rake task is running: the app booted to migrate, install or
+    # precompile, not to serve.
+    def inside_rake_task?
+      defined?(::Rake) && ::Rake.respond_to?(:application) &&
+        ::Rake.application.respond_to?(:top_level_tasks) &&
+        ::Rake.application.top_level_tasks.any?
+    end
+
+    def report_to_sentry(text)
+      return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
+
+      ::Sentry.capture_message(text, level: :error)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.91.2"
+  VERSION = "0.92.1"
 end

data/lib/studio.rb

@@ -13,6 +13,7 @@ require "active_support/core_ext/numeric/time"
 require "active_support/core_ext/integer/time"
 require "studio/version"
 require "studio/local_path"
+require "studio/component_gallery"
 require "studio/log_rotation"
 require "studio/ip_locations"
 require "studio/geo"
@@ -41,6 +42,7 @@ require "studio/public_user"
 require "studio/name_parts"
 require "studio/s3"
 require "studio/image_cache"
+require "studio/host_schema"
 require "studio/link_token"
 require "studio/link_resolution"
 require "studio/session_fingerprint"
@@ -690,6 +692,22 @@ module Studio
   #   config.draw_booking_routes = true
   mattr_accessor :draw_booking_routes, default: false
 
+  # Draw the component gallery (Lookbook at /admin/style/components) in
+  # PRODUCTION. An app whose bundle loads lookbook draws it in development and
+  # test; in production only an app that also sets this does. No app sets it
+  # yet; the hub is meant to, with lookbook in its production bundle. Admins
+  # only, 404 to anyone else. See Studio::ComponentGallery.
+  #
+  #   config.lookbook_in_production = true
+  mattr_accessor :lookbook_in_production, default: false
+
+  # Whether this app draws the component gallery: its bundle loaded lookbook,
+  # and this is development or test, or production with the flag.
+  def self.lookbook_mounted?
+    ComponentGallery.mounted?(env: Rails.env, in_production: lookbook_in_production,
+                              lookbook_loaded: ComponentGallery.lookbook_loaded?)
+  end
+
   # WHERE THE APP'S OWN BOOKING PAGE LIVES, for an app that renders
   # `studio_booking_frame` in a view of its own instead of drawing the engine's
   # /schedule: a path ("/schedule"), or a callable receiving the view
@@ -1043,6 +1061,11 @@ module Studio
   # that intentionally break the contract).
   mattr_accessor :validate_user_contract, default: true
 
+  # How loudly the boot check reports a host database missing a column the
+  # engine's models write (Studio::HostSchema): :raise, :log, or false for off.
+  # nil, the default, means :raise in development and test and :log elsewhere.
+  mattr_accessor :host_schema_check, default: nil
+
   # Does the host load ActiveRecord at all? True for every app that requires
   # `rails/all` or `active_record/railtie` (all the engine's database-backed
   # consumers); false for a FOOTER-ONLY consumer, an app with no database that
@@ -1074,6 +1097,7 @@ module Studio
   PASSWORD_USER_INSTANCE_METHODS = %i[authenticate].freeze
 
   class UserContractError < StandardError; end
+  class HostSchemaError < StandardError; end
 
   def self.configure
     yield self
@@ -1531,6 +1555,19 @@ module Studio
       get   "admin/style",            to: "style#index",               as: :admin_style
       get   "admin/design_system",    to: redirect("/admin/style"),    as: :admin_design_system
 
+      # The component gallery: Lookbook over the engine's ViewComponent previews.
+      # The router refuses anyone but a signed-in admin, so a visitor and a
+      # non-admin get 404 (Studio::ComponentGallery::AdminConstraint). Drawn
+      # only where the host's bundle loaded lookbook: in development and test,
+      # and in production only where Studio.lookbook_in_production is set.
+      if Studio.lookbook_mounted?
+        constraints(Studio::ComponentGallery::AdminConstraint.new) do
+          mount Lookbook::Engine, at: Studio::ComponentGallery::MOUNT_PATH, as: :studio_component_gallery
+          mount Rack::Files.new(Studio::ComponentGallery.lookbook_assets_root),
+                at: Studio::ComponentGallery::ASSETS_PATH, as: :studio_component_gallery_assets
+        end
+      end
+
       # The standard transactional-email page. Canonical at /admin/emails
       # (Studio::EmailsController): index lists every registered email with its
       # live banner and whether that banner is inherited or app-owned; update

data/studio-engine.gemspec

@@ -19,9 +19,11 @@ Gem::Specification.new do |spec|
   }
 
   # config/e2e_lane.yml is the BROWSER LANE's contract — a fact about this repo's CI,
-  # read by bin/e2e-executed-set-check and test/lib/e2e_lane_contract_test.rb. It is
-  # the only thing under config/, and it has no meaning in a consuming app, so it is
-  # excluded rather than shipped. (e2e/, bin/ and test/ were never in this list.)
+  # read by bin/e2e-executed-set-check and test/lib/e2e_lane_contract_test.rb. It
+  # has no meaning in a consuming app, so it is excluded rather than shipped.
+  # config/importmap.rb ships: it is the engine's pins, which every host draws
+  # (lib/studio/engine.rb, studio.importmap). (e2e/, bin/ and test/ were never in
+  # this list.)
   #
   # docs/SITE_FOOTER.md and docs/BOOKING.md ship because consumers cite them from
   # their own initializers ("docs/SITE_FOOTER.md is the contract"), and a
@@ -56,4 +58,16 @@ Gem::Specification.new do |spec|
   # because the point of the geo primitive is that EVERY app has the capacity:
   # an app that has to add a gem before it can place a visitor does not.
   spec.add_dependency "geocoder", ">= 1.8", "< 2.0"
+  # Components (docs/FRONT_END_STANDARD.md). Every consumer renders the engine's
+  # ViewComponent classes, so it is a runtime dependency, and an app takes it
+  # through the engine rather than its own Gemfile.
+  spec.add_dependency "view_component", ">= 4.0", "< 5"
+  # The component gallery at /admin/style/components is Lookbook, and Lookbook is
+  # NOT a runtime dependency: eager-loaded in production it costs every process
+  # tens of megabytes, and most consumers run on 512 MB dynos. An app opts in by
+  # bundling it after studio-engine, `gem "lookbook", group: [:development, :test]`
+  # for a development gallery, ungrouped plus Studio.lookbook_in_production for a
+  # live one. The engine never requires it; it mounts the gallery only when the
+  # host's bundle has loaded it. See Studio::ComponentGallery.
+  spec.add_development_dependency "lookbook", ">= 2.3", "< 3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.91.2
+  version: 0.92.1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -180,6 +180,46 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: lookbook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: Studio Engine is a non-isolated Rails engine that ships an opinionated
   authentication + SSO contract, a polymorphic ErrorLog model, a Sluggable concern,
   a 7-role dynamic theme system with CSS-custom-property generation, and an S3-backed
@@ -318,6 +358,11 @@ files:
 - app/assets/stylesheets/studio/sticky_table_header.css
 - app/assets/tailwind/studio_engine/engine-motion.css
 - app/assets/tailwind/studio_engine/engine.css
+- app/components/previews/studio/badge_component_preview.rb
+- app/components/previews/studio/badge_component_preview/schemes.html.erb
+- app/components/previews/studio/badge_component_preview/tones.html.erb
+- app/components/studio/badge_component.html.erb
+- app/components/studio/badge_component.rb
 - app/controllers/concerns/solana/session_auth.rb
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/board/reorderable.rb
@@ -337,6 +382,7 @@ files:
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/admin_surveys_controller.rb
 - app/controllers/studio/bookings_controller.rb
+- app/controllers/studio/component_previews_controller.rb
 - app/controllers/studio/emails_controller.rb
 - app/controllers/studio/geo_settings_controller.rb
 - app/controllers/studio/knowledge_docs_controller.rb
@@ -363,6 +409,7 @@ files:
 - app/helpers/studio_navbar_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
+- app/javascript/studio/local_path.js
 - app/jobs/error_log_cleanup_job.rb
 - app/jobs/studio/email_delivery_job.rb
 - app/mailers/application_mailer.rb
@@ -416,6 +463,7 @@ files:
 - app/views/layouts/studio/_head.html.erb
 - app/views/layouts/studio/_link_preview_tags.html.erb
 - app/views/layouts/studio/_smooth_load.html.erb
+- app/views/layouts/studio/component_preview.html.erb
 - app/views/navbar/show.html.erb
 - app/views/registrations/new.html.erb
 - app/views/schema/index.html.erb
@@ -548,6 +596,7 @@ files:
 - app/views/studio/surveys/show.html.erb
 - app/views/studio/surveys/sign_in_required.html.erb
 - app/views/studio/surveys/thanks.html.erb
+- app/views/style/_components.html.erb
 - app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
@@ -575,6 +624,7 @@ files:
 - app/views/theme_settings/edit.html.erb
 - app/views/user_mailer/magic_link.html.erb
 - app/views/user_mailer/magic_link.text.erb
+- config/importmap.rb
 - db/migrate/20260614000000_create_studio_email_deliveries.rb
 - db/migrate/20260620000001_create_studio_links.rb
 - db/migrate/20260620000002_allow_null_image_cache_owner.rb
@@ -590,6 +640,9 @@ files:
 - db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - db/migrate/20260930120000_create_studio_site_identities.rb
 - db/migrate/20261005120000_create_studio_survey_responses.rb
+- db/migrate/20261006120001_ensure_error_logs_table.rb
+- db/migrate/20261006120002_ensure_theme_settings_table.rb
+- db/migrate/20261006120003_ensure_image_caches_table.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb
@@ -600,6 +653,7 @@ files:
 - lib/studio/booking.rb
 - lib/studio/cable.rb
 - lib/studio/color_scale.rb
+- lib/studio/component_gallery.rb
 - lib/studio/email.rb
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
@@ -607,6 +661,7 @@ files:
 - lib/studio/geo.rb
 - lib/studio/geo/countries.rb
 - lib/studio/geo/lookup.rb
+- lib/studio/host_schema.rb
 - lib/studio/image_cache.rb
 - lib/studio/ip_locations.rb
 - lib/studio/js_identifier.rb