studio-engine 0.116.2 → 0.118.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506b8003a5848c60123a2707d1d6a13a847e9bcb5a64f153357f5313d7916c21
-  data.tar.gz: f5c669e411552093d0a8809d125b51edeaf14579c852d8fd87929f18ff6cf387
+  metadata.gz: 48ec929ff6a1178b1f5d031f591f3e6f90f4e3257feb303063e40dcd9b142eeb
+  data.tar.gz: c4215b12c48ac7dbcb829e53faca80412007f2da8c0d785641412d375f847f74
 SHA512:
-  metadata.gz: 128d8cf927f3a12da9133867bb17d4fabb59e033f7dc72f860af62d1d8eb23e4c33c622b6892138b1a2cc10af666ad4941d9782ae96158247fb4c8980644cd26
-  data.tar.gz: c1b006da8088c23fd26bd7a32e7daef52b631b2dd0ea8e3f41646daad20e77a9b4445dc327cd3189ae1cd15265694fd8c8d62147229d98785ec8290e4a72942f
+  metadata.gz: 898cba360f134fbc33f800b329e0914a82ed6ecb2af4306dc907361a246845d7974f70f80b2f3740bace96bd2ea7d08ff93b3a4523e27e3a30c223445e442c95
+  data.tar.gz: df32d0a535175c62b3390e8cbbbbc1df96d1be5ac4479711ee388cdbb3643914ec37ca3b04a43c79d1a4d12279145baa2777143079a633f7ba844bb141d9a99c

data/CHANGELOG.md

@@ -4,6 +4,50 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.118.0 — 2026-10-28
+
+### Added
+
+- **The type scale: five text roles every app draws from.** `type-title` (6x),
+  `type-heading` (3x), `type-subhead` (1.5x), `type-body` (1x) and `type-fine`
+  (0.75x), each a multiple of `--type-base`, which the theme tag sets from
+  `Studio.type_base` (16). A `type-dense` container swaps in
+  `Studio.type_dense_base` (14) for admin and ops pages. Title and heading take
+  `Studio.type_display_weight` (800), the rest `Studio.type_text_weight` (400).
+  Nothing changes on a page until it uses a role. README "Type scale".
+
+## 0.117.0 — 2026-10-28
+
+### Changed
+
+- **The default sender names the app: `"<Studio.app_name> <team@mcritchie.studio>"`.**
+  With no `RESEND_MAILER_FROM` and no `resend_from:`,
+  `Studio.mailer_from_for_transport`, `Studio.marketing_from_for_transport`, the
+  engine's `ApplicationMailer` and `studio:email:smoke` now send as the app
+  (`Studio.default_mailer_from`) rather than as "McRitchie Studio"; an app that
+  never set `app_name` still sends as "McRitchie Studio". Every app sends from
+  team@mcritchie.studio; a client's own sending domain is a paid tier upgrade
+  set through `RESEND_MAILER_FROM`. `Studio.resend_mailer_from` defaults to
+  nil and reads that default; setting it still wins. The retired `ses_from:`
+  stays ignored, so an initializer passing only `ses_from:` now gets the app's
+  own name. Set `app_name` before calling the helper in the configure block.
+
+### Added
+
+- **Production refuses an example.com sender.** The engine's after_initialize
+  raises `Studio::MailSender::PlaceholderSenderError` in production when
+  `ApplicationMailer` or `UserMailer` resolves to an example.com, .net or .org
+  address: the Rails scaffold's `app/mailers/application_mailer.rb`
+  (`default from: "from@example.com"`) shadows the engine's, and Resend refused
+  every magic link in voicebox and moms-app. It runs in rake tasks too, so
+  Heroku's `assets:precompile` fails the build and the placeholder never
+  releases. The message names the fix. A sender proc that raises at boot is
+  logged and skipped. **Consumers still carrying the scaffold mailer must
+  delete it or re-point it at `Studio.mailer_from` before bumping.**
+  [`docs/NEW_APP_SETUP.md`](docs/NEW_APP_SETUP.md). Guarded by
+  `test/lib/studio/mail_sender_test.rb` and
+  `test/integration/mail_sender_boot_test.rb`.
+
 ## 0.116.2 — 2026-10-28
 
 ### Added

data/README.md

@@ -155,7 +155,7 @@ Studio.configure do |config|
   config.welcome_message = ->(user) { "Welcome, #{user.display_name}!" }
   config.auth_methods = %i[magic_link google]
   config.registration_params = [:name, :email]
-  config.mailer_from = Studio.mailer_from_for_transport # RESEND_MAILER_FROM, else the shared sender
+  config.mailer_from = Studio.mailer_from_for_transport # RESEND_MAILER_FROM, else "<app_name> <team@mcritchie.studio>"
   config.theme_primary = "#4BAF50"   # Override default violet
   config.theme_logos = ["logo.svg"]
 
@@ -310,6 +310,47 @@ flag — it cannot know where the reader is sitting, so only the reader's machin
 may assert one. A host that omits the script still gets working stamps, just
 frozen in the app's timezone. Specimen: `/admin/style` → Tricks → Time stamps.
 
+### Type scale — `type-*`
+
+The one set of text sizes every Studio app uses (Alex McRitchie's standard,
+2026-10-28; the hub's `/logos/<brand>` Type Scale card shows it per brand).
+Each role is a multiple of one base:
+
+| Utility | Multiple | Public base (16 px) | Dense base (14 px) | Weight |
+|---|---|---|---|---|
+| `type-title` | 6x | 96 px | 84 px | display |
+| `type-heading` | 3x | 48 px | 42 px | display |
+| `type-subhead` | 1.5x | 24 px | 21 px | text |
+| `type-body` | 1x | 16 px | 14 px | text |
+| `type-fine` | 0.75x | 12 px | 10.5 px | text |
+
+```erb
+<h1 class="type-title text-heading">Winter Run 2026</h1>
+<p class="type-body text-body">Since 2016 ...</p>
+
+<%# an admin or ops page: everything inside takes the dense base %>
+<main class="type-dense">
+  <h1 class="type-heading text-heading">Releases</h1>
+</main>
+```
+
+- **Public pages** use the public base. **Admin and ops pages** put
+  `type-dense` on their container: the roles inside keep their ratios on the
+  dense base.
+- **Set the base and weights from the brand kit**, in
+  `config/initializers/studio.rb`: `Studio.type_base`,
+  `Studio.type_dense_base`, `Studio.type_display_weight`,
+  `Studio.type_text_weight`. The theme tag (`studio_theme_css_tag`) writes them
+  as `--type-base`, `--type-dense-base`, `--type-display-weight` and
+  `--type-text-weight`; a bad value raises, naming the setting.
+- **A role sets size, weight and line height only.** Colour stays with
+  `text-heading`, `text-body` and the rest, which are colour utilities, not
+  sizes.
+- **Nothing is smaller than `type-fine`.** A new page uses the roles, not
+  `text-xs` or `text-2xs`; existing pages move over app by app.
+- The multiples live in `Studio::TypeScale::ROLES` and in `engine.css`;
+  `test/lib/type_scale_contract_test.rb` keeps the two the same.
+
 ### Tints and shades — `.scrim`
 
 Text laid over media on a PAGE (a hero photo, a video, a banner) reads through

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

@@ -179,6 +179,50 @@ body.modal-open .studio-app-banner {
   @apply bg-inset rounded-xl border border-subtle p-4 overflow-x-auto;
 }
 
+/* -- Type scale ------------------------------------------------------------
+   The one set of text sizes every app draws from (Studio::TypeScale, README
+   "Type scale"). Each role is a multiple of --type-base: title 6x, heading 3x,
+   subhead 1.5x, body 1x, fine print 0.75x. The theme tag sets the app's base
+   (Studio.type_base, 16px) and weights; `type-dense` swaps in the dense base
+   (Studio.type_dense_base, 14px) for everything inside it, for admin and ops
+   pages. The fallbacks are the engine defaults, for a page with no theme tag.
+   The multiples here must match Studio::TypeScale::ROLES
+   (test/lib/type_scale_contract_test.rb). */
+
+@utility type-dense {
+  --type-base: var(--type-dense-base, 14px);
+}
+
+@utility type-title {
+  font-size: calc(var(--type-base, 16px) * 6);
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.05;
+}
+
+@utility type-heading {
+  font-size: calc(var(--type-base, 16px) * 3);
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.1;
+}
+
+@utility type-subhead {
+  font-size: calc(var(--type-base, 16px) * 1.5);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.25;
+}
+
+@utility type-body {
+  font-size: calc(var(--type-base, 16px) * 1);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.5;
+}
+
+@utility type-fine {
+  font-size: calc(var(--type-base, 16px) * 0.75);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.4;
+}
+
 /* -- Scrims: tints and shades ----------------------------------------------
    A scrim is the wash laid over media (a photo, a video) so text reads on it.
    It comes in two TONES, and the tone is a design decision, not a colour pick:

data/app/helpers/studio_theme_helper.rb

@@ -10,6 +10,6 @@ module StudioThemeHelper
       Studio::ThemeResolver.new(colors).to_css
     end
 
-    tag.style("#{css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
+    tag.style("#{css}\n#{Studio::TypeScale.css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
   end
 end

data/app/mailers/application_mailer.rb

@@ -3,5 +3,8 @@ class ApplicationMailer < ActionMailer::Base
   # the host's config/initializers/studio.rb, with an ENV fallback. No layout is
   # forced — ActionMailer renders bare if the host ships no mailer layout, and a
   # host that defines its own ApplicationMailer (e.g. turf-monster) wins outright.
-  default from: -> { Studio.mailer_from || ENV["MAILER_FROM"] || "McRitchie Studio <team@mcritchie.studio>" }
+  #
+  # Unset, it is "<Studio.app_name> <team@mcritchie.studio>": every app sends
+  # from team@ under its own name (a client's own domain is a tier upgrade).
+  default from: -> { Studio.mailer_from.presence || ENV["MAILER_FROM"].presence || Studio.default_mailer_from }
 end

data/lib/studio/email_smoke.rb

@@ -107,7 +107,7 @@ module Studio
       def sender(env = ENV)
         studio_value(:mailer_from) ||
           env_value(env, "MAILER_FROM") ||
-          "McRitchie Studio <team@mcritchie.studio>"
+          default_sender
       end
 
       def transport_label(action_mailer:, env: ENV)
@@ -128,6 +128,14 @@ module Studio
 
       private
 
+      def default_sender
+        if defined?(Studio) && Studio.respond_to?(:default_mailer_from)
+          Studio.default_mailer_from
+        else
+          "McRitchie Studio <team@mcritchie.studio>"
+        end
+      end
+
       def body_for(app_name:, to:, from:, transport:, delivery_method:, perform_deliveries:, sent_at:)
         <<~TEXT
           Email smoke test for #{app_name}

data/lib/studio/engine.rb

@@ -347,6 +347,21 @@ module Studio
     end
 
     config.after_initialize do
+      # Refuse to boot in production when ApplicationMailer (or the magic-link
+      # UserMailer) sends from an example.com placeholder: the Rails scaffold's
+      # app/mailers/application_mailer.rb shadows the engine's and Resend
+      # refuses every send. Boot, not the email smoke: Heroku's build boots
+      # production for assets:precompile, so the build fails and the bad slug
+      # never releases, while the smoke is an operator step a deploy can skip.
+      # Rake tasks are checked too, on purpose. Studio::MailSender.
+      if defined?(::ActionMailer::Base)
+        Studio::MailSender.verify!(
+          mailer_classes: %w[ApplicationMailer UserMailer].filter_map(&:safe_constantize),
+          rails_env: Rails.env,
+          logger: Rails.logger
+        )
+      end
+
       # Configure the IP -> location provider for every app that has the gem,
       # so geo detection works the same way everywhere: HTTPS (without which
       # ipinfo silently returns nothing), a 3s timeout, and a Rails.cache-backed

data/lib/studio/mail_sender.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Studio
+  # Who engine-sent mail comes from, and the production guard that refuses a
+  # placeholder sender.
+  #
+  # Every app sends from team@mcritchie.studio under its own name (Alex
+  # McRitchie's ruling, 2026-10-28); a client's own sending domain is a paid
+  # tier upgrade, set through RESEND_MAILER_FROM or `resend_from:`.
+  #
+  # The guard exists because `rails new` writes app/mailers/application_mailer.rb
+  # with `default from: "from@example.com"`. That class SHADOWS the engine's
+  # ApplicationMailer, so every mailer, the magic link included, inherits the
+  # placeholder, and Resend refuses every send. voicebox and moms-app both
+  # shipped it and nobody could sign in. Pure Ruby, so the unit suite exercises
+  # this file itself rather than a mirror of it.
+  module MailSender
+    TEAM_ADDRESS = "team@mcritchie.studio"
+    FALLBACK_NAME = "McRitchie Studio"
+    # The engine's own app_name default; an app that never named itself sends as
+    # the platform rather than as "Studio".
+    UNNAMED_APP = "Studio"
+
+    # RFC 2606 reserved second-level domains, and any host under them.
+    PLACEHOLDER_DOMAIN = /@(?:[a-z0-9-]+\.)*example\.(?:com|net|org)(?![a-z0-9.-])/i
+    # RFC 5322 "specials": a display name carrying one must be quoted.
+    DISPLAY_NAME_SPECIALS = /[()<>\[\]:;@\\,."]/
+
+    class PlaceholderSenderError < StandardError; end
+
+    module_function
+
+    # "<app name> <team@mcritchie.studio>", the sender when nothing else is set.
+    def default_for(app_name)
+      name = app_name.to_s.strip
+      name = FALLBACK_NAME if name.empty? || name == UNNAMED_APP
+      "#{display_name(name)} <#{TEAM_ADDRESS}>"
+    end
+
+    def display_name(name)
+      return name unless name.match?(DISPLAY_NAME_SPECIALS)
+
+      %("#{name.gsub(/(["\\])/) { "\\#{Regexp.last_match(1)}" }}")
+    end
+
+    # True when any address in `from` (a String or an Array of them) sits on an
+    # example.com / .net / .org domain.
+    def placeholder?(from)
+      Array(from).any? { |address| address.to_s.match?(PLACEHOLDER_DOMAIN) }
+    end
+
+    # The From: a mailer class would stamp on a message that sets none itself:
+    # its `default from:`, with a proc default evaluated the way ActionMailer
+    # evaluates it (inside a mailer instance).
+    def resolve(mailer_class)
+      from = mailer_class.default_params[:from]
+      return from unless from.respond_to?(:call)
+
+      mailer = mailer_class.send(:new)
+      from.arity == 1 ? mailer.instance_exec(mailer, &from) : mailer.instance_exec(&from)
+    end
+
+    # Raises PlaceholderSenderError in production when any of `mailer_classes`
+    # resolves to an example.com sender. Outside production it does nothing, so
+    # a test or a desk that never sends real mail is never stopped by it.
+    #
+    # It runs at boot (the engine's after_initialize), and Heroku's build runs
+    # `assets:precompile` in production, so a placeholder fails the BUILD: the
+    # bad slug never releases and the running release keeps serving. A sender
+    # that cannot be resolved at boot (its proc raises) is logged and skipped:
+    # the guard refuses a placeholder it can see, and never a boot it cannot read.
+    def verify!(mailer_classes:, rails_env:, logger: nil)
+      return :skipped unless rails_env.to_s == "production"
+
+      Array(mailer_classes).compact.uniq.each do |mailer_class|
+        from =
+          begin
+            resolve(mailer_class)
+          rescue StandardError => e
+            logger&.warn("[mail] could not resolve #{mailer_class.name}'s default sender at boot (#{e.class}: #{e.message}); placeholder guard skipped it")
+            next
+          end
+        raise PlaceholderSenderError, refusal(mailer_class, from) if placeholder?(from)
+      end
+      :verified
+    end
+
+    def refusal(mailer_class, from)
+      <<~MSG.strip
+        #{mailer_class.name} sends from #{Array(from).join(', ').inspect}, an example.com placeholder, and Resend refuses every such send (no magic link would arrive).
+        The Rails scaffold's app/mailers/application_mailer.rb shadows the engine's ApplicationMailer. Delete it, or set:
+          default from: -> { Studio.mailer_from.presence || "#{default_for(defined?(Studio) && Studio.respond_to?(:app_name) ? Studio.app_name : nil)}" }
+        and pass resend_from: (not ses_from:) to Studio.mailer_from_for_transport in config/initializers/studio.rb. See studio-engine docs/NEW_APP_SETUP.md.
+      MSG
+    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.116.2"
+  VERSION = "0.118.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"
@@ -51,6 +52,7 @@ require "studio/agent_chat"
 require "studio/username_generator"
 require "studio/public_user"
 require "studio/name_parts"
+require "studio/mail_sender"
 require "studio/s3"
 require "studio/storage"
 require "studio/image_cache"
@@ -1206,7 +1208,22 @@ module Studio
   # Default From: for engine-sent mail (magic links). Apps set this to their
   # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil
-  mattr_accessor :resend_mailer_from, default: "McRitchie Studio <team@mcritchie.studio>"
+  # The Resend sender when neither RESEND_MAILER_FROM nor `resend_from:` is
+  # given. Unset (nil), it reads "<Studio.app_name> <team@mcritchie.studio>"
+  # (Studio::MailSender.default_for): every app sends from team@ under its own
+  # name, and a client's own sending domain is a paid tier upgrade.
+  mattr_writer :resend_mailer_from, default: nil
+
+  def self.resend_mailer_from
+    value = @@resend_mailer_from
+    value.nil? || value.to_s.strip.empty? ? default_mailer_from : value
+  end
+
+  # "<Studio.app_name> <team@mcritchie.studio>"; "McRitchie Studio" for an app
+  # that never set app_name.
+  def self.default_mailer_from
+    Studio::MailSender.default_for(app_name)
+  end
 
   # Local/worktree email capture. nil means "auto": enabled when AGENT_WORKTREE
   # is truthy, otherwise disabled. Production always disables capture.
@@ -1253,6 +1270,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
@@ -1410,8 +1436,10 @@ module Studio
 
   # The sender for transactional mail. Resend is the only provider (SES was
   # retired 2026-10-10): RESEND_MAILER_FROM, then resend_from, then
-  # Studio.resend_mailer_from. `ses_from:` is still ACCEPTED so existing
-  # consumer initializers keep booting, and IGNORED; drop it at your leisure.
+  # Studio.resend_mailer_from (unset: "<app_name> <team@mcritchie.studio>").
+  # `ses_from:` is still ACCEPTED so existing consumer initializers keep
+  # booting, and IGNORED: pass resend_from: instead. Set app_name BEFORE this
+  # call in the configure block, since the default reads it.
   def self.mailer_from_for_transport(env: ENV, ses_from: nil, resend_from: nil)
     env_value(env, "RESEND_MAILER_FROM") || resend_from || resend_mailer_from
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.116.2
+  version: 0.118.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -774,6 +774,7 @@ files:
 - lib/studio/link_token.rb
 - lib/studio/local_path.rb
 - lib/studio/log_rotation.rb
+- lib/studio/mail_sender.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb
 - lib/studio/navbar_account_sidebar.rb
@@ -811,6 +812,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