studio-engine 0.117.0 → 0.119.0

data/lib/studio/loader.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Studio.loader: the branded loader every app draws from its OWN icon and theme
+# colours (docs/LOADER.md). Pure Ruby apart from the art reader, so the unit
+# suite covers the config without the dummy app.
+#
+# The config is a style name, or a Hash when the style needs more:
+#
+#   config.loader = :breathe                                  # the default
+#   config.loader = { style: :orbit, icon: "/brand/icon-dark.svg" }
+#   config.loader = { style: :sparkle, art: "/brand/loader-sparkle.svg" }
+#
+# GENERIC styles draw the icon as an image and nothing else, so they work on any
+# app with no per-app art: breathe, liquid, orbit, steel.
+#
+# SIGNATURE styles animate PARTS of the icon, which no image can expose, so the
+# app names an ART file: an SVG in the icon's own viewBox holding only the
+# animated layers, each marked with data-loader:
+#
+#   weld_bead   one  <path data-loader="outline" d="..."/>  the line the bead runs
+#   sparkle     each <path data-loader="spark" d="..."/>     in the sweep order
+#
+# The icon is drawn underneath as an image; the art is inlined over it. An art
+# file that is missing, outside public/, or has no marked layer falls back to
+# breathe, so a typo can never blank the loader.
+module Studio
+  module Loader
+    class InvalidConfig < ArgumentError; end
+
+    SETTING = "Studio.loader"
+    GENERIC_STYLES = %i[breathe liquid orbit steel].freeze
+    ART_STYLES = { weld_bead: "outline", sparkle: "spark" }.freeze
+    STYLES = (GENERIC_STYLES + ART_STYLES.keys).freeze
+    DEFAULT_STYLE = :breathe
+    KEYS = %i[style icon art].freeze
+
+    # The icon the loader draws when the app names none: the navbar brand's
+    # logo, else the theme's "Navbar Logo" (Studio.logo_for), which every app
+    # already declares.
+    def self.default_icon
+      brand = Studio.respond_to?(:navbar_brand) ? Studio.navbar_brand : nil
+      (brand && brand[:logo]) || Studio.logo_for("Navbar Logo")
+    end
+
+    module_function
+
+    # The config as { style:, icon:, art: } (icon and art nil when not given).
+    def normalize(config)
+      config = { style: config } if config.is_a?(Symbol) || config.is_a?(String)
+      config = { style: DEFAULT_STYLE } if config.nil?
+      raise InvalidConfig, "#{SETTING} must be a style Symbol or a Hash (got #{config.class})" unless config.is_a?(Hash)
+
+      config = config.to_h { |key, value| [key.to_sym, value] }
+      unknown = config.keys - KEYS
+      raise InvalidConfig, "#{SETTING} has unknown key :#{unknown.first} (takes #{KEYS.join(', ')})" if unknown.any?
+
+      style = style!(config[:style] || DEFAULT_STYLE)
+      icon = path!(config[:icon], "#{SETTING}[:icon]")
+      art = path!(config[:art], "#{SETTING}[:art]")
+      if ART_STYLES.key?(style) && art.nil?
+        raise InvalidConfig, "#{SETTING} style :#{style} animates parts of the icon, so it needs an art: file " \
+                             "(an SVG of <path data-loader=\"#{ART_STYLES[style]}\"> layers; docs/LOADER.md)"
+      end
+
+      { style: style, icon: icon, art: art }.freeze
+    end
+
+    def style!(value)
+      style = value.to_s.strip.tr("-", "_").to_sym
+      return style if STYLES.include?(style)
+
+      raise InvalidConfig, "#{SETTING} style must be one of #{STYLES.map(&:inspect).join(', ')} (got #{value.inspect})"
+    end
+
+    def path!(value, label)
+      return nil if value.nil?
+      return value.strip if value.is_a?(String) && !value.strip.empty?
+
+      raise InvalidConfig, "#{label} must be a non-blank path (got #{value.inspect})"
+    end
+
+    def art_style?(style) = ART_STYLES.key?(style)
+
+    # ---- The art file ------------------------------------------------------
+    #
+    # Read from the host's public/ (the path is the URL path the app would serve
+    # it at), parsed once per file version. Returns
+    #   { view_box: "0 0 w h", width: Float, layers: [Nokogiri::XML::Element] }
+    # with only the layers marked for `style`, or nil when there are none.
+    @art_cache = {}
+    @art_mutex = Mutex.new
+
+    class << self
+      attr_reader :art_cache
+    end
+
+    def art(path, style, root: public_root)
+      mark = ART_STYLES[style]
+      file = public_file(path, root)
+      return nil unless mark && file
+
+      key = [file, File.mtime(file).to_f, mark]
+      Loader.instance_variable_get(:@art_mutex).synchronize do
+        Loader.art_cache[key] ||= parse_art(File.read(file), mark)
+      end
+    rescue SystemCallError
+      nil
+    end
+
+    def parse_art(source, mark)
+      require "nokogiri"
+      doc = Nokogiri::XML(source)
+      svg = doc.root
+      return nil unless svg&.name == "svg"
+
+      layers = doc.xpath("//*[@data-loader='#{mark}']").select { |node| node.name == "path" && node["d"].to_s.strip != "" }
+      return nil if layers.empty?
+
+      view_box = svg["viewBox"].to_s.strip
+      numbers = view_box.split(/[\s,]+/).map { |n| Float(n, exception: false) }
+      return nil unless numbers.size == 4 && numbers.all? && numbers[2].positive? && numbers[3].positive?
+
+      {
+        view_box: numbers.map { |n| format_number(n) }.join(" "),
+        width: numbers[2],
+        layers: layers.map { |node| { d: node["d"].strip, transform: inherited_transform(node) } }.freeze
+      }.freeze
+    end
+
+    # The transforms of the layer and every group above it, outermost first, so a
+    # layer copied out of a <g transform> keeps its place.
+    def inherited_transform(node)
+      chain = []
+      while node.respond_to?(:name) && node.name != "svg" && node.name != "document"
+        chain.unshift(node["transform"]) if node["transform"].to_s.strip != ""
+        node = node.parent
+      end
+      chain.empty? ? nil : chain.join(" ")
+    end
+
+    def format_number(n) = (n % 1).zero? ? n.to_i.to_s : n.to_s
+
+    def public_root
+      defined?(::Rails) && ::Rails.respond_to?(:public_path) && ::Rails.public_path ? ::Rails.public_path.to_s : nil
+    end
+
+    # The file behind a public URL path, refusing anything that escapes public/.
+    def public_file(path, root)
+      return nil if root.nil? || path.nil? || path.match?(%r{\A[a-z]+:}i)
+
+      clean = path.split(/[?#]/).first.to_s.delete_prefix("/")
+      full = File.expand_path(clean, root)
+      return nil unless full.start_with?(File.expand_path(root) + File::SEPARATOR)
+
+      File.file?(full) ? full : nil
+    end
+  end
+end

data/lib/studio/type_scale.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Studio
+  # THE TYPE SCALE — the one set of text sizes every Studio app draws from
+  # (task engine-type-scale-roles). Alex McRitchie ruled it the standard for
+  # every app on 2026-10-28; the hub's /logos/<brand> Type Scale card shows the
+  # same multiples per brand.
+  #
+  # Each role is a multiple of one base: title 6x, heading 3x, subhead 1.5x,
+  # body 1x, fine print 0.75x. engine.css draws the roles as the utilities
+  # `type-title`, `type-heading`, `type-subhead`, `type-body` and `type-fine`
+  # (not `text-heading` / `text-body`: those are colour utilities).
+  #
+  # An app has TWO bases:
+  #   Studio.type_base        (16) public and marketing pages: 96/48/24/16/12
+  #   Studio.type_dense_base  (14) admin and ops pages, under a `type-dense`
+  #                                container: 84/42/21/14/10.5
+  # The ratios never change; a page picks its base by where it sits.
+  #
+  # This module emits the per-app variables the utilities read, in the theme
+  # tag (StudioThemeHelper#studio_theme_css_tag):
+  #
+  #   Studio::TypeScale.css
+  #   # => ":root {\n  --type-base: 16px;\n  --type-dense-base: 14px; ..."
+  module TypeScale
+    # [utility, multiple, weight] — weight :display or :text picks the app's
+    # Studio.type_display_weight or Studio.type_text_weight.
+    ROLES = [
+      ["type-title", 6, :display],
+      ["type-heading", 3, :display],
+      ["type-subhead", 1.5, :text],
+      ["type-body", 1, :text],
+      ["type-fine", 0.75, :text]
+    ].freeze
+
+    WEIGHTS = (100..900).step(100).to_a.freeze
+
+    def self.css
+      <<~CSS
+        :root {
+          --type-base: #{px(Studio.type_base, 'type_base')};
+          --type-dense-base: #{px(Studio.type_dense_base, 'type_dense_base')};
+          --type-display-weight: #{weight(Studio.type_display_weight, 'type_display_weight')};
+          --type-text-weight: #{weight(Studio.type_text_weight, 'type_text_weight')};
+        }
+      CSS
+    end
+
+    # The sizes a base gives, in pixels, largest first.
+    def self.sizes(base) = ROLES.to_h { |utility, multiple, _| [utility, base * multiple] }
+
+    def self.px(value, setting)
+      raise ArgumentError, "Studio.#{setting} must be a positive number of pixels, got #{value.inspect}" unless value.is_a?(Numeric) && value.positive?
+
+      "#{value.to_s.delete_suffix('.0')}px"
+    end
+
+    def self.weight(value, setting)
+      raise ArgumentError, "Studio.#{setting} must be one of #{WEIGHTS.join(', ')}, got #{value.inspect}" unless WEIGHTS.include?(value)
+
+      value.to_s
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.117.0"
+  VERSION = "0.119.0"
 end

data/lib/studio.rb

@@ -27,6 +27,7 @@ require "studio/color_scale"
 require "studio/environment_banner"
 require "studio/theme_resolver"
 require "studio/ui_primitives"
+require "studio/type_scale"
 require "studio/js_literal"
 require "studio/js_identifier"
 require "studio/hold_button"
@@ -41,10 +42,12 @@ require "studio/navbar_account_sidebar"
 require "studio/navbar_identity"
 require "studio/navbar_wordmark"
 require "studio/navbar_brand"
+require "studio/loader"
 require "studio/auth_labels"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
+require "studio/google_sign_in"
 require "studio/newsletter"
 require "studio/health_report"
 require "studio/agent_chat"
@@ -184,6 +187,26 @@ module Studio
   #   config.features     = %i[web3]
   mattr_accessor :auth_methods, default: %i[magic_link google]
 
+  # ---- Google sign-in, ready out of the box (Studio::GoogleSignIn) ----------
+  # :google in auth_methods draws the button; the engine registers the strategy
+  # and a default User.from_omniauth. What is left is the OAuth client, and
+  # google_ready? says whether the app has one: GOOGLE_CLIENT_ID and
+  # GOOGLE_CLIENT_SECRET both set. While it is false the button opens a modal
+  # whose "Request Google setup" mails google_setup_request_to, once per app
+  # per day, with the redirect URI to register. docs/GOOGLE_AUTH_SETUP.md.
+  def self.google_ready?(env: ENV)
+    GoogleSignIn.ready?(env: env)
+  end
+
+  mattr_accessor :google_setup_request_to, default: "team@mcritchie.studio"
+
+  # The host Google's callback lives on, e.g. "voicebox.mcritchie.studio". It
+  # names the redirect URI the setup-request email asks ops to register, and in
+  # production it pins OmniAuth's callback host. nil, the default, falls back to
+  # ENV["APP_HOST"], then the first plain hostname in config.hosts
+  # (Studio::GoogleSignIn.canonical_host). Never read from the request.
+  mattr_accessor :google_canonical_host, default: nil
+
   # ---- Capability features --------------------------------------------------
   # Coarse app-level capability switches an app opts into. Distinct from
   # auth_methods (which sign-in methods the login views render) — these gate
@@ -282,6 +305,27 @@ module Studio
     @@navbar_wordmark = NavbarWordmark.normalize(config)
   end
 
+  # ---- Branded loader ----
+  # The loader every page load, long wait and pending button draws: the app's
+  # own icon in its own theme colours, no per-app code. A style name, or a Hash
+  # with the icon (default: the navbar brand logo, else theme_logos' "Navbar
+  # Logo") and, for a signature style, the art file of marked layers. The
+  # default is :breathe. Rules: lib/studio/loader.rb; docs/LOADER.md.
+  #
+  #   config.loader = :orbit
+  #   config.loader = { style: :sparkle, icon: "/brand/icon-dark.svg",
+  #                     art: "/brand/loader-sparkle.svg" }
+  mattr_reader :loader, default: Loader.normalize(nil)
+
+  def self.loader=(config)
+    @@loader = Loader.normalize(config)
+  end
+
+  # The icon the loader draws: the configured one, else Loader.default_icon.
+  def self.loader_icon
+    loader[:icon] || Loader.default_icon
+  end
+
   def self.sign_in_label=(label)
     NavbarIdentity.validate_label!(label)
     @@sign_in_label = label
@@ -1269,6 +1313,15 @@ module Studio
   mattr_accessor :theme_danger,   default: "#EF4444"
   mattr_accessor :theme_accent,   default: "#F72585"
 
+  # Type scale (Studio::TypeScale): the body size every type-* role multiplies.
+  # type_base for public pages, type_dense_base inside a `type-dense` container
+  # (admin and ops pages). Weights: title and heading take the display weight,
+  # subhead, body and fine print the text weight. Set them from the brand kit.
+  mattr_accessor :type_base,           default: 16
+  mattr_accessor :type_dense_base,     default: 14
+  mattr_accessor :type_display_weight, default: 800
+  mattr_accessor :type_text_weight,    default: 400
+
   # S3 / object storage — host apps MUST set s3_bucket_prefix explicitly in
   # config/initializers/studio.rb before any S3-touching code runs (ImageCache,
   # Studio::S3.upload, etc.). Default is nil so external users don't accidentally
@@ -1726,6 +1779,16 @@ module Studio
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
+      # "Request Google setup", the button in the Google modal an app shows
+      # while its OAuth client is unset (Studio::GoogleSignIn). Mails the team
+      # once per app per day, and answers 404 once the
+      # button posts; unauthenticated, since the person asking cannot
+      # sign in yet. Drawn whenever the Google button can be.
+      if Studio.auth_method?(:google)
+        post "_studio/google_setup_request", to: "studio/google_setup_requests#create",
+             as: :studio_google_setup_request
+      end
+
       # The daily health report as JSON, for the hub's central 07:00 pull
       # (Studio::HealthReportsController). Drawn in EVERY environment, production
       # included: the controller is the gate, answering 404 until the app names

data/studio-engine.gemspec

@@ -63,6 +63,14 @@ Gem::Specification.new do |spec|
   # allows accepts redis 6. test/lib/gemspec_redis_bound_test.rb pins it.
   spec.add_dependency "redis", ">= 4.0.1", "< 6"
   spec.add_dependency "turbo-rails", ">= 1.0"
+  # Google sign-in ships ready (Studio::GoogleSignIn). Every app draws the
+  # "Sign in with Google" button, so every app carries the strategy: the engine
+  # registers google_oauth2 itself unless the host's own initializer already did.
+  # Bounds match the consumers' locks (omniauth 2.1, google-oauth2 1.2,
+  # rails_csrf_protection 1.0 and 2.0).
+  spec.add_dependency "omniauth", ">= 2.1", "< 3"
+  spec.add_dependency "omniauth-google-oauth2", ">= 1.1", "< 2"
+  spec.add_dependency "omniauth-rails_csrf_protection", ">= 1.0", "< 3"
   # IP -> location for Studio::Geo. A dependency rather than a host concern
   # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.117.0
+  version: 0.119.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -174,6 +174,66 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: omniauth-google-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: omniauth-rails_csrf_protection
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: geocoder
   requirement: !ruby/object:Gem::Requirement
@@ -400,6 +460,7 @@ files:
 - app/controllers/studio/component_previews_controller.rb
 - app/controllers/studio/emails_controller.rb
 - app/controllers/studio/geo_settings_controller.rb
+- app/controllers/studio/google_setup_requests_controller.rb
 - app/controllers/studio/health_reports_controller.rb
 - app/controllers/studio/knowledge_docs_controller.rb
 - app/controllers/studio/links_controller.rb
@@ -419,6 +480,7 @@ files:
 - app/helpers/studio/fizz_helper.rb
 - app/helpers/studio/geo_helper.rb
 - app/helpers/studio/link_preview_helper.rb
+- app/helpers/studio/loader_helper.rb
 - app/helpers/studio/public_user_helper.rb
 - app/helpers/studio/site_footer_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
@@ -466,6 +528,7 @@ files:
 - app/javascript/studio/leveling_activity.js
 - app/javascript/studio/link_preview_card.js
 - app/javascript/studio/link_sidebar.js
+- app/javascript/studio/loader.js
 - app/javascript/studio/local_path.js
 - app/javascript/studio/modal_countdown.js
 - app/javascript/studio/modal_host.js
@@ -486,12 +549,14 @@ files:
 - app/jobs/studio/email_delivery_job.rb
 - app/jobs/studio/health_report_job.rb
 - app/mailers/application_mailer.rb
+- app/mailers/studio/google_setup_mailer.rb
 - app/mailers/studio/health_report_mailer.rb
 - app/mailers/studio/newsletter_mailer.rb
 - app/mailers/studio/profile_mailer.rb
 - app/mailers/user_mailer.rb
 - app/models/concerns/sluggable.rb
 - app/models/concerns/studio/board/rankable.rb
+- app/models/concerns/studio/omniauth_user.rb
 - app/models/current.rb
 - app/models/error_log.rb
 - app/models/image_cache.rb
@@ -591,6 +656,10 @@ files:
 - app/views/studio/emails/show.html.erb
 - app/views/studio/fields/_date_of_birth.html.erb
 - app/views/studio/geo_settings/edit.html.erb
+- app/views/studio/google_setup_mailer/setup_requested.html.erb
+- app/views/studio/google_setup_mailer/setup_requested.text.erb
+- app/views/studio/google_sign_in/_button.html.erb
+- app/views/studio/google_sign_in/_setup_modal.html.erb
 - app/views/studio/health_report_mailer/daily.html.erb
 - app/views/studio/health_report_mailer/daily.text.erb
 - app/views/studio/knowledge_docs/_access_chips.html.erb
@@ -610,6 +679,8 @@ files:
 - app/views/studio/knowledge_docs/preview.html.erb
 - app/views/studio/knowledge_docs/show.html.erb
 - app/views/studio/links/confirm.html.erb
+- app/views/studio/loader/_loader.html.erb
+- app/views/studio/loader/_overlay.html.erb
 - app/views/studio/local_emails/index.html.erb
 - app/views/studio/mailers/_layered_banner.html.erb
 - app/views/studio/modals/_crop_photo.html.erb
@@ -755,6 +826,7 @@ files:
 - lib/studio/geo.rb
 - lib/studio/geo/countries.rb
 - lib/studio/geo/lookup.rb
+- lib/studio/google_sign_in.rb
 - lib/studio/health_report.rb
 - lib/studio/hold_button.rb
 - lib/studio/host_schema.rb
@@ -772,6 +844,7 @@ files:
 - lib/studio/link_preview.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
+- lib/studio/loader.rb
 - lib/studio/local_path.rb
 - lib/studio/log_rotation.rb
 - lib/studio/mail_sender.rb
@@ -812,6 +885,7 @@ files:
 - lib/studio/survey/export.rb
 - lib/studio/tailwind_entry.rb
 - lib/studio/theme_resolver.rb
+- lib/studio/type_scale.rb
 - lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb
 - lib/studio/version.rb