studio-engine 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb273757252724d41962bac1a7c6318c0d04006ff41c1ba29735ad413c0b57fc
-  data.tar.gz: 618a5a39311ac9a316c649a502b44fa6540e8dc70c776fc3c3b2c17455473479
+  metadata.gz: 01f352e62e854f4ec09087aec52716a87ca4ac494e19882e554bb19dd154092c
+  data.tar.gz: 791a21cfc0130503ff5489f43857bde752892facfe7d1ab7e9233dd7535f6ffe
 SHA512:
-  metadata.gz: 9b7bcf2d4dca51566942a2179a6f06e6c4a70293acab99b5a747a76785d9cba69cf51e4992e02410e82e9602f6c317605866ed1bd5b59bbf452954eae5d620aa
-  data.tar.gz: 1136131a5250c8a014edeb8ddd602c23dced903a82b99d3c57eb3bf27dd2394b735c993d08a559ff6132b8ffcdf337a4d6a91d8f4396ef8ab83c7679b7e2c4d7
+  metadata.gz: 52b2b4f48c08972164d73c9ffff6276c242a3baa5a139c32076c698e37232867bb15b4d54bb28333bdd0531e413cb3226be46b03f3445bbf102e40dd6e1878c3
+  data.tar.gz: 2bd861d11c1342bdb0ffec8865f3a2e04665a7883f1bccd9886fd53a5e93936af658b276015592c599497029b133f33ba31a45e9244238e5a1849e7cc41967c9

data/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 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`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## Unreleased
+
+### Added
+
+- **The "at" time stamp — `at_time_tag` + `studio/at_time_script`.** A shared
+  primitive for stamping WHEN something happened, on the READER's clock rather
+  than the app's: `at 3:53p`, gaining a date only when the stamp is not today and
+  the year only when it differs, with a country flag trailing the clock when the
+  reader's timezone is outside the US. The relative phrase moves to the hover
+  title. The server renders the app-timezone form as a no-JS fallback and never
+  renders a flag — it cannot know where the reader is sitting, so only the
+  reader's machine may assert one. Hosts render `studio/at_time_script` once,
+  near the end of the layout body; omitting it degrades to app-timezone stamps
+  rather than breaking. Specimen: `/admin/style` → Tricks → Time stamps; recipe
+  in the README's UI Primitives section.
+
+**Banner aspect ratio is now per-entry.** The new artwork is 3:1 while the shared
+default is 2:1, and turf-monster's eight banners are 2:1. A single global constant
+would letterbox one app's artwork or crop the other's on every upload, so:
+
+```ruby
+Studio::EmailCatalog.register("winnings",
+  default_asset: "emails/winnings.jpg",
+  aspect_ratio: 2.0)   # omit it and you keep the shared default
+```
+
+The page draws each row's thumbnail in that shape, and the upload cropper
+enforces it, so a replacement lands in the same frame as the artwork it replaces.
+`Studio::EmailCatalog.ratio(key)` reads it; `ASPECT_RATIO` remains the fallback.
+
+### Changed
+
+**The two standard emails now ship Mr. McRitchie's real artwork** — "Your Magic
+Link" and "Confirm Email" — replacing the placeholder gradients. Animated, 1800x600,
+with the McRitchie Studio logo. Every app that has not uploaded its own banner
+inherits them.
+
+Shipped **animated at full size on purpose**, with the trade measured rather than
+assumed: a static first frame would have been 24 KB against 3.5 MB, and
+re-encoding smaller made the files LARGER (GIF re-dithers the smooth gradient on
+every frame, so colour reduction and frame-dropping both backfired). Outlook
+desktop renders frame one only — frame one is a complete, legible banner.
+
+### Fixed
+
+**The emails page named the wrong owner for an app's own artwork.**
+`/admin/emails` described ANY registered banner as *"Shared Studio artwork,
+shipped with the engine"*. turf-monster registers its own eight committed
+banners, so its page announced its own artwork as the engine's — the same
+wrong-provenance failure this page exists to end (the page it replaced claimed
+"No image yet" about an email that was visibly sending one).
+
+`Studio::EmailCatalog.source` now answers with four states instead of three:
+
+| State | Means |
+|---|---|
+| `:app` | uploaded on this app's /admin/emails — revertible |
+| `:app_asset` | registered by this app, committed in its own repo |
+| `:engine_default` | the shared artwork that ships in the gem |
+| `:none` | no banner; the email sends without one |
+
+`:default` is gone; it was the value covering the middle two together.
+**`:app` is deliberately unchanged** — turf-monster's suite asserts it on `main`
+and consumer CI runs consumers' default branch.
+
+Origin is recorded at **registration**, not inferred later: by the time the page
+asks, a resolved asset path looks identical whether the file came from the gem
+or from the host. The engine seeds its own two as engine-owned; passing
+`default_asset:` makes that artwork the host's. Relabelling an inherited email
+does NOT claim its picture, and overriding its asset DOES.
+
+Also new: `Studio::EmailCatalog.app_artwork?(key)` — true when the live banner
+belongs to this app either way. The page's summary line counts it, so an app
+whose banners all ship from its own repo no longer reports "all inheriting the
+default artwork".
+
 ## 0.39.0 — 2026-08-11
 
 ### Removed

data/README.md

@@ -155,6 +155,35 @@ privileges while impersonating.
 
 ## UI Primitives
 
+### The "at" time stamp — `at_time_tag`
+
+Stamps WHEN something happened, on the reader's own clock: `at 3:53p`, gaining a
+date only when the stamp is not today and the year only when it differs. A
+country flag trails the clock when the reader's timezone is outside the US, and
+inside the US there is no flag at all — it carries signal only because it is
+unusual. The relative phrase ("7 minutes ago") moves to the hover title.
+
+Render the re-stamper **once per page, near the end of the layout body**, then
+use the helper anywhere:
+
+```erb
+<%# near the end of <body>, once %>
+<%= render "studio/at_time_script" %>
+
+<%# anywhere %>
+<%= at_time_tag(release.shipped_at) %>
+<%= at_time_tag(task.created_at, prefix: nil) %>
+```
+
+**Near the END of the body matters.** The script's first pass runs synchronously
+as it parses, so rendering it in `head` finds zero stamps on that pass and leaves
+them until the next one.
+
+The server renders the app-timezone form as a no-JS fallback and never renders a
+flag — it cannot know where the reader is sitting, so only the reader's machine
+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.
+
 ### Smooth-load header pin — `.vt-pinned-header`
 
 When `Studio.smooth_load` is on, put `vt-pinned-header` on the app's sticky
@@ -376,11 +405,18 @@ relabeling `magic_link` does not reorder the page or drop its default artwork.
 
 ```
 Studio::EmailCatalog.resolved_url(:magic_link)
-  1. this app's ImageCache row  (its own S3 bucket)   -> app-owned override
-  2. the engine's default gem asset                   -> inherited default
+  1. this app's ImageCache row  (its own S3 bucket)   -> uploaded here
+  2. the registered default_asset                     -> a committed file
   3. nil                                              -> sends bannerless
 ```
 
+`source(key)` says WHOSE the live banner is — `:app` (uploaded here, revertible),
+`:app_asset` (registered by this app, committed in its repo), `:engine_default`
+(the shared artwork in the gem), or `:none`. The origin is recorded when the
+email is registered, because a resolved asset path looks identical either way by
+the time the page asks. Passing `default_asset:` makes that artwork the host's;
+relabelling an inherited email leaves it the engine's.
+
 Note the method: **`resolved_url` walks all three layers; `url` returns only
 layer 1** (this app's own image, or nil). That split is deliberate — it keeps
 every caller written before the registry behaving exactly as it did. A mailer

data/app/helpers/studio/at_time_helper.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Studio
+  # The "at" format — the shared primitive for stamping WHEN something happened.
+  #
+  # A relative stamp ("Shipped less than a minute ago") answers *how long ago* and
+  # then stops. It never tells the reader what the clock said, so it cannot be
+  # placed against the rest of a day. The "at" format answers the other question,
+  # and it answers it in the reader's own time:
+  #
+  #   · The clock is 12-hour with a single-letter meridiem — "3:53p".
+  #   · The date appears ONLY when the stamp is not today. Something that happened
+  #     minutes ago needs no date; last week's is ambiguous without it. The year
+  #     joins only when it differs, so "Aug 10, 3:53p" stays short all year.
+  #   · A country flag TRAILS the clock when the reader's timezone sits outside the
+  #     US. Inside the US there is no flag at all — the flag carries signal only
+  #     because it is unusual, and one that fired on every stamp would carry none.
+  #   · The relative phrase is not thrown away; it moves to the hover title, beside
+  #     the full local stamp and its zone name.
+  #
+  # WHO OWNS WHAT. The server renders the app-timezone form as the pre-hydration
+  # and no-JS fallback, and never renders a flag — it cannot know where the reader
+  # is sitting. `studio/_at_time_script` re-stamps the clock to the VIEWER's local
+  # time and adds the flag from the browser's IANA zone. That split is the whole
+  # design: the flag is a fact about the reader, so only the reader's machine may
+  # assert it.
+  #
+  # HOSTS: render `studio/at_time_script` ONCE per page, near the END of the layout
+  # body (its first pass runs synchronously, so rendering it in head finds zero
+  # stamps), then use `at_time_tag` anywhere. Recipe in the README's UI Primitives
+  # section. Without the script the stamps still render — in the app's timezone,
+  # with no flag — so a host that forgets it degrades to the old behavior rather
+  # than breaking. Specimen: /admin/style → Tricks → Time stamps.
+  module AtTimeHelper
+    MONTH_DAY = "%b %-d"
+
+    # "3:53p" / "11:07a" — 12-hour clock, no leading zero, single-letter meridiem,
+    # no space. Zones the time into the app zone first, so a bare UTC timestamp and
+    # an already-zoned one render the same. nil-safe.
+    def at_clock(time)
+      return nil if time.blank?
+
+      local = time.in_time_zone
+      "#{local.strftime('%-l:%M')}#{local.hour < 12 ? 'a' : 'p'}"
+    end
+
+    # The date half of an "at" stamp, or nil when the stamp falls on `now`'s date —
+    # today's stamps carry no date. "Aug 10" within the current year, "Aug 10 2025"
+    # outside it. `now` is injectable so the boundary is testable.
+    def at_date(time, now: Time.current)
+      return nil if time.blank?
+
+      local = time.in_time_zone
+      today = now.in_time_zone
+      return nil if local.to_date == today.to_date
+
+      return local.strftime(MONTH_DAY) if local.year == today.year
+
+      "#{local.strftime(MONTH_DAY)} #{local.year}"
+    end
+
+    # The visible text of an "at" stamp: "3:53p" today, "Aug 10, 3:53p" otherwise.
+    # The JS half builds the identical string from the viewer's clock — change one
+    # and change the other, or the value flickers on hydration.
+    def at_stamp_text(time, now: Time.current)
+      return nil if time.blank?
+
+      date = at_date(time, now: now)
+      date ? "#{date}, #{at_clock(time)}" : at_clock(time)
+    end
+
+    # The hover title: the relative phrase this format replaced, then the full local
+    # stamp with its zone. Server-side that zone is the app's; the script rewrites
+    # the whole title in the viewer's.
+    #
+    # `now` is measured against, not decoration: time_ago_in_words reads the real
+    # clock, so a caller that injected `now` used to get a title from a DIFFERENT
+    # moment than the label right beside it.
+    def at_stamp_title(time, now: Time.current)
+      return nil if time.blank?
+
+      local = time.in_time_zone
+      "#{distance_of_time_in_words(local, now)} ago · #{local.strftime('%a, %b %-d, %Y, %-l:%M %p %Z')}"
+    end
+
+    # The primitive itself. Renders a <time> carrying the epoch the script re-stamps
+    # from, the text slot, and the (server-side empty) flag slot that trails it.
+    #
+    #   at_time_tag(release.shipped_at)              => "at 3:53p"
+    #   at_time_tag(task.created_at, prefix: nil)    => "3:53p"
+    #
+    # nil for a blank time, so a caller can `<%= at_time_tag(t) %>` unguarded.
+    def at_time_tag(time, prefix: "at", now: Time.current, css_class: nil)
+      return nil if time.blank?
+
+      # One reading of "no prefix" for BOTH halves. `.presence` folds nil, "" and
+      # false to nil, and the data attribute is then omitted rather than carrying a
+      # stringified value — `prefix: false` used to render bare server-side and
+      # hydrate to "false 3:53p", because the client trusts the attribute it is given.
+      prefix = prefix.presence
+      local = time.in_time_zone
+      text = at_stamp_text(local, now: now)
+      text = "#{prefix} #{text}" if prefix
+
+      tag.time(datetime: local.iso8601,
+               title: at_stamp_title(local, now: now),
+               class: ["whitespace-nowrap", css_class].compact.join(" "),
+               data: { at_stamp: "", at_epoch: local.to_i, at_prefix: prefix }) do
+        # No whitespace between the two slots: the gap is `ml-2` on the flag, which
+        # collapses with the flag itself when the reader is inside the US.
+        safe_join([
+          tag.span(text, data: { at_text: "" }),
+          tag.span("", class: "ml-2", hidden: true, data: { at_flag: "" })
+        ])
+      end
+    end
+  end
+end

data/app/services/studio/email_catalog.rb

@@ -74,11 +74,25 @@ module Studio
     #   type          — :transactional or :marketing.
     #   preview       — callable returning a Mail, or nil.
     Entry = Struct.new(:key, :label, :description, :default_asset, :type, :preview,
-                       keyword_init: true) do
+                       :default_origin, :aspect_ratio, keyword_init: true) do
       def to_s = key
       def previewable? = preview.respond_to?(:call)
       # nil-safe: an Entry built directly (the STANDARD seed) may carry no type.
       def marketing? = type.to_s == "marketing"
+
+      # WHOSE artwork default_asset names. Recorded at registration rather than
+      # inferred later: by the time the page asks, a resolved asset path looks
+      # identical whether the file came from the gem or from the host, and
+      # guessing from the path is exactly the wrong-answer machine this exists
+      # to remove. The engine seeds its own two as :engine; anything a host
+      # passes default_asset for is that host's own.
+      def engine_artwork? = default_origin.to_s != "app"
+
+      # The shape of THIS email's banner — the box the page draws and the ratio
+      # the upload cropper enforces. Per-entry because the engine's own artwork
+      # is 3:1 while turf-monster's eight banners are 2:1; one global constant
+      # would letterbox one app's art and crop the other's on every upload.
+      def ratio = (aspect_ratio || ASPECT_RATIO).to_f
     end
 
     # The emails EVERY Studio app sends. Pre-registered, so a host inherits both
@@ -88,13 +102,15 @@ module Studio
         key: "magic_link",
         label: "Magic-link sign-in",
         description: "Passwordless sign-in link. Sent whenever someone asks to sign in by email.",
-        default_asset: "emails/magic-link.png"
+        default_asset: "emails/magic-link.gif",
+        aspect_ratio: 3.0
       },
       {
         key: "email_change_confirmation",
         label: "Email change confirmation",
         description: "Confirms a new address before the change takes effect.",
-        default_asset: "emails/email-change-confirmation.png"
+        default_asset: "emails/email-change-confirmation.gif",
+        aspect_ratio: 3.0
       }
     ].freeze
 
@@ -113,7 +129,8 @@ module Studio
     # Every keyword is OPTIONAL and omitting one on a re-register KEEPS the
     # existing value — that is what lets a host relabel an inherited email, or
     # attach a preview builder to it, without restating its artwork.
-    def register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: nil)
+    def register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: nil,
+                 aspect_ratio: nil)
       key = key.to_s
       existing = registry[key]
       registry[key] = Entry.new(
@@ -122,7 +139,13 @@ module Studio
         description: description || existing&.description,
         default_asset: default_asset.nil? ? existing&.default_asset : default_asset.presence,
         type: normalize_type(type || existing&.type),
-        preview: preview || existing&.preview
+        preview: preview || existing&.preview,
+        # Passing artwork here makes it THIS APP's artwork — that is the only
+        # moment anyone can know. Omitting it keeps whatever the entry already
+        # had, so a host relabelling an inherited email does not accidentally
+        # claim the engine's picture as its own.
+        default_origin: default_asset.nil? ? (existing&.default_origin || :engine) : :app,
+        aspect_ratio: aspect_ratio || existing&.aspect_ratio
       )
       key
     end
@@ -177,23 +200,45 @@ module Studio
     # symbol, not nil) and every reader can trust the shape.
     def registry
       @registry ||= STANDARD.each_with_object({}) do |attrs, out|
-        out[attrs[:key]] = Entry.new(**attrs, type: normalize_type(attrs[:type]), preview: attrs[:preview])
+        out[attrs[:key]] = Entry.new(**attrs, type: normalize_type(attrs[:type]),
+                                     preview: attrs[:preview], default_origin: :engine,
+                                     aspect_ratio: attrs[:aspect_ratio])
       end
     end
 
     # --- Resolution --------------------------------------------------------
 
-    # Where the live banner for this email comes from:
-    #   :app     — this app uploaded its own (ImageCache row in its bucket)
-    #   :default — the inherited engine default (gem asset)
-    #   :none    — no image at all; the email sends bannerless
+    # Where the live banner for this email actually comes from:
+    #
+    #   :app            — uploaded on this app's /admin/emails (ImageCache row
+    #                     in this app's bucket). Revertible.
+    #   :app_asset      — registered by this app, committed in its own repo.
+    #   :engine_default — the shared artwork that ships in the gem.
+    #   :none           — no image at all; the email sends bannerless.
+    #
+    # `:default` USED to cover the middle two together, and the page said
+    # "Shared Studio artwork, shipped with the engine" for both — so
+    # turf-monster's own eight banners were announced as the engine's. Telling
+    # the operator the wrong provenance is the same failure this page was built
+    # to end (the page it replaced claimed "No image yet" about an email that
+    # was visibly sending one).
+    #
+    # `:app` is deliberately unchanged: turf-monster's suite on `main` asserts
+    # it, and consumer CI runs consumers' default branch.
     def source(key)
       return :app if record(key)
-      return :default if default_asset_path(key)
+      return :none unless default_asset_path(key)
 
-      :none
+      entry(key)&.engine_artwork? ? :engine_default : :app_asset
     end
 
+    # True when the live banner belongs to this app either way — uploaded here
+    # or committed here. What the page's summary line counts.
+    def app_artwork?(key) = %i[app app_asset].include?(source(key))
+
+    # This email's banner shape, falling back to the shared default.
+    def ratio(key) = entry(key)&.ratio || ASPECT_RATIO
+
     def app_owned?(key) = source(key) == :app
 
     # --- Preview -----------------------------------------------------------

data/app/views/studio/_at_time_script.html.erb

@@ -0,0 +1,253 @@
+<%# The client half of the "at" format (Studio::AtTimeHelper). The server renders
+    every [data-at-stamp] in the APP timezone with no flag, because it cannot know
+    where the reader is sitting; this re-stamps each one to the VIEWER's local clock
+    and appends the country flag when that viewer's IANA zone is outside the US.
+
+    HOSTS: the adoption recipe lives in the README's UI Primitives section. It is
+    deliberately NOT repeated here — the first version of this comment carried the
+    render snippet, and an ERB comment ends at the first close-tag whatever it sits
+    inside, so the comment terminated mid-sentence and the remaining prose rendered
+    as page text. That leaked prose contained a script open tag, which swallowed the
+    real one: the re-stamper never executed, on every page of every host that
+    followed the recipe. Keep this comment free of close-tag characters and of tag
+    names spelled inside angle brackets.
+
+    Render it once per page, near the end of the layout body. Near the END matters:
+    the first pass runs synchronously as this script parses, so a host that renders
+    it in head finds zero stamps on that pass and waits for the next one. Cloning it
+    into an Alpine template or a morphed card would re-run it or never run it. It is
+    self-guarded, so a second render is a no-op.
+
+    It re-queries the DOM on every pass — on load, after Turbo navigations and
+    stream renders, and on a slow interval — so a card swapped in by a broadcast is
+    picked up with no re-wiring, and the relative phrase in the hover title never
+    goes stale in a tab left open.
+
+    clock() and dateLabel() MUST render the same strings as
+    Studio::AtTimeHelper#at_clock and #at_date, or the value visibly flickers when
+    hydration overwrites the server's fallback. %>
+<script>
+  (function () {
+    if (window.__atTimeFmt) return;
+    window.__atTimeFmt = true;
+
+    // Zones inside the United States — the 50 states, DC, and the territories.
+    // Membership here means NO FLAG: the flag is a signal, and one that fired on
+    // every stamp would carry none.
+    //
+    // BOTH SPELLINGS OF INDIANA AND KENTUCKY ARE MEMBERS, AND THAT IS NOT
+    // REDUNDANCY. A browser does not hand back the tzdb id it was given — it hands
+    // back the CLDR-canonical one, and the engines DISAGREE about which that is:
+    // Chromium and WebKit report America/Indianapolis and America/Louisville, while
+    // Firefox reports America/Indiana/Indianapolis and America/Kentucky/Louisville.
+    // The short forms match no US_PREFIXES entry and carry only two path segments,
+    // so the parent fallback in zoneFlag() never fires for them either — which is
+    // how Chrome and Safari readers in Indianapolis and Louisville were shown the
+    // Americas globe while Firefox readers beside them saw the correct bare clock.
+    // Delete either spelling and one engine's readers break. (Reached through
+    // US/East-Indiana and America/Fort_Wayne too; both canonicalize to
+    // America/Indianapolis.)
+    var US_ZONES = ("America/New_York America/Detroit America/Chicago America/Menominee " +
+      "America/Denver America/Boise America/Phoenix America/Los_Angeles America/Anchorage " +
+      "America/Juneau America/Sitka America/Metlakatla America/Yakutat America/Nome " +
+      "America/Adak Pacific/Honolulu America/Puerto_Rico America/St_Thomas Pacific/Guam " +
+      "Pacific/Saipan Pacific/Pago_Pago Pacific/Midway " +
+      "America/Indianapolis America/Louisville").split(" ");
+
+    // Zone families that resolve to the US without listing every member. The
+    // Indiana/Kentucky entries are what Firefox needs; the short aliases above are
+    // what Chromium and WebKit need. `US/` matches nothing in any engine shipping
+    // today (every US/* id canonicalizes away before it is reported) — it is kept
+    // as a cheap floor for an engine that does not canonicalize, not because it is
+    // known to fire.
+    var US_PREFIXES = ["US/", "America/Indiana/", "America/Kentucky/", "America/North_Dakota/"];
+
+    // IANA zone → ISO 3166-1 alpha-2, grouped by country so the table reads. Not
+    // exhaustive by design: an unlisted zone outside the US falls back to a
+    // hemisphere globe rather than guessing a country wrong (see zoneFlag).
+    var COUNTRY_ZONES = {
+      GB: "Europe/London", IE: "Europe/Dublin", FR: "Europe/Paris", ES: "Europe/Madrid",
+      PT: "Europe/Lisbon Atlantic/Azores Atlantic/Madeira", DE: "Europe/Berlin Europe/Busingen",
+      IT: "Europe/Rome", NL: "Europe/Amsterdam", BE: "Europe/Brussels", LU: "Europe/Luxembourg",
+      CH: "Europe/Zurich", AT: "Europe/Vienna", DK: "Europe/Copenhagen", NO: "Europe/Oslo",
+      SE: "Europe/Stockholm", FI: "Europe/Helsinki", IS: "Atlantic/Reykjavik", PL: "Europe/Warsaw",
+      CZ: "Europe/Prague", SK: "Europe/Bratislava", HU: "Europe/Budapest", RO: "Europe/Bucharest",
+      BG: "Europe/Sofia", GR: "Europe/Athens", TR: "Europe/Istanbul", UA: "Europe/Kyiv Europe/Kiev",
+      RU: "Europe/Moscow Europe/Kaliningrad Asia/Yekaterinburg Asia/Novosibirsk Asia/Vladivostok",
+      HR: "Europe/Zagreb", RS: "Europe/Belgrade", SI: "Europe/Ljubljana", EE: "Europe/Tallinn",
+      LV: "Europe/Riga", LT: "Europe/Vilnius", MT: "Europe/Malta", CY: "Asia/Nicosia",
+      BY: "Europe/Minsk", MD: "Europe/Chisinau", AL: "Europe/Tirane", BA: "Europe/Sarajevo",
+      MK: "Europe/Skopje", ME: "Europe/Podgorica", MC: "Europe/Monaco", AD: "Europe/Andorra",
+      GI: "Europe/Gibraltar",
+
+      CA: "America/Toronto America/Vancouver America/Edmonton America/Winnipeg America/Halifax " +
+          "America/St_Johns America/Regina America/Montreal",
+      MX: "America/Mexico_City America/Tijuana America/Monterrey America/Cancun " +
+          "America/Chihuahua America/Mazatlan",
+      BR: "America/Sao_Paulo America/Bahia America/Fortaleza America/Recife America/Manaus " +
+          "America/Belem",
+      AR: "America/Argentina America/Buenos_Aires", CL: "America/Santiago", CO: "America/Bogota",
+      PE: "America/Lima", VE: "America/Caracas", EC: "America/Guayaquil", UY: "America/Montevideo",
+      PY: "America/Asuncion", BO: "America/La_Paz", CR: "America/Costa_Rica", PA: "America/Panama",
+      GT: "America/Guatemala", SV: "America/El_Salvador", HN: "America/Tegucigalpa",
+      NI: "America/Managua", BZ: "America/Belize", CU: "America/Havana", DO: "America/Santo_Domingo",
+      JM: "America/Jamaica", HT: "America/Port-au-Prince", BS: "America/Nassau",
+      BB: "America/Barbados", TT: "America/Port_of_Spain", BM: "Atlantic/Bermuda",
+
+      JP: "Asia/Tokyo", CN: "Asia/Shanghai Asia/Chongqing Asia/Urumqi", HK: "Asia/Hong_Kong",
+      MO: "Asia/Macau", TW: "Asia/Taipei", KR: "Asia/Seoul", KP: "Asia/Pyongyang",
+      SG: "Asia/Singapore", MY: "Asia/Kuala_Lumpur Asia/Kuching",
+      ID: "Asia/Jakarta Asia/Makassar Asia/Jayapura", TH: "Asia/Bangkok",
+      VN: "Asia/Ho_Chi_Minh Asia/Saigon", PH: "Asia/Manila", IN: "Asia/Kolkata Asia/Calcutta",
+      PK: "Asia/Karachi", BD: "Asia/Dhaka", LK: "Asia/Colombo", NP: "Asia/Kathmandu",
+      MM: "Asia/Yangon", KH: "Asia/Phnom_Penh", LA: "Asia/Vientiane", MN: "Asia/Ulaanbaatar",
+      KZ: "Asia/Almaty", UZ: "Asia/Tashkent", AZ: "Asia/Baku", GE: "Asia/Tbilisi",
+      AM: "Asia/Yerevan", IL: "Asia/Jerusalem Asia/Tel_Aviv", PS: "Asia/Gaza Asia/Hebron",
+      LB: "Asia/Beirut", JO: "Asia/Amman", SY: "Asia/Damascus", IQ: "Asia/Baghdad",
+      IR: "Asia/Tehran", SA: "Asia/Riyadh", AE: "Asia/Dubai", QA: "Asia/Qatar", KW: "Asia/Kuwait",
+      BH: "Asia/Bahrain", OM: "Asia/Muscat", YE: "Asia/Aden", AF: "Asia/Kabul",
+
+      EG: "Africa/Cairo", MA: "Africa/Casablanca", DZ: "Africa/Algiers", TN: "Africa/Tunis",
+      LY: "Africa/Tripoli", NG: "Africa/Lagos", GH: "Africa/Accra", CI: "Africa/Abidjan",
+      SN: "Africa/Dakar", KE: "Africa/Nairobi", ET: "Africa/Addis_Ababa",
+      TZ: "Africa/Dar_es_Salaam", UG: "Africa/Kampala", ZA: "Africa/Johannesburg",
+      NA: "Africa/Windhoek", ZW: "Africa/Harare", ZM: "Africa/Lusaka", MZ: "Africa/Maputo",
+      AO: "Africa/Luanda", CD: "Africa/Kinshasa Africa/Lubumbashi", CM: "Africa/Douala",
+      RW: "Africa/Kigali", MU: "Indian/Mauritius", MG: "Indian/Antananarivo",
+
+      AU: "Australia/Sydney Australia/Melbourne Australia/Brisbane Australia/Perth " +
+          "Australia/Adelaide Australia/Darwin Australia/Hobart Australia/Canberra",
+      NZ: "Pacific/Auckland", FJ: "Pacific/Fiji", PG: "Pacific/Port_Moresby",
+      NC: "Pacific/Noumea", PF: "Pacific/Tahiti", TO: "Pacific/Tongatapu", WS: "Pacific/Apia",
+      VU: "Pacific/Efate", SB: "Pacific/Guadalcanal"
+    };
+
+    var ZONE_COUNTRY = {};
+    Object.keys(COUNTRY_ZONES).forEach(function (cc) {
+      COUNTRY_ZONES[cc].split(" ").forEach(function (zone) { ZONE_COUNTRY[zone] = cc; });
+    });
+
+    // A flag emoji is just its country code in regional-indicator code points, so
+    // the table above only has to carry two letters per country.
+    function flagFor(cc) {
+      return cc.split("").map(function (ch) {
+        return String.fromCodePoint(127397 + ch.charCodeAt(0));
+      }).join("");
+    }
+
+    function isUS(zone) {
+      if (US_ZONES.indexOf(zone) !== -1) return true;
+      return US_PREFIXES.some(function (prefix) { return zone.indexOf(prefix) === 0; });
+    }
+
+    function zoneFlag(zone) {
+      if (!zone || isUS(zone)) return "";
+      // A machine pinned to UTC/GMT is in no country; say "somewhere else" rather
+      // than invent one.
+      if (zone === "UTC" || zone === "GMT" || zone.indexOf("Etc/") === 0) return "🌐";
+
+      var cc = ZONE_COUNTRY[zone];
+      if (!cc) {
+        // Sub-zone families (America/Argentina/Buenos_Aires) resolve on their
+        // parent before giving up.
+        var parts = zone.split("/");
+        if (parts.length > 2) cc = ZONE_COUNTRY[parts[0] + "/" + parts[1]];
+      }
+      if (cc) return flagFor(cc);
+
+      var region = zone.split("/")[0];
+      if (region === "Europe" || region === "Africa" || region === "Atlantic") return "🌍";
+      if (region === "America") return "🌎";
+      return "🌏";
+    }
+
+    var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+    // Mirrors AtTimeHelper#at_clock.
+    function clock(d) {
+      var h = d.getHours(), m = d.getMinutes(), ap = h < 12 ? "a" : "p";
+      h = h % 12; if (h === 0) h = 12;
+      return h + ":" + String(m).padStart(2, "0") + ap;
+    }
+
+    // Mirrors AtTimeHelper#at_date — null on today, the year only when it differs.
+    function dateLabel(d, now) {
+      if (d.toDateString() === now.toDateString()) return null;
+      var label = MONTHS[d.getMonth()] + " " + d.getDate();
+      return d.getFullYear() === now.getFullYear() ? label : label + " " + d.getFullYear();
+    }
+
+    // Mirrors time_ago_in_words closely enough that hydration does not visibly
+    // rewrite the hover title. It must keep climbing past months into YEARS:
+    // time_ago_in_words does, so capping here made a year-old stamp read "about 12
+    // months ago" on the server and something else after hydration — visible on the
+    // style guide's own 1.year.ago specimen.
+    function relative(secs) {
+      if (secs < 60) return "less than a minute ago";
+      var m = Math.floor(secs / 60);
+      if (m < 60) return m === 1 ? "1 minute ago" : m + " minutes ago";
+      var h = Math.floor(m / 60);
+      if (h < 24) return h === 1 ? "about 1 hour ago" : "about " + h + " hours ago";
+      var days = Math.floor(h / 24);
+      if (days < 30) return days === 1 ? "1 day ago" : days + " days ago";
+      var months = Math.floor(days / 30);
+      if (months < 12) return months === 1 ? "about 1 month ago" : "about " + months + " months ago";
+      var years = Math.floor(days / 365);
+      return years === 1 ? "about 1 year ago" : "about " + years + " years ago";
+    }
+
+    function fullStamp(d) {
+      return d.toLocaleString([], {
+        weekday: "short", month: "short", day: "numeric", year: "numeric",
+        hour: "numeric", minute: "2-digit", timeZoneName: "short"
+      });
+    }
+
+    function viewerZone() {
+      try {
+        return (Intl.DateTimeFormat().resolvedOptions().timeZone) || "";
+      } catch (e) {
+        return "";
+      }
+    }
+
+    function stamp() {
+      var now = new Date();
+      var zone = viewerZone();
+      var flag = zoneFlag(zone);
+
+      document.querySelectorAll("[data-at-stamp]").forEach(function (el) {
+        var epoch = parseInt(el.dataset.atEpoch || "0", 10);
+        if (!epoch) return;
+        var d = new Date(epoch * 1000);
+
+        var textEl = el.querySelector("[data-at-text]");
+        if (textEl) {
+          var date = dateLabel(d, now);
+          var label = date ? date + ", " + clock(d) : clock(d);
+          var prefix = el.dataset.atPrefix;
+          textEl.textContent = prefix ? prefix + " " + label : label;
+        }
+
+        var flagEl = el.querySelector("[data-at-flag]");
+        if (flagEl) {
+          flagEl.textContent = flag;
+          flagEl.hidden = !flag;
+          if (flag) flagEl.title = zone;
+        }
+
+        el.title = relative(Math.max(0, Math.floor((now - d) / 1000))) + " · " + fullStamp(d);
+        el.dataset.atZone = zone;
+      });
+    }
+
+    stamp();
+    document.addEventListener("turbo:load", stamp);
+    document.addEventListener("turbo:render", stamp);
+    // A stream render swaps nodes in AFTER the event fires, so re-stamp on the
+    // next tick rather than against the outgoing DOM.
+    document.addEventListener("turbo:before-stream-render", function () { setTimeout(stamp, 0); });
+    setInterval(stamp, 30000);
+  })();
+</script>

data/app/views/studio/email_images/index.html.erb

@@ -38,7 +38,11 @@
           sending a banner from a committed repo asset. Even on its way out it
           should tell the truth about what ships. %>
       <% current_url = Studio::EmailCatalog.preview_url(variant) %>
-      <% inherited = current_url.present? && Studio::EmailCatalog.source(variant) == :default %>
+      <%# NOT `== :default` — that value split into :app_asset / :engine_default.
+          Comparing against a value nothing returns would silently never show
+          this note again. Anything that is not an upload is still inherited
+          from a file, which is all this retiring page needs to say. %>
+      <% inherited = current_url.present? && Studio::EmailCatalog.source(variant) != :app %>
       <section class="rounded-xl border border-subtle p-5">
         <h2 class="font-semibold mb-3"><%= label %></h2>
 

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

@@ -1,4 +1,4 @@
-<%# locals: (entry:, uploads_available:, aspect:, max_width:)
+<%# locals: (entry:, uploads_available:, max_width:)
     One registered email: its live banner, its name, and where that banner comes
     from. The whole row is the imageUploadHost x-data so the thumbnail, the Edit
     button, and the hidden multipart form the cropper submits all sit together —
@@ -11,14 +11,21 @@
 
   # `badge` is a shape-only utility in engine.css — the state color comes from
   # theme-token utilities so it follows each app's palette in light and dark.
+  #
+  # Four states, because three of them used to read as one. An app that ships
+  # its own committed artwork was told that artwork "ships with the engine",
+  # which is the wrong answer to the only question this column exists to answer.
   badge_class, badge_label, badge_note =
     case source
     when :app
-      ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s own",
-       "Uploaded here — this app owns it."]
-    when :default
-      ["badge bg-inset text-muted border-subtle", "Inherited default",
-       "Shared Studio artwork, shipped with the engine."]
+      ["badge bg-success/10 text-success border-success/30", "Uploaded here",
+       "Stored for #{Studio.app_name} — this upload is what ships."]
+    when :app_asset
+      ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s artwork",
+       "Committed in this app's own assets. Upload to replace it."]
+    when :engine_default
+      ["badge bg-inset text-muted border-subtle", "Studio default",
+       "Shared artwork that ships with the engine. Upload to make it #{Studio.app_name}'s."]
     else
       ["badge bg-warning/10 text-warning border-warning/30", "No image",
        "This email sends without a banner."]
@@ -32,7 +39,7 @@
     <% if uploads_available %>
       x-data="imageUploadHost({
         store: 'emailModals',
-        aspectRatio: <%= aspect %>,
+        aspectRatio: <%= entry.ratio %>,
         maxWidth: <%= max_width %>,
         transparent: false,
         filename: '<%= entry.key %>.png',
@@ -46,7 +53,7 @@
 
   <td class="px-4 py-4">
     <div class="rounded-lg overflow-hidden border border-subtle w-40"
-         style="aspect-ratio: <%= aspect %>; background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));">
+         style="aspect-ratio: <%= entry.ratio %>; background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));">
       <% if banner_url %>
         <%= image_tag banner_url, class: "w-full h-full object-cover",
               alt: "#{entry.label} email banner", loading: "lazy" %>

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

@@ -20,9 +20,12 @@
      partial in this non-isolated engine. %>
 <% content_for(:title) { "Emails" } %>
 <%
-  aspect     = Studio::EmailCatalog::ASPECT_RATIO
   max_width  = Studio::EmailCatalog::MAX_WIDTH
-  app_owned  = @entries.count { |entry| Studio::EmailCatalog.source(entry.key) == :app }
+  # Counts the app's OWN artwork either way — uploaded here or committed in this
+  # app's assets. Counting only uploads made turf-monster, whose eight banners
+  # all ship from its own repo, report "all inheriting the default artwork".
+  app_artwork = @entries.count { |entry| Studio::EmailCatalog.app_artwork?(entry.key) }
+  bannerless  = @entries.count { |entry| Studio::EmailCatalog.source(entry.key) == :none }
 %>
 <div class="max-w-5xl mx-auto px-4 pb-16">
   <header class="space-y-2 pt-8 pb-6">
@@ -30,12 +33,23 @@
     <h1 class="text-3xl font-bold text-heading">Emails</h1>
     <p class="text-body max-w-2xl">
       Every transactional email <%= Studio.app_name %> sends, and the banner that
-      rides at the top of it. Each one starts on the shared Studio artwork; upload
-      your own and it belongs to this app from then on.
+      rides at the top of it. An email starts on the shared Studio artwork, or on
+      artwork this app registered itself; upload here and the image belongs to
+      <%= Studio.app_name %> from then on.
     </p>
     <p class="text-sm text-muted">
       <%= pluralize(@entries.size, "email") %> registered &middot;
-      <%= app_owned.zero? ? "all inheriting the default artwork" : "#{app_owned} with #{Studio.app_name}'s own artwork" %>
+      <%
+        summary =
+          if app_artwork == @entries.size && @entries.any?
+            "all on #{Studio.app_name}'s own artwork"
+          elsif app_artwork.zero?
+            bannerless == @entries.size && @entries.any? ? "none have a banner yet" : "all on the shared Studio artwork"
+          else
+            "#{app_artwork} on #{Studio.app_name}'s own artwork"
+          end
+      %>
+      <%= summary %>
     </p>
   </header>
 
@@ -77,7 +91,7 @@
           <% @entries.each do |entry| %>
             <%= render "studio/emails/row", entry: entry,
                   uploads_available: @uploads_available,
-                  aspect: aspect, max_width: max_width %>
+                  max_width: max_width %>
           <% end %>
         </tbody>
       </table>
@@ -86,8 +100,9 @@
 
   <p class="text-xs text-muted mt-4">
     Banners render full-bleed at 600px wide inside the email card. The crop is
-    fixed at <%= aspect.to_i %>:1 and saved at up to <%= max_width %>px, which is
-    retina-sharp in an inbox without tripping a clipping limit.
+    saved at up to <%= max_width %>px, which is retina-sharp in an inbox. Each
+    email crops to the shape of its own banner, so a replacement lands in the
+    same frame as the artwork it is replacing.
     <% if @entries.any? { |entry| Studio::EmailCatalog.source(entry.key) == :none } %>
       An email with no image sends bannerless — the card still renders.
     <% end %>

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

@@ -9,12 +9,13 @@
 <%
   source     = Studio::EmailCatalog.source(@entry.key)
   banner_url = Studio::EmailCatalog.preview_url(@entry.key)
-  aspect     = Studio::EmailCatalog::ASPECT_RATIO
+  aspect     = @entry.ratio
 
   badge_class, badge_label =
     case source
-    when :app     then ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s own"]
-    when :default then ["badge bg-inset text-muted border-subtle", "Inherited default"]
+    when :app       then ["badge bg-success/10 text-success border-success/30", "Uploaded here"]
+    when :app_asset then ["badge bg-success/10 text-success border-success/30", "#{Studio.app_name}'s artwork"]
+    when :engine_default then ["badge bg-inset text-muted border-subtle", "Studio default"]
     else               ["badge bg-warning/10 text-warning border-warning/30", "No image"]
     end
 %>

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

@@ -113,6 +113,72 @@
     </div>
   </section>
 
+  <!-- Time stamps: the "at" format -->
+  <section class="space-y-5">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Time stamps — the &ldquo;at&rdquo; format</h3>
+      <p class="text-muted text-sm">
+        <code class="font-mono text-2xs">at_time_tag</code> stamps WHEN something happened, on
+        the reader&rsquo;s own clock. The stamps below are live: the server rendered them in this
+        app&rsquo;s timezone and <code class="font-mono text-2xs">studio/at_time_script</code>
+        re-stamped them in yours. Hover one for the relative time and your zone.
+      </p>
+    </div>
+    <%# An ERB snippet cannot be written literally inside an ERB template: the
+        scanner closes the tag at the first `%` + `>` it sees, whatever Ruby string
+        it sits in. So assemble the markers — the raw template never contains one. %>
+    <% erb = ->(code) { "<" + "%= " + code + " %" + ">" } %>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%= render layout: "style/specimen",
+            locals: { klass: "at_time_tag(time)",
+                      usage: erb.call("at_time_tag(release.shipped_at)") } do %>
+        <span class="text-sm text-body"><%= at_time_tag(Time.current) %></span>
+      <% end %>
+
+      <%# The date joins only when the stamp is not today — the rule is easiest to
+          read as two specimens side by side. %>
+      <%= render layout: "style/specimen",
+            locals: { klass: "at_time_tag — not today",
+                      usage: erb.call("at_time_tag(task.created_at)") + "\n# the date joins only when it is not today" } do %>
+        <span class="text-sm text-body"><%= at_time_tag(3.days.ago) %></span>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: "at_time_tag — another year",
+                      usage: erb.call("at_time_tag(old_record.created_at)") + "\n# the year joins only when it differs" } do %>
+        <span class="text-sm text-body"><%= at_time_tag(1.year.ago) %></span>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: "at_time_tag(time, prefix: nil)",
+                      usage: erb.call("at_time_tag(time, prefix: nil)") + %(\n# bare clock, for a cell that already says "at") } do %>
+        <span class="text-sm text-body"><%= at_time_tag(Time.current, prefix: nil) %></span>
+      <% end %>
+
+      <%# STATIC ILLUSTRATION, not the primitive: a reader inside the US never sees
+          the flag, so a live specimen cannot show them what it looks like. Hand-built
+          to match the hydrated markup exactly (clock, then ml-2, then the flag). %>
+      <%= render layout: "style/specimen",
+            locals: { klass: "outside the US — the flag trails",
+                      usage: %(# The flag is added CLIENT-side from the browser's IANA zone.\n# Inside the US there is no flag at all, and its margin collapses with it.) } do %>
+        <div class="flex flex-col items-start gap-1.5 text-sm text-body">
+          <span class="whitespace-nowrap"><span>at 6:50a</span><span class="ml-2">🇯🇵</span></span>
+          <span class="whitespace-nowrap"><span>at 10:50p</span><span class="ml-2">🇬🇧</span></span>
+          <span class="whitespace-nowrap"><span>at 9:50p</span><span class="ml-2">🌐</span></span>
+          <span class="whitespace-nowrap text-muted"><span>at 4:50p</span></span>
+        </div>
+      <% end %>
+
+      <%# The first caller's shape, so a host sees the primitive in a real pill
+          rather than only as bare text. %>
+      <%= render layout: "style/specimen",
+            locals: { klass: "in a status badge",
+                      usage: %(<span class="badge">Shipped ) + erb.call("at_time_tag(release.shipped_at)") + "</span>" } do %>
+        <span class="badge" style="color: var(--color-success); border-color: var(--color-success)">Shipped <%= at_time_tag(42.minutes.ago) %></span>
+      <% end %>
+    </div>
+  </section>
+
   <!-- Motion primitives -->
   <section class="space-y-5">
     <div class="space-y-1">

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

@@ -58,3 +58,8 @@
     <%= render "style/tasks" %>
   </div>
 </div>
+
+<%# The "at" format's re-stamper, so the Tricks time-stamp specimens hydrate to the
+    reader's clock even on a host that has not yet wired it into its own layout.
+    Self-guarded — a host that HAS wired it renders this as a no-op. %>
+<%= render "studio/at_time_script" %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.39.0"
+  VERSION = "0.40.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -168,8 +168,8 @@ files:
 - Gemfile
 - LICENSE
 - README.md
-- app/assets/images/emails/email-change-confirmation.png
-- app/assets/images/emails/magic-link.png
+- app/assets/images/emails/email-change-confirmation.gif
+- app/assets/images/emails/magic-link.gif
 - app/assets/images/resend-favicon.png
 - app/assets/images/ses-favicon.png
 - app/assets/javascripts/studio/canvas_confetti.js
@@ -203,6 +203,7 @@ files:
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
+- app/helpers/studio/at_time_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
@@ -256,6 +257,7 @@ files:
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
 - app/views/studio/_age_verify_assets.html.erb
+- app/views/studio/_at_time_script.html.erb
 - app/views/studio/_board_assets.html.erb
 - app/views/studio/_confirm_interstitial.html.erb
 - app/views/studio/_cropper_assets.html.erb