studio-engine 0.109.0.rc2 → 0.110.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c0cd3c18b09bb009d42eea9911cb5eef64299aa74ba800f7bdd011da66623b
-  data.tar.gz: b22bc36fc79bac82a01ff679bbd9e7d9a49ea92f4d5b71fb52d1efc95e75bd0b
+  metadata.gz: faad0b30d10e3cfbb58f3af463f47af004c790db2ef4945c7e8c914d533bcc5a
+  data.tar.gz: 567c93db53a89e63a192abf3ccd03b5dfddbadb03df8072783988cd7aed43482
 SHA512:
-  metadata.gz: dd07af40833cdeb4acdaab8e37bffc7f021b9369c14c3b5f6d83c417e7344ada891143924f662cda4bcf6b389098b21eb9c85a860c99134798417273caf7b715
-  data.tar.gz: e4a4fc94d72ffcb463a1e37117dcd53f2d2897aea9ee070852a732cf1bace6b31ec35f3c0bdaa128528dcebd63c5d008a98142a024eb4415eabda0ccc5a02a69
+  metadata.gz: 014cccc62e8ac88d2c6bbf9d5758eaf1997c42ff654f84bbf889d8f0c20f5e3bd15cd3aa8fb7946775e29f91fceaa1f8916a15f57bb7c7340d6c13a21de4b8dd
+  data.tar.gz: d3523274d32ed61fcc806a32a73b17f92f857c7c471bb91bd28b8cfeff5c27ab1cd04100156aca35b46472222789fa6425288178b087142394fe7acc8ef1e217

data/CHANGELOG.md

@@ -4,8 +4,34 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.110.0 — 2026-10-15
+
+### Added
+
+- **The site footer can draw a brand lockup in place of its logo and
+  wordmark.** A new `lockup:` fact in `config.site_footer` names one file per
+  theme, plus the artwork's own size: `lockup: { light:
+  "/brand/stacked-light.svg", dark: "/brand/stacked-dark.svg", width: 942,
+  height: 885 }`. Both images render with the site name as `alt` and that
+  `width`/`height`, inside the home link; CSS shows the light file on a light
+  page and the dark file under `.dark`, so a theme toggle swaps them with no
+  script. It is drawn `7rem` tall (`--ftr-lockup-height` on `.ftr` changes it)
+  and never wider than its column. A lockup centres the brand block
+  (`.ftr-brand-lockup`: the lockup, tagline, email and social row), since a
+  stacked lockup is symmetric; the link columns keep their alignment. A footer that declares no lockup is byte-identical: the lockup's
+  styles render only with it (`studio/site_footer/_lockup_assets`), and an
+  older engine ignores the key. See `docs/SITE_FOOTER.md`, *A lockup*.
+
 ### Changed
 
+- **The favicon link carries its content version.** The head writes
+  `<link rel="icon" href="/favicon.png?v=<8 hex>">`, the first 8 characters of
+  the file's SHA-256 (`Studio::PublicFileVersion.path`), so a redrawn favicon
+  is a new URL: browsers cache a favicon per origin and a hard reload does not
+  reliably clear it, on a reused localhost port or for a returning visitor.
+  The digest is read once per file contents (cached by path, size and mtime).
+  A host with no `public/favicon.png` keeps the bare link, byte for byte.
+
 - **A held navbar eases its collapse again.** 0.108.0 held the header's
   footprint so the page never moves, and with it let the header follow the
   scroll position exactly. On a hard flick that crossed the whole ramp in a

data/app/views/layouts/studio/_head.html.erb

@@ -31,7 +31,9 @@
     includes Studio::ErrorHandling. See studio/_session_stamp. %>
 <%= render "studio/session_stamp" %>
 <%= render "layouts/studio/smooth_load" %>
-<link rel="icon" type="image/png" href="/favicon.png">
+<%# The favicon's URL carries its content version (Studio::PublicFileVersion),
+    so a redrawn favicon is a new URL no browser has cached. %>
+<link rel="icon" type="image/png" href="<%= Studio::PublicFileVersion.path("/favicon.png") %>">
 <%# Link-preview (og:/twitter:) tags: the page's link_preview override, else the
     operator default from /admin/link_preview, else the static fallback. Gated by
     Studio.link_preview_tags? — under the default :auto, only once this app has

data/app/views/studio/site_footer/_footer.html.erb

@@ -15,8 +15,20 @@
   <div class="ftr-wrap">
     <% tracks = Studio::SiteFooter.tracks(columns) %>
     <div class="ftr-cols<%= " ftr-cols-many" if columns.size > Studio::SiteFooter::MAX_ROW_COLUMNS %>"<% if tracks %> style="--ftr-tracks: <%= tracks %>"<% end %>>
-      <div class="ftr-brand">
-        <% if facts[:logo] || facts[:wordmark] %>
+      <div class="ftr-brand<%= " ftr-brand-lockup" if facts[:lockup] %>">
+        <% if (lockup = facts[:lockup]) %>
+          <%# The lockup replaces the logo and the wordmark, and centres the
+              brand block (.ftr-brand-lockup). Both theme files render;
+              studio/site_footer/_lockup_assets shows the one that matches the
+              page, so a theme toggle swaps them with no script. %>
+          <%= render "studio/site_footer/lockup_assets" %>
+          <a href="<%= facts[:home_path] %>" class="ftr-home" aria-label="<%= facts[:name] %>">
+            <% [ [ :light, lockup[:light] ], [ :dark, lockup[:dark] ] ].each do |theme, src| %>
+              <%= image_tag src, class: "ftr-lockup ftr-lockup-#{theme}", alt: facts[:name].to_s,
+                    width: lockup[:width], height: lockup[:height] %>
+            <% end %>
+          </a>
+        <% elsif facts[:logo] || facts[:wordmark] %>
           <a href="<%= facts[:home_path] %>" class="ftr-home" aria-label="<%= facts[:name] %>">
             <% if facts[:logo] %>
               <%= image_tag facts[:logo], class: [ "ftr-logo", ("ftr-logo-invert" if facts[:logo_invert]) ].compact.join(" "), alt: "" %>

data/app/views/studio/site_footer/_lockup_assets.html.erb

@@ -0,0 +1,30 @@
+<%# The footer lockup's styles (the `lockup:` fact; docs/SITE_FOOTER.md). Only
+    a footer that declares a lockup renders this, so a footer without one is
+    byte for byte what it was before the fact existed.
+
+    HEIGHT-LED. The lockup is drawn at --ftr-lockup-height (default 7rem, about
+    the icon-and-name block's height plus the room a stacked logo's second line
+    needs) and its width follows the artwork, never wider than its column. The
+    width and height attributes give the box its shape before the file loads.
+
+    CENTRED. A lockup centres the brand block (.ftr-brand-lockup): the lockup,
+    the tagline, the email and the social row. A stacked lockup is symmetric
+    about its own centre, so it reads as the column's heading only when
+    centred under it. The link columns keep their alignment. The home link is
+    inline-flex, so it hugs the artwork (centred by the block's text-align)
+    and its focus ring, offset 4px, rings the lockup instead of running
+    across the column through the name.
+
+    THEME SWAP. Light shows on a light page, dark under the root's `dark`
+    class. The hide rule comes after the display rule, so it wins on order. %>
+<style>
+  .ftr-lockup { display: block; width: auto; height: var(--ftr-lockup-height, 7rem); max-width: 100%;
+    object-fit: contain; object-position: center; }
+  .ftr-brand-lockup { text-align: center; }
+  .ftr-brand-lockup .ftr-home { display: inline-flex; justify-content: center; vertical-align: top; }
+  .ftr-brand-lockup .ftr-home:focus-visible { outline-offset: 4px; }
+  .ftr-brand-lockup .ftr-socials { justify-content: center; }
+  .ftr-lockup-dark { display: none; }
+  .dark .ftr-lockup-light { display: none; }
+  .dark .ftr-lockup-dark { display: block; }
+</style>

data/docs/SITE_FOOTER.md

@@ -191,6 +191,7 @@ Every key is optional. A missing key removes its part of the footer.
 | `wordmark` | Two parts, the second in the primary colour: `%w[Example Co]` | `name`, split before its last word |
 | `logo` | An image beside the wordmark: an asset name or a path | The app's "Footer Logo" in `config.theme_logos`, else its navbar logo. `logo: false` shows none |
 | `logo_invert` | `true` inverts a dark mark in light mode | Shown as drawn |
+| `lockup` | One brand artwork in place of the logo AND the wordmark, one file per theme: `{ light: "/brand/stacked-light.svg", dark: "/brand/stacked-dark.svg", width: 942, height: 885 }`. See [A lockup](#a-lockup) | The logo and the wordmark |
 | `home_path` | Where the logo and wordmark link | `/` |
 | `tagline` | A line under the wordmark | No line |
 | `email` | A `mailto:` link under the tagline | No line. (To list the email in a column instead, write it as a column link.) |
@@ -282,6 +283,40 @@ Propshaft app. The engine's copy of the stylesheet drops Leaflet's default marke
 image and its layers-control image, which are not shipped: mark a point with
 `L.divIcon`, as the footer does.
 
+
+### A lockup
+
+A kit's stacked logo, say, draws the icon and the name as one piece of
+artwork. Declare it as `lockup:` and the footer draws it in place of the logo
+and the wordmark; the tagline, email and social row stay below it.
+
+```ruby
+config.site_footer = ->(view) {
+  { name: "Example Co",
+    lockup: { light: "/brand/stacked-light.svg", dark: "/brand/stacked-dark.svg",
+              width: 942, height: 885 },
+    tagline: "Everything, by example" }
+}
+```
+
+- `light` is drawn on a light page and `dark` under the root's `dark` class.
+  Both images render and CSS hides the one that does not match, so a theme
+  toggle swaps them with no script (as `Studio.navbar_wordmark` does). With no
+  `dark`, `light` serves both. With no `light`, there is no lockup.
+- `width` and `height` are the artwork's own size, an SVG's `viewBox` rounded.
+  Both are written onto each image so the browser holds the box before the
+  file loads and nothing below it moves. Give both or neither.
+- It is drawn `7rem` tall, its width following the artwork and never wider
+  than its column. Set `--ftr-lockup-height` on `.ftr` to change that.
+- It centres the brand block (`.ftr-brand-lockup`): the lockup, the tagline,
+  the email and the social row, at every width. A stacked lockup is symmetric
+  about its centre, so it is centred rather than given an alignment option; the
+  link columns keep theirs.
+- Both images carry the site name as `alt`, inside the home link.
+- A footer that declares no lockup renders exactly as before: its styles ride
+  only with a lockup (`studio/site_footer/_lockup_assets`). An engine older
+  than the fact ignores the key, so a host can declare it before it upgrades.
+
 ## Where it shows
 
 `studio_site_footer` asks `config.site_footer_visible`, one callable that
@@ -402,13 +437,14 @@ These class names are stable, and an app may style against them:
 |-------|---------|
 | `.ftr` | The footer |
 | `.ftr-cols` | The grid of brand and link columns; `--ftr-tracks` is its link-column tracks. `.ftr-cols-many` with more than four |
-| `.ftr-brand` | The brand block |
+| `.ftr-brand` | The brand block; `.ftr-brand-lockup` when it holds a lockup (centred) |
 | `.ftr-col` | One link column (a `nav`) |
 | `.ftr-heading`, `.ftr-list` | A column's heading and its list |
 | `.ftr-link`, `.ftr-link-solid`, `.ftr-link-disabled` | A link; an address kept on one line; a "coming soon" label. `--ftr-link-ink` on `.ftr` is the link colour |
 | `.ftr-location`, `.ftr-location-title`, `.ftr-address` | The Location band |
 | `.ftr-legal`, `.ftr-copyright` | The legal line and the © line |
 | `.ftr-map` | The map |
+| `.ftr-lockup`, `.ftr-lockup-light`, `.ftr-lockup-dark` | The lockup's images; `--ftr-lockup-height` on `.ftr` is its height |
 
 The rest (`.ftr-wrap`, `.ftr-home`, the social and pin classes) may change.
 
@@ -435,6 +471,8 @@ link. Those rules are more specific than the engine's and still apply.
 
 - `test/lib/studio/site_footer_test.rb`: the facts' rules, the default facts, the
   address setting's precedence, and the visibility rule.
+- `test/views/site_footer_lockup_css_test.rb`: the lockup's size, centring and theme swap,
+  and that the stylesheet every footer renders carries none of it.
 - `test/lib/vendored_leaflet_test.rb`: Leaflet is vendored, precompiled, and
   addressed through the asset pipeline.
 - `test/integration/site_footer_test.rb`: what a host renders, with and without

data/lib/studio/public_file_version.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Studio
+  # A content version for a file in the host's public/ directory, so a link to
+  # it changes when the file does (task footer-stacked-logo). Browsers cache a
+  # favicon per origin and a hard reload does not reliably clear it: a redrawn
+  # /favicon.png kept showing the old picture, both on a localhost port reused
+  # by another desk and for returning production visitors. A versioned URL is
+  # a new resource, so nobody has to bump anything by hand.
+  #
+  #   Studio::PublicFileVersion.path("/favicon.png")
+  #     # => "/favicon.png?v=1a2b3c4d" (the first 8 hex of the file's SHA-256)
+  #     # => "/favicon.png"            when the host has no such file
+  #
+  # The digest is read once per file contents: it is cached by the file's
+  # path, size and mtime, so a process reads each file once and a file
+  # redrawn in development gets its new version on the next request.
+  module PublicFileVersion
+    LENGTH = 8
+    @versions = {}
+    @lock = Mutex.new
+
+    module_function
+
+    # The path with `?v=<digest>` when root/path is a file, else the path as given.
+    def path(path, root: default_root)
+      version = version(path, root: root)
+      version ? "#{path}?v=#{version}" : path
+    end
+
+    # The first LENGTH hex characters of the file's SHA-256, or nil when it is not a file.
+    def version(path, root: default_root)
+      return nil if root.nil?
+
+      file = File.join(root.to_s, path.to_s.delete_prefix("/"))
+      stat = File.stat(file)
+      return nil unless stat.file?
+
+      key = [file, stat.size, stat.mtime.to_r]
+      @lock.synchronize { @versions[key] ||= Digest::SHA256.file(file).hexdigest[0, LENGTH] }
+    rescue SystemCallError
+      nil
+    end
+
+    def default_root
+      ::Rails.public_path if defined?(::Rails.public_path) && ::Rails.respond_to?(:public_path)
+    end
+
+    def reset!
+      @lock.synchronize { @versions.clear }
+    end
+  end
+end

data/lib/studio/site_footer.rb

@@ -183,6 +183,7 @@ module Studio
         wordmark: wordmark(facts[:wordmark], site_name),
         logo: facts.key?(:logo) ? text(facts[:logo]) : text(logo),
         logo_invert: facts[:logo_invert] ? true : false,
+        lockup: lockup(facts[:lockup]),
         home_path: safe_href(facts[:home_path], "home_path") || "/",
         tagline: text(facts[:tagline]),
         email: text(facts[:email]),
@@ -253,6 +254,44 @@ module Studio
       [words[0..-2].join(" "), words.last]
     end
 
+    # THE LOCKUP: one piece of brand artwork (an icon and the name drawn
+    # together, such as a kit's stacked logo) that the footer draws in place of
+    # the logo and the wordmark. One file per theme, as Studio.navbar_wordmark
+    # takes them:
+    #
+    #   lockup: { light: "/brand/stacked-light.svg", dark: "/brand/stacked-dark.svg",
+    #             width: 942, height: 885 }
+    #
+    # `light` is drawn on a light page, `dark` on a dark one; a lockup with no
+    # `dark` uses its `light` file for both. `width` and `height` are the
+    # artwork's own size (an SVG's viewBox): written onto both images, they
+    # give the browser the shape before the file arrives, so nothing moves
+    # when it does. Either one missing or not a positive number, neither is
+    # written. No `light`: no lockup, and the logo and wordmark are drawn.
+    def lockup(declared)
+      return nil unless declared.respond_to?(:to_h) && !declared.is_a?(Array)
+
+      source = symbolize(declared)
+      light = text(source[:light])
+      return nil if light.nil?
+
+      width = dimension(source[:width])
+      height = dimension(source[:height])
+      sized = !width.nil? && !height.nil?
+      { light: light, dark: text(source[:dark]) || light,
+        width: (width if sized), height: (height if sized) }
+    end
+
+    # A positive, finite number, rounded to a whole pixel; anything else is nil.
+    def dimension(value)
+      return nil unless value.is_a?(Numeric) || value.to_s.match?(/\A\s*\d+(\.\d+)?\s*\z/)
+
+      number = Float(value)
+      number.finite? && number.positive? ? [number.round, 1].max : nil
+    rescue ArgumentError, TypeError, FloatDomainError
+      nil
+    end
+
     # The address may be nested under :address or written flat (street:,
     # city_line:, lat:, lng:, directions_url:). No street and no city line means
     # no address at all: no Location band and no map.

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.109.0.rc2"
+  VERSION = "0.110.0.rc1"
 end

data/lib/studio.rb

@@ -13,6 +13,7 @@ require "active_support/core_ext/numeric/time"
 require "active_support/core_ext/integer/time"
 require "studio/version"
 require "studio/local_path"
+require "studio/public_file_version"
 require "studio/component_gallery"
 require "studio/log_rotation"
 require "studio/ip_locations"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.109.0.rc2
+  version: 0.110.0.rc1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -660,6 +660,7 @@ files:
 - app/views/studio/site_footer/_assets.html.erb
 - app/views/studio/site_footer/_footer.html.erb
 - app/views/studio/site_footer/_link.html.erb
+- app/views/studio/site_footer/_lockup_assets.html.erb
 - app/views/studio/site_footer/_map.html.erb
 - app/views/studio/site_footer/_map_assets.html.erb
 - app/views/studio/site_footer/_social_icon.html.erb
@@ -768,6 +769,7 @@ files:
 - lib/studio/partial_block.rb
 - lib/studio/profile_image.rb
 - lib/studio/profile_sections.rb
+- lib/studio/public_file_version.rb
 - lib/studio/public_user.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb