studio-engine 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da34668d5a20c0af381f45d37de84594937f3687db9f90cd9abb18a88e861f26
+  data.tar.gz: 2ce061aa2892e42dc83609e8a07848bcfbbf1180074b4ec3579068ef12b6cf28
+SHA512:
+  metadata.gz: 49e7e91f9f786b86e9ce38c64f7b86ddb0c07de6dc908e8d5af2c03a945347e7317c90d949a34532762e628348b14f69013bdbcf9d84564722ebd09d62269009
+  data.tar.gz: e570b26da2e8aea1366c3539cb85cfdd160395e686e5dd331f98150b734005be105dcd28b20f158bd9a552c1eff5e9bba50c15f9aa6783f88519004fabc208f7

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Both consumer Rails apps pin to a tag in their `Gemfile`; bumping the tag is a release.
+
+## v0.4.1 (2026-05-17)
+
+Pre-public-release security hardening per `SECURITY-AUDIT-2026-05-17.md`.
+
+### Fixed (security)
+- **SSRF guard in `Studio::ImageCache.cache!`** — `source_url` is now validated: rejects schemes other than http/https, blocks loopback / private / link-local IPs (incl. AWS metadata 169.254.169.254), and blocks `localhost` / `*.local` / `*.internal` / `*.lan` hostnames. Raises `Studio::ImageCache::InvalidSourceURL`. Does not defend against DNS rebinding.
+- **MIME-type allowlist in `Studio::ImageCache.cache!`** — `content_type` must be one of `ALLOWED_CONTENT_TYPES` (image/png|jpeg|jpg|webp|gif). Raises `Studio::ImageCache::UnsupportedContentType`.
+- **MiniMagick resource caps per invocation** — every resize runs with `-limit memory 256MB -limit map 512MB -limit width/height 16KP` to prevent decompression-bomb DoS.
+- **Remote source size cap** — `MAX_REMOTE_BYTES = 50MB`. Raises `Studio::ImageCache::SourceTooLarge` on overage.
+- **`ErrorLog.capture!` no longer stores `exception.inspect`** — Ruby's default inspect for many error subclasses includes ivar dumps that can carry secrets (API keys read into locals, request bodies). Now stores a sanitized `"#<{class}: {message[0,1000]}>"` instead.
+
+### Changed (breaking for misconfigured users only)
+- **`Studio.s3_bucket_prefix` no longer defaults to `"mcritchie-studio"`.** Default is `nil`; host apps MUST set explicitly in `config/initializers/studio.rb`. Both current consumer apps already do this — no impact in practice.
+- **`Studio.UserContractError` message** now points at the correct repo URL (`amcritchie/studio-engine`, not `amcritchie/studio`).
+
+### Added
+- `LICENSE` file (MIT) — gemspec already declared MIT but the file was missing. Required for RubyGems listing.
+- Gemspec author email changed from `alex@mcritchie.studio` (personal) to `studio-engine@mcritchie.studio` (project alias).
+
+## v0.4.0 (2026-05-17)
+
+### Changed (breaking)
+- **Gem renamed from `studio` to `studio-engine`.** Repo URL is now `github.com/amcritchie/studio-engine` (was `.../studio`). Consumers must update their `Gemfile`:
+  ```ruby
+  # Before:
+  gem "studio", git: "https://github.com/amcritchie/studio.git", tag: "v0.3.1"
+  # After:
+  gem "studio-engine", git: "https://github.com/amcritchie/studio-engine.git", tag: "v0.4.0"
+  ```
+- The Ruby `Studio` module name is **unchanged** — all call sites (`Studio.configure`, `Studio::ErrorHandling`, `Studio::ImageCache`, etc.) keep working without code changes.
+- Gem entry point at `lib/studio-engine.rb` (a thin `require_relative "studio"` shim) ensures `gem "studio-engine"` auto-requires correctly without a `require:` option in the Gemfile.
+
+### Added
+- `LICENSE`, gemspec `metadata` (homepage / source / bugs / changelog URIs), `spec.description`, `spec.required_ruby_version` — getting ready for RubyGems publishing.
+
+## v0.3.1 (2026-05-17)
+
+### Fixed
+- `Studio.validate_user_contract!` no longer checks for `User#email` (or any column-style attribute). ActiveRecord defines column accessors lazily, so they don't appear on `.instance_methods` until first record access — leading to false-positive `Studio::UserContractError` raises at boot. Only explicitly-defined methods (`authenticate`, `admin?`, `display_name`, class `find_by`) are validated. DB columns are out of scope; missing columns fail the User table migration instead.
+
+## v0.3.0 (2026-05-17)
+
+### Added
+- **Shared stage-* badge palette.** New scheme aliases on `app/views/components/_badge.html.erb`: `stage-fresh` (blue), `stage-shaping` (yellow), `stage-structured` (mint), `stage-refined` (emerald), `stage-cohered` (violet), `stage-shipped` (emerald), `stage-closed` (gray). Consumer apps' News + Content stage helpers can now resolve to a unified palette instead of each picking ad-hoc scheme names per stage. Closes ecosystem-audit Tier 1 #2.
+- **`Studio.validate_user_contract!`** + boot-time validator hook in `Engine#after_initialize`. Verifies host's `User` class responds to required methods (`authenticate`, `admin?`, `email`, `display_name`, plus class `find_by`). Raises `Studio::UserContractError` with a clear pointer to `docs/USER_CONTRACT.md` when something's missing — replaces the previous cryptic `NoMethodError` at first request. Opt out per-app with `Studio.validate_user_contract = false`. Closes ecosystem-audit Tier 2 #16.
+- **`docs/USER_CONTRACT.md`** — full reference for required + optional User methods, recommended DB columns, and a minimal compliant model example.
+- **Sentry fan-out from `ErrorLog.capture!`.** When the host app has loaded `sentry-ruby` (and Sentry is initialized via DSN), every `ErrorLog.capture!` call also sends the exception to Sentry with `error_log_slug` as a tag for cross-reference. Apps without `sentry-ruby` are unaffected — the call is guarded with `defined?(::Sentry)`. Closes ecosystem-audit Tier 2 #15.
+
+### Changed
+- Stage badge color schemes are additive — existing `success/danger/warning/info/violet/primary/orange/emerald/gray/neutral` schemes unchanged.
+
+### Notes
+- Both current consumer apps (mcritchie-studio, turf-monster) already satisfy the new User contract — validator is a no-op for them.
+
+## v0.2.4 (pre-2026-05-17)
+
+Last release before formal versioning. Consumer apps tracked `git: main` until this point. v0.2.4 is the snapshot at the previous commit `ef738ff` ("Studio::ImageCache.cache! accepts source_path for local files"). Anything before that is in `git log`.

data/Gemfile

@@ -0,0 +1,18 @@
+source "https://rubygems.org"
+
+gemspec
+
+# nokogiri 1.18.10 has 3 CVEs (1 HIGH regex-backtracking + 2 MEDIUM
+# in XSLT / xmlC14NExecute). Fix is `>= 1.19.3` but nokogiri 1.19.x
+# requires Ruby 3.2+. The ecosystem currently runs on Ruby 3.1.7;
+# bumping Ruby is a separate effort (across both Rails apps).
+#
+# **Important**: this gem does NOT declare nokogiri as a runtime
+# dependency in its gemspec — nokogiri comes into the consuming
+# Rails app via Rails itself. Consumers running Rails on a Ruby
+# version that supports nokogiri 1.19.x will resolve it. The
+# studio-engine gem's own Gemfile.lock (this repo's dev env) is the
+# only place still on 1.18.10.
+#
+# Tracked in SECURITY-AUDIT-2026-05-17.md. When the ecosystem bumps
+# to Ruby 3.2+, add: gem "nokogiri", ">= 1.19.3", group: :development

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Alex McRitchie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Studio Engine
+
+Shared Rails engine for McRitchie apps. Provides authentication, error handling, dynamic theming, and common concerns used by [McRitchie Studio](https://app.mcritchie.studio) and [Turf Monster](https://turf.mcritchie.studio).
+
+> **Part of the McRitchie ecosystem** — see [`ECOSYSTEM.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/ECOSYSTEM.md) for the 5-repo map; [`house-burn-down.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/agents/system/house-burn-down.md) for fresh-Mac recovery.
+
+## Installation
+
+```ruby
+# Gemfile — pin to a tag (recommended; see Releases section)
+gem "studio-engine", git: "https://github.com/amcritchie/studio-engine.git", tag: "v0.3.0"
+```
+
+Then `bundle install`. The current release is **v0.3.0**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+
+> Pinning to a tag (not `main`) is now the recommended pattern. Consumer apps that track `main` will silently inherit any engine merge — bad when one merge breaks several apps at once.
+
+## What It Provides
+
+- **Authentication**: Session-based login/signup controllers and views, Google OAuth via OmniAuth, one-way SSO (hub to satellite)
+- **Error handling**: `Studio::ErrorHandling` concern with `rescue_and_log`, `ErrorLog` model with `capture!`, error log viewer at `/error_logs`
+- **Theme system**: Dynamic CSS custom properties generated from 7 role colors (primary, dark, light, success, accent, warning, danger). Dark/light mode toggle. Admin theme editor at `/admin/theme`.
+- **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
+- **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
+
+## Configuration
+
+Each consuming app configures the engine in `config/initializers/studio.rb`:
+
+```ruby
+Studio.configure do |config|
+  config.app_name = "My App"
+  config.session_key = :my_app_user_id
+  config.sso_logo = "/logo.svg"
+  config.welcome_message = ->(user) { "Welcome, #{user.display_name}!" }
+  config.registration_params = [:name, :email, :password, :password_confirmation]
+  config.theme_primary = "#4BAF50"   # Override default violet
+  config.theme_logos = ["logo.svg"]
+end
+```
+
+## Routes
+
+In the consuming app's `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  Studio.routes(self)
+  # ... app routes
+end
+```
+
+This draws: `/login`, `/signup`, `/logout`, `/sso_continue`, `/sso_login`, `/auth/:provider/callback`, `/auth/failure`, `/error_logs`, `/admin/theme` (GET, PATCH), `/admin/theme/regenerate`.
+
+## Overriding Views
+
+This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.
+
+## Releasing
+
+Engine releases are git tags (semver: `MAJOR.MINOR.PATCH`). Both consumer apps pin to a tag in their Gemfile — bumping the tag is the release.
+
+1. Make + commit changes on `main`.
+2. Update [`CHANGELOG.md`](./CHANGELOG.md) with the new version + a `### Added` / `### Changed` / `### Removed` summary. Keep entries terse.
+3. Bump `lib/studio/version.rb` to match.
+4. Commit the version bump + CHANGELOG together (`v0.X.Y: <summary>`).
+5. Tag: `git tag -a v0.X.Y -m "<one-line summary>"`.
+6. Push: `git push origin main --tags`.
+7. In each consumer app's Gemfile, update the `tag:` field. Commit + push.
+8. On consumer prod: `bundle install` runs as part of the deploy buildpack.
+
+**Semver guide**
+- **PATCH**: bug fix; no API change. Consumers can bump tag with zero diff elsewhere.
+- **MINOR**: backward-compatible feature add. Consumers may opt in to new APIs.
+- **MAJOR**: breaking change. Consumers will need code changes alongside the tag bump.
+
+## Local development (against an unreleased engine)
+
+When iterating on engine code from a consumer app, point bundler at the local path so you don't need to push + tag for every edit:
+
+```bash
+# in the consumer app
+bundle config set --local local.studio /Users/alex/projects/studio-engine
+bundle install
+# ... iterate in both repos ...
+bundle config unset --local local.studio  # restore tag-pinned resolution
+```
+
+Note: `bundle config local.studio` requires `branch:` in the Gemfile entry. If you frequently develop locally, change the Gemfile to `gem "studio-engine", git: "...", branch: "main"` during dev and back to `tag:` before merging.
+
+## Development Notes
+
+See [CLAUDE.md](./CLAUDE.md) for detailed development context including the theme architecture, SSO protocol, color scale system, and code conventions.

data/app/controllers/concerns/studio/error_handling.rb

@@ -0,0 +1,149 @@
+module Studio
+  module ErrorHandling
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      rescue_from StandardError, with: :handle_unexpected_error
+
+      before_action :require_authentication
+
+      helper_method :current_user, :logged_in?, :sso_user_available?, :sso_display_name, :sso_source_app, :sso_hub_logo, :admin?
+    end
+
+    private
+
+    def current_user
+      return @current_user if defined?(@current_user)
+
+      # Try app-specific session key
+      @current_user = User.find_by(id: session[Studio.session_key])
+
+      # Legacy migration: old shared session[:user_id]
+      if @current_user.nil? && session[:user_id].present? && Studio.session_key != :user_id
+        @current_user = User.find_by(id: session[:user_id])
+        if @current_user
+          set_app_session(@current_user)  # Migrate to new key
+          session.delete(:user_id)        # Clean up old key
+        end
+      end
+
+      @current_user
+    end
+
+    def set_app_session(user)
+      # App-specific session (only this app reads this key)
+      session[Studio.session_key] = user.id
+
+      # Only update shared awareness fields if this app is the source
+      # (don't overwrite the other app's sso_source when logging in via sso_continue)
+      if session[:sso_source].blank? || session[:sso_source] == Studio.app_name
+        session[:sso_email]    = user.email
+        session[:sso_name]     = user.try(:name)
+        session[:sso_provider] = user.provider
+        session[:sso_uid]      = user.uid
+        session[:sso_wallet]   = user.try(:wallet_address)
+        session[:sso_source]   = Studio.app_name
+        session[:sso_logo]     = Studio.sso_logo
+      end
+    end
+
+    def clear_app_session
+      session.delete(Studio.session_key)
+
+      # Clear sso_* fields only if this app is the source
+      # (preserve them if the other app set them — they're still logged in there)
+      if session[:sso_source] == Studio.app_name
+        session.delete(:sso_email)
+        session.delete(:sso_name)
+        session.delete(:sso_provider)
+        session.delete(:sso_uid)
+        session.delete(:sso_wallet)
+        session.delete(:sso_source)
+        session.delete(:sso_logo)
+      end
+    end
+
+    # Cross-app awareness helpers for login page
+    def sso_user_available?
+      !logged_in? && session[:sso_email].present? && session[:sso_source] != Studio.app_name
+    end
+
+    def sso_display_name
+      session[:sso_name].presence || session[:sso_email]&.split("@")&.first&.capitalize || "User"
+    end
+
+    def sso_source_app
+      session[:sso_source]
+    end
+
+    def sso_hub_logo
+      session[:sso_logo]
+    end
+
+    def logged_in?
+      current_user.present?
+    end
+
+    def require_authentication
+      unless logged_in?
+        redirect_to login_path
+      end
+    end
+
+    def require_admin
+      return redirect_to root_path, alert: "Not authorized" unless logged_in? && current_user.admin?
+    end
+
+    def admin?
+      logged_in? && current_user.admin?
+    end
+
+    # Central error logging method — all controller error logging flows through here.
+    # Returns the ErrorLog record so callers can attach target/parent context.
+    def create_error_log(exception)
+      ErrorLog.capture!(exception)
+    end
+
+    # Layer 2: Opt-in per-action wrapper with target/parent context.
+    # Sets @_error_logged flag so Layer 1 won't double-log.
+    def rescue_and_log(target: nil, parent: nil)
+      yield
+    rescue ActiveRecord::RecordNotFound => e
+      raise e
+    rescue StandardError => e
+      error_log = create_error_log(e)
+      if target
+        error_log.target = target
+        error_log.target_name = target.slug
+      end
+      if parent
+        error_log.parent = parent
+        error_log.parent_name = parent.slug
+      end
+      error_log.save!
+      @_error_logged = true
+      raise e
+    end
+
+    # Layer 1: Catch-all for RecordNotFound — 404 redirect, no logging.
+    def handle_not_found(exception)
+      respond_to do |format|
+        format.html { redirect_to root_path, alert: "Not found" }
+        format.json { render json: { error: "Not found" }, status: :not_found }
+      end
+    end
+
+    # Layer 1: Catch-all for unexpected errors — log + friendly response.
+    # Skips logging if rescue_and_log already captured it.
+    def handle_unexpected_error(exception)
+      create_error_log(exception) unless @_error_logged
+      raise exception if Rails.env.development? || Rails.env.test?
+
+      respond_to do |format|
+        format.html { redirect_to root_path, alert: "Something went wrong." }
+        format.json { render json: { error: "Internal server error" }, status: :internal_server_error }
+      end
+    end
+  end
+end

data/app/controllers/error_logs_controller.rb

@@ -0,0 +1,16 @@
+class ErrorLogsController < ApplicationController
+  before_action :require_admin
+
+  def index
+    @error_logs = ErrorLog.order(created_at: :desc)
+    if params[:q].present?
+      @error_logs = @error_logs.where("message ILIKE :q OR target_name ILIKE :q OR parent_name ILIKE :q OR target_type ILIKE :q", q: "%#{params[:q]}%")
+    end
+    @error_logs = @error_logs.limit(100)
+  end
+
+  def show
+    @error_log = ErrorLog.find_by(slug: params[:id])
+    return redirect_to error_logs_path, alert: "Error log not found" unless @error_log
+  end
+end

data/app/controllers/navbar_controller.rb

@@ -0,0 +1,6 @@
+class NavbarController < ApplicationController
+  before_action :require_admin
+
+  def show
+  end
+end

data/app/controllers/omniauth_callbacks_controller.rb

@@ -0,0 +1,17 @@
+class OmniauthCallbacksController < ApplicationController
+  skip_before_action :require_authentication
+
+  def create
+    user = User.from_omniauth(request.env["omniauth.auth"])
+    rescue_and_log(target: user) do
+      set_app_session(user)
+      redirect_to root_path, notice: "Signed in with Google!"
+    end
+  rescue StandardError => e
+    redirect_to login_path, alert: "Google sign-in failed. Please try again."
+  end
+
+  def failure
+    redirect_to login_path, alert: "Google sign-in failed. Please try again."
+  end
+end

data/app/controllers/registrations_controller.rb

@@ -0,0 +1,25 @@
+class RegistrationsController < ApplicationController
+  skip_before_action :require_authentication
+
+  def new
+    @user = User.new
+  end
+
+  def create
+    @user = User.new(user_params)
+    Studio.configure_new_user.call(@user)
+    rescue_and_log(target: @user) do
+      @user.save!
+      set_app_session(@user)
+      redirect_to root_path, notice: Studio.welcome_message.call(@user)
+    end
+  rescue StandardError => e
+    render :new, status: :unprocessable_entity
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(*Studio.registration_params)
+  end
+end

data/app/controllers/schema_controller.rb

@@ -0,0 +1,14 @@
+class SchemaController < ApplicationController
+  before_action :require_admin
+
+  def index
+    conn = ActiveRecord::Base.connection
+    @tables = (conn.tables - %w[schema_migrations ar_internal_metadata]).sort.map do |table_name|
+      {
+        name: table_name,
+        columns: conn.columns(table_name),
+        indexes: conn.indexes(table_name)
+      }
+    end
+  end
+end

data/app/controllers/sessions_controller.rb

@@ -0,0 +1,65 @@
+class SessionsController < ApplicationController
+  skip_before_action :require_authentication
+
+  def new
+  end
+
+  def create
+    user = User.find_by(email: params[:email])
+    if user&.authenticate(params[:password])
+      set_app_session(user)
+      redirect_to root_path, notice: "Welcome back, #{user.display_name}!"
+    else
+      flash.now[:alert] = "Invalid email or password."
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  # GET /sso_login — one-click SSO entry point (linked from hub app nav)
+  def sso_login
+    return redirect_to root_path if logged_in?
+    return redirect_to login_path unless sso_user_available?
+
+    authenticate_sso_user!
+  rescue StandardError => e
+    create_error_log(e)
+    redirect_to login_path, alert: "Could not continue session. Please log in."
+  end
+
+  # POST /sso_continue — form-based SSO from login page button
+  def sso_continue
+    return redirect_to login_path unless sso_user_available?
+
+    authenticate_sso_user!
+  rescue StandardError => e
+    create_error_log(e)
+    redirect_to login_path, alert: "Could not continue session. Please log in."
+  end
+
+  def destroy
+    clear_app_session
+    redirect_to login_path, notice: "Logged out."
+  end
+
+  private
+
+  def authenticate_sso_user!
+    user = User.find_by(email: session[:sso_email])
+    unless user
+      user = User.new(
+        email:    session[:sso_email],
+        name:     session[:sso_name],
+        provider: session[:sso_provider],
+        uid:      session[:sso_uid],
+        password: SecureRandom.hex(16)
+      )
+      Studio.configure_sso_user.call(user)
+      rescue_and_log(target: user) do
+        user.save!
+      end
+    end
+
+    set_app_session(user)
+    redirect_to root_path, notice: Studio.welcome_message.call(user)
+  end
+end

data/app/controllers/theme_settings_controller.rb

@@ -0,0 +1,35 @@
+class ThemeSettingsController < ApplicationController
+  before_action :require_admin
+
+  def edit
+    @theme_setting = ThemeSetting.current
+    @defaults = Studio.theme_config
+    @preview_css = Studio::ThemeResolver.new(@theme_setting.resolved_colors).to_css
+  end
+
+  def update
+    @theme_setting = ThemeSetting.find_or_initialize_by(app_name: Studio.app_name)
+
+    rescue_and_log(target: @theme_setting) do
+      @theme_setting.update!(theme_params)
+      Rails.cache.delete("studio/theme/#{Studio.app_name}")
+      redirect_to admin_theme_path, notice: "Theme saved."
+    end
+  rescue StandardError => e
+    @defaults = Studio.theme_config
+    @preview_css = Studio::ThemeResolver.new(@theme_setting.resolved_colors).to_css
+    flash.now[:alert] = "Error saving theme: #{e.message}"
+    render :edit, status: :unprocessable_entity
+  end
+
+  def regenerate
+    Rails.cache.delete("studio/theme/#{Studio.app_name}")
+    redirect_to admin_theme_path, notice: "Theme cache cleared."
+  end
+
+  private
+
+  def theme_params
+    params.require(:theme_setting).permit(:primary, :accent1, :accent2, :warning, :danger, :dark, :light)
+  end
+end

data/app/helpers/studio_theme_helper.rb

@@ -0,0 +1,15 @@
+module StudioThemeHelper
+  def studio_theme_css_tag
+    css = Rails.cache.fetch("studio/theme/#{Studio.app_name}", expires_in: 1.hour) do
+      colors = begin
+        ThemeSetting.current.resolved_colors
+      rescue ActiveRecord::StatementInvalid
+        # Table doesn't exist yet (pre-migration) — use config defaults
+        Studio.theme_config
+      end
+      Studio::ThemeResolver.new(colors).to_css
+    end
+
+    tag.style(css.html_safe, nonce: content_security_policy_nonce)
+  end
+end

data/app/jobs/error_log_cleanup_job.rb

@@ -0,0 +1,8 @@
+class ErrorLogCleanupJob < ApplicationJob
+  queue_as :default
+
+  def perform(days_old: 30)
+    count = ErrorLog.where("created_at < ?", days_old.days.ago).delete_all
+    Rails.logger.info "[ErrorLogCleanupJob] Deleted #{count} error logs older than #{days_old} days"
+  end
+end

data/app/models/concerns/sluggable.rb

@@ -0,0 +1,17 @@
+module Sluggable
+  extend ActiveSupport::Concern
+
+  included do
+    before_save :set_slug
+  end
+
+  def to_param
+    slug
+  end
+
+  private
+
+  def set_slug
+    self.slug = name_slug
+  end
+end

data/app/models/error_log.rb

@@ -0,0 +1,45 @@
+class ErrorLog < ApplicationRecord
+  belongs_to :target, polymorphic: true, optional: true
+  belongs_to :parent, polymorphic: true, optional: true
+
+  def to_param
+    slug
+  end
+
+  def inspect_field
+    read_attribute(:inspect)
+  end
+
+  def self.capture!(exception)
+    cleaned = Rails.backtrace_cleaner.clean(exception.backtrace || [])
+
+    # Don't store exception.inspect — Ruby's default inspect for many error
+    # subclasses includes ivar dumps that can carry secrets (API keys read
+    # from ENV into a local, request bodies, etc.). Store just class +
+    # truncated message instead. Apps that need richer context should
+    # capture it explicitly via target/parent or via Sentry's PII rules.
+    safe_inspect = "#<#{exception.class}: #{exception.message.to_s[0, 1000]}>"
+
+    log = create!(
+      message: exception.message,
+      inspect: safe_inspect,
+      backtrace: cleaned.to_json
+    )
+    log.update_column(:slug, "error-log-#{log.id}")
+
+    # Fan out to Sentry if the host app loaded sentry-ruby. Guard with
+    # respond_to? so we don't blow up on old SDK versions. The DB ErrorLog
+    # row remains the local triage view; Sentry is the paging layer.
+    if defined?(::Sentry) && ::Sentry.respond_to?(:capture_exception)
+      begin
+        ::Sentry.capture_exception(exception) do |scope|
+          scope.set_tags(error_log_slug: log.slug)
+        end
+      rescue => e
+        Rails.logger.warn "[ErrorLog.capture!] Sentry delivery failed: #{e.class}: #{e.message}"
+      end
+    end
+
+    log
+  end
+end

data/app/models/image_cache.rb

@@ -0,0 +1,11 @@
+class ImageCache < ApplicationRecord
+  belongs_to :owner, polymorphic: true
+
+  validates :purpose, :variant, :s3_key, presence: true
+  validates :s3_key, uniqueness: true
+  validates :variant, uniqueness: { scope: [:owner_type, :owner_id, :purpose] }
+
+  def url
+    Studio::S3.url(key: s3_key)
+  end
+end