studio-engine 0.102.0 → 0.103.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3892a67d3cb43b26a47398f6f1560d2bb6f8d00265815dd86532e77acef4e869
-  data.tar.gz: 0ea0fb8690a31529d28cac58c22c695e6fe726d3ba5a30ecd9cd65d78b9f90d6
+  metadata.gz: 792f0e16ad48572393e4e8cf22f51d497e832af869b0d1bfe6dd5be6ac8da058
+  data.tar.gz: c862691168c2c8e782d4b4ec7d6d956058494b717fd2d4b2757f6d9f2bd60148
 SHA512:
-  metadata.gz: 9e24a1c2ffc63f222044117d12716a455204a0a58e1548092083eb9955ffc29dda9f855a4bc14efea79d44437fd48b5abe6e8311deaadc94078e979640e46f3c
-  data.tar.gz: a383db6a52bc983e52ead696868cc3d8f36d5e878606879a969faec430e12e5dd3733245c437e3204a516db9c4a0460000067083710799c407f4b3411a528b00
+  metadata.gz: 5d7b0b148093fca45e7ded99ad0056fc6a8a6e5dc698f1b85a4032414ae9a2a92b92ab94189ba3f7fc287b45fc40b1796e0b4807b910b08a99403b202d965c4a
+  data.tar.gz: 5c37ecd0f4c1f526cebe802cfc46a0dda47c4be3b1558ad57d2648de3fbfbf29fa122267551b5673f33000bf1edbaef0ba2a7154ab7f127c36fb099a14487015

data/CHANGELOG.md

@@ -4,6 +4,96 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+
+- **`--color-primary-ink` and `text-primary-ink`: the primary colour as chip
+  text.** The theme resolver derives it per theme the way it derives the
+  danger, warning and success inks: the configured primary, shaded until it
+  clears WCAG AA 4.5:1 on every surface and on its own 10%, 15% and 20% tints.
+  `text-primary` and `--color-primary` stay the brand colour.
+
+### Changed
+
+- **Primary chips are painted in the primary colour and clear AA in both
+  themes.** `Studio::BadgeComponent`'s `tone: :primary` drew heading-coloured
+  text (white in dark, near-black in light), and its `scheme: "primary"`, the
+  Marketing chip on `/admin/emails` and the sidebar's ADMIN chip drew the raw
+  primary, 2.2:1 to 3.6:1 on its tint. All of them now draw `text-primary-ink`.
+  A host that copies the tone's class string (the hub's `status_tone`) changes
+  when it adopts the class.
+- **Every role ink clears AA on its 10%, 15% and 20% tints, as a browser
+  paints them.** The apps put the inks on the stronger tints too (turf's
+  "Entered" badge is `bg-primary/15`; the hub's workflow and verdict chips are
+  `bg-success/20 text-success-ink` and `bg-warning/20 text-warning-ink`), where
+  an ink tuned to the 10% chip read as low as 3.83:1 (default warning, dark, on
+  20%). The search now counts 0.10, 26/255 (how Chromium composites a 10%
+  fill), 0.15 and 0.20, each also one unit off in every channel, because 8-bit
+  compositing rounds (Chromium painted a 20% danger tint one unit lighter than
+  the blend, taking a 4.51:1 ink to 4.47:1). The inks darken in light and
+  lighten in dark. Default theme, 0.102.0 to this release:
+
+  | Ink | Dark | Light |
+  |---|---|---|
+  | primary (new) | `#BDB7FE` | `#58519D` |
+  | success | `#8EB791` to `#96BC99` | `#2E6C32` to `#2A622D` |
+  | warning | `#FF966C` to `#FFAE8D` | `#994A2B` to `#8F4528` |
+  | danger | `#F58F8F` to `#F79E9E` | `#AC3131` to `#9E2D2D` |
+
+  A configured role colour moves the same way; a configured colour that
+  already clears every tint (mcritchie-industries' yellow warning) keeps its
+  exact hex.
+
+## 0.103.0 — 2026-10-10
+
+### Added
+
+- **Seed assets reference production.** A non-production process (laptop,
+  desk, QA app) can record an `ImageCache` row that REFERENCES an object
+  already in the production bucket instead of uploading a copy into the dev
+  bucket. New:
+  - `Studio.s3_production_public_url`: production's public host, set in
+    every environment (e.g. `https://assets.turfmonster.media`). Default nil
+    turns references off.
+  - `image_caches.stored_in` (migration `AddStoredInToImageCaches`):
+    nullable string. nil or `"own"` is the own bucket, `"production"` a
+    reference. `ImageCache#url` resolves a reference on the production host
+    off production. In production both kinds resolve on the own host, which
+    is production's.
+  - `Studio::ImageCache.reference_or_cache!`: `cache!`'s arguments and
+    answer. Off production, with the setting, it HEADs each missing variant
+    in `<prefix>-production` (read-only) and records a reference when found,
+    else uploads to the own bucket as `cache!` does. A HEAD failing for any
+    reason but not-found raises. In production, or without the setting, it
+    is `cache!`.
+  - `Studio::S3.production_bucket`, `production_references?`,
+    `production_url`, `production_head`, `production_exists?` and
+    `production_download`: reads only. `ImageCache#download` and
+    `#delete_object!` act on the bucket that holds the row's object;
+    off production `delete_object!` deletes nothing for a reference.
+
+  **Design.** A per-row marker plus one configured host, because a row must
+  say whose object it is: 11 of 12 sampled Turf headshot keys were on
+  production and one (`kenneth-walker-iii`) was only on dev, so no app-wide
+  switch is right for every row. Rejected: storing absolute URLs in `s3_key`
+  (breaks every reader that treats it as a key, the uniqueness index and the
+  key namespace); an AR enum (raises at load on a host that has not migrated);
+  an HTTP HEAD on the public host (a CDN answer is not the bucket's, and the
+  dev token's Item Read on production makes the S3 HEAD available and
+  stubbable); requiring the column in `Studio::HostSchema` (would fail boot on
+  every consumer before it installs the migration). The existing guard
+  (`guard_production_bucket!`) still refuses any delete from a `*-production`
+  bucket off production, and the dev R2 tokens cannot write production.
+
+  **Consumer adoption.** Nothing changes until an app opts in, and production
+  behaves as before. To adopt: (1) `bin/rails studio_engine:install:migrations
+  db:migrate` and commit the copy and `db/schema.rb`; (2) set
+  `config.s3_production_public_url` to the production asset host in
+  `config/initializers/studio.rb`; (3) switch seeders from
+  `Studio::ImageCache.cache!` to `reference_or_cache!`; (4) replace any
+  `Studio::S3.download(key: row.s3_key)` or `Studio::S3.delete(key:
+  row.s3_key)` on an `ImageCache` row with `row.download` /
+  `row.delete_object!`.
+
 ## 0.102.0 — 2026-10-10
 
 ### Removed

data/README.md

@@ -979,6 +979,33 @@ be a positive Integer.
 `Studio::S3.delete` moves the object to `trash/` for three days rather than
 deleting it; see [Trash and restore](#trash-and-restore).
 
+### Seed assets reference production
+
+Seed assets (NFL headshots, Pokémon sprites) live in the **production** bucket.
+A laptop, desk or QA app points at production's copy instead of uploading a
+duplicate into the dev bucket, and uploads only what production lacks. Set
+production's public host in every environment (it is not a secret):
+
+```ruby
+config.s3_production_public_url = "https://assets.turfmonster.media"
+```
+
+and have seeders call `Studio::ImageCache.reference_or_cache!` (same arguments
+and answer as `cache!`). Off production it HEADs each missing variant in
+`<prefix>-production` (read-only; the dev R2 token holds Item Read there).
+Found: an `ImageCache` row with `stored_in = "production"`, whose `#url`
+resolves on `s3_production_public_url`. Absent: an ordinary upload to the own
+bucket. A HEAD failing for any reason but not-found raises. In production, or
+with the setting unset, it is exactly `cache!`.
+
+`stored_in` arrives by the engine migration `AddStoredInToImageCaches`
+(nullable; nil and `"own"` mean the own bucket, so existing rows keep their
+URLs). Read an object's bytes with `ImageCache#download` and remove it with
+`ImageCache#delete_object!`, never `Studio::S3.download/delete(key: row.s3_key)`:
+those read and delete the OWN bucket. Off production, `delete_object!` on a
+production reference deletes nothing, and `Studio::S3` has no write, copy or
+delete that targets the production bucket.
+
 An app with **no** bucket configured does not error — `/admin/emails` renders
 read-only, showing the inherited defaults it is genuinely sending and naming the
 one setting that turns uploads on.

data/app/components/studio/badge_component.rb

@@ -20,7 +20,8 @@ module Studio
   # 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.
+  # the stage-* pipeline ladder. Its "primary" draws the primary ink; the rest
+  # render 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.
@@ -34,7 +35,7 @@ module Studio
       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",
+      primary: "bg-primary/10 text-primary-ink border-primary/40",
       muted: "bg-surface-alt text-muted border-subtle"
     }.freeze
 
@@ -44,7 +45,7 @@ module Studio
       "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",
+      "primary" => "bg-primary/10 text-primary-ink 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",

data/app/models/image_cache.rb

@@ -1,4 +1,20 @@
 class ImageCache < ApplicationRecord
+  # Where a row's object lives (the `stored_in` column):
+  #
+  #   nil / "own"   this process's own bucket, at Studio.s3_public_url. Every row
+  #                 written before the column existed, and every upload.
+  #   "production"  a REFERENCE to production's copy, recorded by a
+  #                 non-production seeder (Studio::ImageCache.reference_or_cache!)
+  #                 instead of uploading a duplicate. It resolves on
+  #                 Studio.s3_production_public_url.
+  #
+  # A plain string, not an AR enum: the column arrives by an engine migration a
+  # host installs on its own schedule, and an enum declared on an absent column
+  # raises at load. Without the column every row reads as "own", as before.
+  STORED_IN = %w[own production].freeze
+  OWN = "own"
+  PRODUCTION = "production"
+
   # Optional so app-GLOBAL images (no owning record) can be cached too — e.g.
   # Studio::EmailCatalog stores the admin-managed email banners owner-less. Per-
   # record images (athlete/coach headshots) still set an owner; the
@@ -8,8 +24,41 @@ class ImageCache < ApplicationRecord
   validates :purpose, :variant, :s3_key, presence: true
   validates :s3_key, uniqueness: true
   validates :variant, uniqueness: { scope: [:owner_type, :owner_id, :purpose] }
+  validates :stored_in, inclusion: { in: STORED_IN }, allow_nil: true, if: -> { has_attribute?(:stored_in) }
+
+  def self.stored_in_column?
+    table_exists? && column_names.include?("stored_in")
+  end
+
+  def production_reference?
+    has_attribute?(:stored_in) && stored_in == PRODUCTION
+  end
 
+  # In production both kinds resolve on the app's own host, which IS
+  # production's, so a production app's URLs are what they always were.
   def url
-    Studio::S3.url(key: s3_key)
+    production_reference? ? Studio::S3.production_url(key: s3_key) : Studio::S3.url(key: s3_key)
+  end
+
+  # The object's bytes, read from the bucket that holds them (read-only for a
+  # production reference). Use this, not Studio::S3.download(key: s3_key),
+  # which reads this process's own bucket.
+  def download(max_bytes: nil)
+    if production_reference?
+      Studio::S3.production_download(key: s3_key, max_bytes: max_bytes)
+    else
+      Studio::S3.download(key: s3_key, max_bytes: max_bytes)
+    end
+  end
+
+  # Removes the row's OBJECT (to trash, via Studio::S3.delete). A production
+  # reference outside production is not this process's object: nothing is
+  # deleted from either bucket (the own bucket may hold an unrelated object
+  # under the same key) and nil is returned. Destroying the row itself is
+  # always fine. In production a reference is an ordinary own object.
+  def delete_object!
+    return nil if production_reference? && !Studio::S3.production_environment?
+
+    Studio::S3.delete(key: s3_key)
   end
 end

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

@@ -27,7 +27,7 @@
       <div class="px-4 pt-4 pb-1 label-upper font-bold text-muted flex items-center gap-2">
         <span><%= section[:title] %></span>
         <% if section[:admin] %>
-          <span class="rounded border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-[10px] font-mono text-primary">ADMIN</span>
+          <span class="rounded border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-[10px] font-mono text-primary-ink">ADMIN</span>
         <% end %>
       </div>
 
@@ -92,7 +92,7 @@
     <% if sidebar_admin && sections.any? { |section| section[:admin] } %>
       <div class="px-4 pt-4 pb-1 label-upper font-bold text-muted flex items-center gap-2">
         <span>Geo</span>
-        <span class="rounded border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-[10px] font-mono text-primary">ADMIN</span>
+        <span class="rounded border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-[10px] font-mono text-primary-ink">ADMIN</span>
       </div>
       <%= render "components/geo_signpost", variant: :sidebar, close_action: close_action %>
     <% end %>

data/app/views/studio/emails/_row.html.erb

@@ -85,7 +85,7 @@
     <%= link_to entry.label, admin_email_path(entry.key),
           class: "font-semibold text-heading hover:text-primary underline-offset-2 hover:underline" %>
     <% if entry.marketing? %>
-      <span class="badge bg-primary/10 text-primary border-primary/30 ml-1.5 whitespace-nowrap">Marketing</span>
+      <span class="badge bg-primary/10 text-primary-ink border-primary/30 ml-1.5 whitespace-nowrap">Marketing</span>
     <% end %>
     <% if entry.description.present? %>
       <p class="text-sm text-body mt-0.5 max-w-md"><%= entry.description %></p>

data/app/views/studio/emails/show.html.erb

@@ -103,7 +103,7 @@
     </div>
 
     <div class="flex flex-wrap items-center gap-2 mt-3">
-      <span class="badge <%= @entry.marketing? ? "bg-primary/10 text-primary border-primary/30" : "bg-inset text-muted border-subtle" %> whitespace-nowrap">
+      <span class="badge <%= @entry.marketing? ? "bg-primary/10 text-primary-ink border-primary/30" : "bg-inset text-muted border-subtle" %> whitespace-nowrap">
         <%= @entry.type.to_s.titleize %>
       </span>
       <span class="<%= badge_class %> whitespace-nowrap"><%= badge_label %></span>

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

@@ -124,7 +124,7 @@
     </div>
   <% end %>
   <% chrome_kickoff = capture do %>
-    <span class="inline-flex items-center gap-1 rounded border border-primary/30 bg-primary/10 px-1.5 py-0.5 text-2xs font-semibold uppercase tracking-wide text-primary">kickoff slot</span>
+    <span class="inline-flex items-center gap-1 rounded border border-primary/30 bg-primary/10 px-1.5 py-0.5 text-2xs font-semibold uppercase tracking-wide text-primary-ink">kickoff slot</span>
   <% end %>
   <%
     # Per-column count_class colours (raw classes, the task_stage_count_classes shape),

data/db/migrate/20261010120000_add_stored_in_to_image_caches.rb

@@ -0,0 +1,25 @@
+# Adds image_caches.stored_in: where a row's object lives. nil (every existing
+# row) and "own" mean this app's own bucket; "production" marks a non-production
+# row that REFERENCES production's copy of a seed asset instead of a duplicate
+# in the dev bucket (Studio::ImageCache.reference_or_cache!, ImageCache#url).
+#
+# Nullable with no default, so the add is a catalog-only change on any table
+# size and no existing row is rewritten or changes its URL.
+#
+# image_caches is host-owned; on a host without the table this is a no-op, like
+# AllowNullImageCacheOwner. Studio::HostSchema does not require the column: a
+# host that has not installed this migration keeps working, and every row reads
+# as "own".
+class AddStoredInToImageCaches < ActiveRecord::Migration[7.2]
+  def up
+    return unless table_exists?(:image_caches)
+
+    add_column :image_caches, :stored_in, :string, if_not_exists: true
+  end
+
+  def down
+    return unless table_exists?(:image_caches)
+
+    remove_column :image_caches, :stored_in, if_exists: true
+  end
+end

data/lib/studio/image_cache.rb

@@ -46,21 +46,107 @@ module Studio
     # Idempotent: variants already present in ImageCache are skipped. If
     # nothing is missing, the source is never read.
     def self.cache!(owner:, purpose:, key_prefix:, widths:, source_url: nil, source_path: nil, content_type: "image/png")
-      raise ArgumentError, "either source_url or source_path is required" if source_url.nil? && source_path.nil?
+      ext, requested = prepare!(source_url: source_url, source_path: source_path, content_type: content_type, widths: widths)
 
-      unless ALLOWED_CONTENT_TYPES.include?(content_type)
-        raise UnsupportedContentType, "content_type #{content_type.inspect} not in allowlist (#{ALLOWED_CONTENT_TYPES.join(", ")})"
+      existing = ::ImageCache.where(owner: owner, purpose: purpose).index_by(&:variant)
+      missing  = requested - existing.keys
+      return existing if missing.empty?
+
+      upload_variants!(existing, missing, owner: owner, purpose: purpose, key_prefix: key_prefix, ext: ext,
+                                          source_url: source_url, source_path: source_path, content_type: content_type)
+    end
+
+    # ── SEED ASSETS: REFERENCE PRODUCTION, UPLOAD ONLY WHAT IS NEW ────────────
+    #
+    # cache!'s signature and answer, for SEEDERS. Seed assets live in the
+    # production bucket; a laptop, desk or QA app should point at production's
+    # copy rather than upload a duplicate into the dev bucket. So, outside
+    # production, with Studio.s3_production_public_url set, each missing variant
+    # is first looked for in production by a read-only HEAD
+    # (Studio::S3.production_head) under the key cache! would write:
+    #
+    #   found     an ImageCache row with stored_in "production" is recorded. Its
+    #             #url resolves on the production host. Nothing is uploaded.
+    #   absent    the variant is uploaded to this process's OWN bucket exactly as
+    #             cache! does (stored_in nil = own). A key production lacks
+    #             (kenneth-walker-iii, 2026-10-10) still gets an image.
+    #
+    # The source is fetched only when at least one variant has to be uploaded.
+    # A HEAD that fails for any reason but "not found" raises: a token without
+    # read on production must not quietly turn into a dev-bucket copy of
+    # everything.
+    #
+    # In production, or with s3_production_public_url unset, this IS cache!.
+    # Production never reads the knob, so production apps behave as before.
+    #
+    # Nothing here writes, copies or deletes in the production bucket.
+    def self.reference_or_cache!(owner:, purpose:, key_prefix:, widths:, source_url: nil, source_path: nil,
+                                 content_type: "image/png")
+      unless Studio::S3.production_references?
+        return cache!(owner: owner, purpose: purpose, key_prefix: key_prefix, widths: widths,
+                      source_url: source_url, source_path: source_path, content_type: content_type)
       end
 
-      validate_source_url!(source_url) if source_url
+      unless ::ImageCache.stored_in_column?
+        raise MissingStoredInColumn,
+              "image_caches.stored_in is missing: run `bin/rails studio_engine:install:migrations db:migrate` " \
+              "before referencing production seed assets"
+      end
 
-      ext = EXT_BY_TYPE[content_type]
-      requested = ["original", *widths.map(&:to_s)]
+      ext, requested = prepare!(source_url: source_url, source_path: source_path, content_type: content_type, widths: widths)
 
       existing = ::ImageCache.where(owner: owner, purpose: purpose).index_by(&:variant)
       missing  = requested - existing.keys
       return existing if missing.empty?
 
+      to_upload = missing.reject do |variant|
+        s3_key = variant_key(key_prefix, variant, ext)
+        head = Studio::S3.production_head(key: s3_key)
+        next false if head.nil?
+
+        existing[variant] = ::ImageCache.create!(
+          owner: owner,
+          purpose: purpose,
+          variant: variant,
+          s3_key: s3_key,
+          stored_in: ::ImageCache::PRODUCTION,
+          source_url: source_url,
+          bytes: head.content_length,
+          content_type: head.content_type.to_s.empty? ? content_type : head.content_type
+        )
+        true
+      end
+      return existing if to_upload.empty?
+
+      upload_variants!(existing, to_upload, owner: owner, purpose: purpose, key_prefix: key_prefix, ext: ext,
+                                            source_url: source_url, source_path: source_path, content_type: content_type)
+    end
+
+    class MissingStoredInColumn < StandardError; end
+
+    # The key every variant is written under, by cache! and looked up under by
+    # reference_or_cache!. One definition, so the two can never disagree.
+    def self.variant_key(key_prefix, variant, ext)
+      "#{key_prefix}/#{variant}.#{ext}"
+    end
+
+    def self.prepare!(source_url:, source_path:, content_type:, widths:)
+      raise ArgumentError, "either source_url or source_path is required" if source_url.nil? && source_path.nil?
+
+      unless ALLOWED_CONTENT_TYPES.include?(content_type)
+        raise UnsupportedContentType, "content_type #{content_type.inspect} not in allowlist (#{ALLOWED_CONTENT_TYPES.join(", ")})"
+      end
+
+      validate_source_url!(source_url) if source_url
+
+      [EXT_BY_TYPE[content_type], ["original", *widths.map(&:to_s)]]
+    end
+    private_class_method :prepare!
+
+    # Reads the source once and uploads each of `missing` to this process's own
+    # bucket, recording a row per variant into `existing`, which it returns.
+    def self.upload_variants!(existing, missing, owner:, purpose:, key_prefix:, ext:, source_url:, source_path:,
+                              content_type:)
       require "mini_magick"
 
       body = if source_path
@@ -72,7 +158,6 @@ module Studio
       missing.each do |variant|
         if variant == "original"
           payload = body
-          s3_key  = "#{key_prefix}/original.#{ext}"
         else
           img = MiniMagick::Image.read(body)
           # Cap ImageMagick resources per-invocation to prevent decompression-bomb DoS.
@@ -84,8 +169,8 @@ module Studio
             c.resize "#{variant}x"
           end
           payload = img.to_blob
-          s3_key  = "#{key_prefix}/#{variant}.#{ext}"
         end
+        s3_key = variant_key(key_prefix, variant, ext)
 
         Studio::S3.upload(
           key: s3_key,
@@ -107,6 +192,7 @@ module Studio
 
       existing
     end
+    private_class_method :upload_variants!
 
     # ── THE SSRF GUARD ────────────────────────────────────────────────────────
     #

data/lib/studio/s3.rb

@@ -25,13 +25,18 @@ module Studio
       # is answered as the empty string it means. Tested against a stubbed
       # client only: no live store, R2 included, has been asked.
       def download(key:, max_bytes: nil)
+        read_object(bucket, key, max_bytes)
+      end
+
+      # The GET behind download and production_download.
+      def read_object(target, key, max_bytes)
         # 0 or a negative would build "bytes=0--1", which a store may read as
         # no range at all and answer with the whole object.
         unless max_bytes.nil? || (max_bytes.is_a?(Integer) && max_bytes.positive?)
           raise ArgumentError, "max_bytes must be a positive Integer, got #{max_bytes.inspect}"
         end
 
-        opts = { bucket: bucket, key: full_key(key) }
+        opts = { bucket: target, key: full_key(key) }
         opts[:range] = "bytes=0-#{max_bytes - 1}" if max_bytes
         s3 = client
         # The rescue names an SDK constant, so it wraps only what runs after
@@ -84,10 +89,70 @@ module Studio
       end
 
       def exists?(key:)
-        client.head_object(bucket: bucket, key: full_key(key))
-        true
-      rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
-        false
+        !head(bucket, key).nil?
+      end
+
+      # ── PRODUCTION REFERENCES (read-only) ─────────────────────────────────
+      #
+      # Seed assets live in the PRODUCTION bucket, and a non-production process
+      # references them there instead of uploading its own copy (ImageCache's
+      # stored_in = "production"). Everything below READS production and
+      # nothing writes it: there is no upload, copy or delete that takes the
+      # production bucket, and delete/purge! still refuse a "*-production"
+      # bucket off production (guard_production_bucket!). The dev R2 tokens
+      # hold Item Read on production and Item Write on dev only, so the store
+      # refuses a write even if code here ever tried.
+
+      # The bucket production writes: "#{s3_bucket_prefix}-production" in every
+      # environment. In real production it is `bucket`.
+      def production_bucket
+        prefix = Studio.s3_bucket_prefix
+        raise NotConfigured, "Studio.s3_bucket_prefix not set in config/initializers/studio.rb" if prefix.nil? || prefix.empty?
+
+        "#{prefix}-production"
+      end
+
+      # Whether this process may record a production reference: it is not
+      # production itself (production's own uploads already ARE production's)
+      # and it knows production's public host (Studio.s3_production_public_url).
+      def production_references?
+        !production_environment? && !Studio.s3_production_public_url.to_s.empty?
+      end
+
+      # The public URL of production's copy of `key`. In production it is
+      # exactly url(key:). Elsewhere it is s3_production_public_url plus the
+      # key, under the same s3_key_prefix (the namespace is per app, not per
+      # environment); without that base it RAISES rather than answer with this
+      # environment's host, where the object does not exist.
+      def production_url(key:)
+        return url(key: key) if production_environment?
+
+        base = Studio.s3_production_public_url.to_s
+        if base.empty?
+          raise NotConfigured,
+                "Studio.s3_production_public_url not set: cannot resolve production's copy of #{key.inspect} " \
+                "from a #{environment} process"
+        end
+
+        "#{base.chomp("/")}/#{full_key(key)}"
+      end
+
+      # A read-only HEAD against the production bucket: the object's metadata
+      # (content_length, content_type) when production holds `key`, nil when it
+      # does not. Any other answer (403 from a token without Item Read on
+      # production, a network error) RAISES: a seeder that cannot ask must not
+      # read the silence as "absent" and quietly upload a copy.
+      def production_head(key:)
+        head(production_bucket, key)
+      end
+
+      def production_exists?(key:)
+        !production_head(key: key).nil?
+      end
+
+      # A read-only GET of production's copy, with download's max_bytes rules.
+      def production_download(key:, max_bytes: nil)
+        read_object(production_bucket, key, max_bytes)
       end
 
       # A RECOVERABLE delete: the object moves under trash/ in the same bucket
@@ -235,8 +300,22 @@ module Studio
         @client = nil
       end
 
+      private :read_object
+
       private
 
+      # HEAD of `key` in `target`: the response, or nil when the object is
+      # absent. `target` is resolved by the caller, so an unconfigured app
+      # raises NotConfigured before the rescue below names an SDK constant.
+      def head(target, key)
+        s3 = client
+        begin
+          s3.head_object(bucket: target, key: full_key(key))
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+          nil
+        end
+      end
+
       # WHICH BUCKET HALF THIS APP OWNS. Rails.env alone cannot answer it: no QA app
       # sets RAILS_ENV, so every QA app boots as `production` exactly like real
       # production. QA_ENV is the signal that separates them, and it is the one

data/lib/studio/theme_resolver.rb

@@ -117,6 +117,10 @@ module Studio
         "--color-danger-ink"     => status_ink(danger, surfaces, direction: :lighten),
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :lighten),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :lighten),
+        # The primary role as chip TEXT (`bg-primary/10 text-primary-ink`): the
+        # brand hue, shaded per theme until it clears AA on the surfaces and on
+        # its own tint. --color-primary itself stays the brand colour.
+        "--color-primary-ink"    => status_ink(primary, surfaces, direction: :lighten),
         "--color-accent"         => colors[:accent] || "#F72585"
       }.merge(fill_vars(primary, warning, danger))
     end
@@ -165,6 +169,16 @@ module Studio
     # How strong a status role's tint is where its ink is read on it: the
     # `bg-<role>/10 text-<role>-ink` badge and flash-panel pattern.
     STATUS_TINT = 0.10
+    # Every tint strength a role's ink is read on. The 10% chip, as written and
+    # as an 8-bit alpha channel holds it (26/255, a little stronger), and the
+    # 15% and 20% tints the apps also put an ink on: a selected or "Entered"
+    # badge (`bg-primary/15`), the hub's workflow and verdict chips
+    # (`bg-success/20 text-success-ink`, `bg-warning/20 text-warning-ink`),
+    # turf's signer roster (`bg-danger/15 text-danger-ink`). A stronger tint
+    # sits closer to the ink, so an ink tuned to the 10% chip alone read 3.89:1
+    # on a 20% one (default warning, dark). 0.15 and 0.20 are the stronger of
+    # each written alpha and its 8-bit value (38/255 is weaker, 51/255 equal).
+    TINT_ALPHAS = [STATUS_TINT, (STATUS_TINT * 255).round / 255.0, 0.15, 0.20].freeze
 
     # A status ink lands on the page surfaces AND on its own role's tint over
     # each of them (the `bg-warning/10 text-warning-ink` badge). The tint is
@@ -172,9 +186,28 @@ module Studio
     # to the bare surfaces alone comes out below AA inside its own badge
     # (default theme: warning 3.91:1 dark, success 4.00:1 dark, danger 4.10:1
     # light and 4.18:1 dark). Counting the tints as surfaces closes that.
+    #
+    # The tint is counted at every strength in TINT_ALPHAS. Chromium composites
+    # a 10% fill at 26/255, a little stronger than 0.10, and an ink tuned to
+    # 0.10 alone measured 4.48:1 on the painted pixels (danger, dark, on a
+    # #141516 base).
+    #
+    # Each tint is also counted one unit lighter and one unit darker in every
+    # channel. A browser composites in 8 bits and rounds the fill's share and
+    # the surface's share separately, so a painted tint can sit one unit off
+    # the exact blend: the default danger at 20% over #3C3853 blends to
+    # #5F3A50 and Chromium paints #603B50, which took an ink graded 4.51:1 here
+    # to 4.47:1 on screen. Contrast moves with luminance, and luminance with
+    # each channel, so the two all-channel neighbours bound every rounding.
     def status_ink(role, surfaces, direction:)
-      tints = surfaces.map { |bg| ColorScale.blend(role, bg, STATUS_TINT) }
-      contrast_ink(role, direction: direction, start: 0.0, target: 4.5, against: surfaces + tints)
+      tints = TINT_ALPHAS.flat_map { |alpha| surfaces.map { |bg| ColorScale.blend(role, bg, alpha) } }
+      painted = tints.flat_map { |tint| [tint, nudge(tint, 1), nudge(tint, -1)] }
+      contrast_ink(role, direction: direction, start: 0.0, target: 4.5, against: surfaces + painted)
+    end
+
+    # `hex` with every channel moved `units` (clamped to 0..255).
+    def nudge(hex, units)
+      ColorScale.rgb_to_hex(*ColorScale.hex_to_rgb(hex).map { |c| c + units })
     end
 
     # The lightest shade of `color` that carries a white label at AA: the
@@ -307,6 +340,7 @@ module Studio
         "--color-danger-ink"     => status_ink(danger, surfaces, direction: :darken),
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :darken),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :darken),
+        "--color-primary-ink"    => status_ink(primary, surfaces, direction: :darken),
         "--color-accent"         => colors[:accent] || "#F72585"
       }.merge(fill_vars(primary, warning, danger))
     end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.102.0"
+  VERSION = "0.103.0.rc2"
 end

data/lib/studio.rb

@@ -1079,6 +1079,19 @@ module Studio
   mattr_accessor :s3_secret_access_key, default: nil
   mattr_accessor :s3_public_url,        default: nil
 
+  # SEED ASSETS LIVE IN PRODUCTION. The public base of THIS app's PRODUCTION
+  # bucket (https://assets.turfmonster.media), set in every environment. A
+  # non-production process (a laptop, a desk, a QA app) whose seeders call
+  # Studio::ImageCache.reference_or_cache! records an ImageCache row that
+  # REFERENCES production's copy of an object instead of uploading its own, and
+  # that row's #url resolves on this host. Not a secret, so a literal in
+  # config/initializers/studio.rb is the expected form.
+  #
+  # nil (the default) turns references off: reference_or_cache! is then exactly
+  # cache!, and every row resolves on s3_public_url as it always has. A real
+  # production process ignores it, because its own bucket IS production.
+  mattr_accessor :s3_production_public_url, default: nil
+
   # Knowledge layer — the S3-backed document store + /admin/knowledge browser
   # (Studio::KnowledgeDoc). Routes are opt-in like every route surface.
   # knowledge_agents is the roster of agent slugs the intake UI offers

data/tailwind/studio.tailwind.config.js

@@ -103,6 +103,9 @@ module.exports = {
         'danger-ink':  'var(--color-danger-ink)',
         'warning-ink': 'var(--color-warning-ink)',
         'success-ink': 'var(--color-success-ink)',
+        // The primary role as chip text, derived the same way. text-primary
+        // stays the brand colour for links, icons and large text.
+        'primary-ink': 'var(--color-primary-ink)',
       },
       // The status-role FILLS: badge tints, flash panels, borders. Registered
       // for backgrounds and borders ONLY (not `colors`), so that registering

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.102.0
+  version: 0.103.0.rc2
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -713,6 +713,7 @@ files:
 - db/migrate/20261006120002_ensure_theme_settings_table.rb
 - db/migrate/20261006120003_ensure_image_caches_table.rb
 - db/migrate/20261008120000_add_recording_to_studio_knowledge_docs.rb
+- db/migrate/20261010120000_add_stored_in_to_image_caches.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb