studio-engine 0.91.1 → 0.92.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b177cff9fc53b20d566685aa744f1dc41f481017f3014c9a00ef71a43620365a
-  data.tar.gz: 100753f4d2f9dd2f936c8285a2b3aac844d2538099b066ef15013ca77f407392
+  metadata.gz: 823f5e3df6cb271556188c72d4322a968b5cf63f8635c37b70fc71a56ad93fe3
+  data.tar.gz: ab908a4f8a0c9beae55f1844bbc2957b43c7bc33f1643c3ae083473ae68473d7
 SHA512:
-  metadata.gz: 76433dc917873ff167918968f9ec85d1d6765606e58f3c6502183cab9fca55b3b19a4bc74652f93c74222c3799e4cedbc411a7ce79c6d4d8ff207524982dca20
-  data.tar.gz: 3c69e3e3ed94f63952f9cbf2c2e75446b3d95a7d63c51e5b7331dce801bc5ae5329761b456f6cd968e276d6874daf453dcce551c20b87960c49a604eda81d80e
+  metadata.gz: 0f66ecc8ebf3c1b6318e88e4b069cb2bc4b19452db48035558eea01cb5cf163fcf126435dfdc8b74d5e837bcd65535a10b99157e9cec1fa286f2452739f420ba
+  data.tar.gz: a3ae0c907619c2ba686bdb3a35a82883bd1a15e010191969e52c102414e37b57982a19de4cba20ccf20866638d6814983ad06e6fe0f7027ad8bad925caba6c06

data/CHANGELOG.md

@@ -4,6 +4,60 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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
+
+- **A return path beginning `/\` no longer redirects off-site.** Browsers read
+  `/\evil.com` as `//evil.com`, and the engine's path sanitizers checked only for
+  one leading `/` and not two, so a magic link minted with `return_to=/\evil.com`
+  sent the visitor to another host after sign-in (or, under Rails'
+  `raise_on_open_redirects`, answered 500). One predicate, `Studio::LocalPath.local?`,
+  now holds the rule (one leading `/`, no backslash, no control character) and
+  every engine site uses it: `Studio::LinkToken.sanitize_path`, the link-consume
+  redirect, `Studio::Booking.local_path?`, and the link-preview fallback image.
+  Each site keeps its fallback: a refused return path lands on the default page.
+  Consumers that sanitize a return path themselves should call
+  `Studio::LocalPath.local?` instead of a bare `start_with?("/")` check.
+
 ## 0.91.1 — 2026-10-06
 
 ### Fixed

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/concerns/studio/link_consumption.rb

@@ -163,10 +163,10 @@ module Studio
       user.update!(email_verified_at: Time.current)
     end
 
-    # Only same-origin absolute paths survive; everything else collapses to nil.
+    # Only local paths survive (Studio::LocalPath); everything else collapses to nil.
     def safe_path(path)
       p = path.to_s
-      p.start_with?("/") && !p.start_with?("//") ? p : nil
+      Studio::LocalPath.local?(p) ? p : nil
     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/models/studio/site_identity.rb

@@ -183,7 +183,7 @@ module Studio
       def static_image
         path = Studio.link_preview_fallback_image.to_s
         return nil if path.empty?
-        return path unless path.start_with?("/") && !path.start_with?("//")
+        return path unless Studio::LocalPath.local?(path)
 
         @static_files ||= Concurrent::Map.new
         present = @static_files.compute_if_absent(path) do
@@ -203,7 +203,7 @@ module Studio
       # per path like static_image.
       def static_image_dimensions
         path = static_image
-        return nil if path.nil? || !path.start_with?("/") || path.start_with?("//")
+        return nil unless Studio::LocalPath.local?(path)
 
         @static_dimensions ||= Concurrent::Map.new
         dims = @static_dimensions.compute_if_absent(path) do

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/lib/studio/booking.rb

@@ -11,6 +11,8 @@
 #
 # `gv=true` is what makes Google serve the embeddable page, so the frame and the
 # popup add it; the "open the booking page" link does not.
+require_relative "local_path"
+
 module Studio
   module Booking
     EMBED_PARAM = "gv=true"
@@ -116,10 +118,10 @@ module Studio
     # hrefs (the footer's booking links, `studio_booking_link`). It begins with
     # one "/" and carries no control character. That refuses a scheme
     # ("javascript:", "https:") and a protocol-relative "//host", which a browser
-    # reads as another site.
+    # reads as another site. The rule is Studio::LocalPath's, shared with every
+    # other engine path sanitizer.
     def local_path?(path)
-      string = path.to_s
-      string.start_with?("/") && !string.start_with?("//") && !string.match?(/[\x00-\x1f\x7f\\]/)
+      Studio::LocalPath.local?(path)
     end
 
     # Studio.booking_path: nil, a local path, or a callable receiving the view.

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
@@ -206,5 +299,6 @@ module Studio
         Studio.validate_user_contract!(::User)
       end
     end
+
   end
 end

data/lib/studio/link_token.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "local_path"
 
 module Studio
   # Pure-Ruby helpers behind the Studio::Link model — token minting, the kind
@@ -53,12 +54,13 @@ module Studio
       email.to_s.strip.downcase
     end
 
-    # Only same-origin absolute paths survive; protocol-relative ("//evil"),
+    # Only local paths survive (Studio::LocalPath: one leading "/", no
+    # backslash, no control character); protocol-relative ("//evil", "/\evil"),
     # absolute URLs, and blanks collapse to nil so callers fall back to a safe
-    # default redirect. Mirrors the MagicLink service's sanitizer.
+    # default redirect.
     def sanitize_path(path)
       p = path.to_s
-      p.start_with?("/") && !p.start_with?("//") ? p : nil
+      Studio::LocalPath.local?(p) ? p : nil
     end
   end
 end

data/lib/studio/local_path.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Studio
+  # The one rule for "is this a path on THIS site?", used wherever the engine
+  # writes a caller-supplied path into a redirect or an href: a sign-in's
+  # return_to, a link's target, the booking page, the link-preview fallback image.
+  #
+  # 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:
+  #   "https://x", "javascript:x"  - no leading "/": a scheme or a relative path
+  #   "//x"                        - protocol-relative: another host
+  #   "/\x", "/\/x"                - browsers (the WHATWG URL parser) read "\" as
+  #                                  "/", so these are "//x" in disguise
+  #   "/\tx", "/\nx"               - the URL parser strips tab and newline, so a
+  #                                  control character can hide a second "/"
+  # Pure Ruby, so it loads and unit-tests without Rails.
+  module LocalPath
+    # A control character (C0 or DEL) or a backslash anywhere in the path.
+    UNSAFE_CHARACTER = /[\x00-\x1f\x7f\\]/
+
+    module_function
+
+    def local?(path)
+      string = path.to_s
+      string.start_with?("/") && !string.start_with?("//") && !string.match?(UNSAFE_CHARACTER)
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.91.1"
+  VERSION = "0.92.0"
 end

data/lib/studio.rb

@@ -12,6 +12,8 @@ require "active_support/core_ext/module/attribute_accessors"
 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"
@@ -689,6 +691,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
@@ -1530,6 +1548,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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.91.1
+  version: 0.92.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -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
@@ -600,6 +650,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
@@ -614,6 +665,7 @@ files:
 - lib/studio/link_preview.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
+- lib/studio/local_path.rb
 - lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb