studio-engine 0.123.0 → 0.124.0

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

@@ -44,6 +44,11 @@
         <% if facts[:email] %>
           <p class="ftr-email"><a href="mailto:<%= facts[:email] %>" class="ftr-link ftr-link-solid"><%= facts[:email] %></a></p>
         <% end %>
+        <%# The brand block, not a link column or the legal line: the kit belongs to the
+            brand, and an app's own columns and legal line stay exactly what it wrote. %>
+        <% if facts[:marketing_kit] %>
+          <p class="ftr-kit"><%= render "studio/site_footer/link", link: facts[:marketing_kit], booking: booking %></p>
+        <% end %>
         <% if facts[:social].any? %>
           <ul class="ftr-socials" aria-label="Social profiles">
             <% facts[:social].each do |profile| %>

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

@@ -72,6 +72,41 @@
     </div>
   </section>
 
+  <!-- Page header -->
+  <section class="space-y-5" data-page-header-specimen>
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Page header</h3>
+      <p class="text-muted text-sm">
+        <code class="font-mono text-2xs">studio/_page_header</code>: the title, optional meta beside
+        it and optional tabs on the right. This page's own title row is one: scroll to see it take the bar.
+        It joins the pinned stack, so a table's sticky header sits under it: navbar, page row, table
+        header, each below the last. The rule is in <code class="font-mono text-2xs">docs/PAGE_HEADER.md</code>.
+      </p>
+    </div>
+    <div class="grid gap-4 lg:grid-cols-2">
+      <%# The classes alone, not the partial: the partial's row is sticky, joins the
+          pinned stack and holds the page's h1, and a page has one of each. %>
+      <% [["At rest", {}], ["Stuck", { stuck: "" }]].each do |state, data| %>
+        <%= render layout: "style/specimen",
+              locals: { klass: "studio/_page_header (#{state.downcase})",
+                        usage: %(<%= render "studio/page_header",\n      title: "Models", meta: "v1.2.3", label: "Models",\n      tabs: [{ label: "Users", href: users_path, current: "page" }, { label: "Teams", href: teams_path }] %\>) } do %>
+          <%= tag.div(class: "page-header w-full px-4", data: data) do %>
+            <div class="page-header-lead">
+              <p class="page-header-title">Models</p>
+              <p class="page-header-meta label-upper">v1.2.3</p>
+            </div>
+            <div class="page-header-tabs">
+              <div class="page-header-track">
+                <a href="#tricks" class="btn btn-sm btn-primary">Users</a>
+                <a href="#tricks" class="btn btn-sm btn-neutral">Teams</a>
+              </div>
+            </div>
+          <% end %>
+        <% end %>
+      <% end %>
+    </div>
+  </section>
+
   <!-- Surfaces, text and form -->
   <section class="space-y-5">
     <div class="space-y-1">

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

@@ -3,7 +3,7 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Five ENGINE sections, reached by the sticky title row below and rendered
+     Five ENGINE sections, reached by the page header below and rendered
      as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the theme editor, the live preview, and the
      logos and type), then Modals (the shared host + engine card blocks), Tricks
@@ -53,36 +53,25 @@
     ["components", "Components"]
   ]
 %>
-<div class="max-w-6xl mx-auto px-4 pb-16">
-  <%# The page's title and its section tabs, one sticky row under the whole pinned
-      stack (--pin-stack-bottom; then --nav-bottom and --nav-h for a host on an
-      older publisher; then 0). Not --nav-h first: that is the header's HEIGHT,
-      and chrome stacked above the header would sit over the row by its own
-      height. The tabs scroll sideways on a narrow screen, softened by
-      .fade-edge-x; px-8 matches its 2rem fade, so a tab at rest is not faded.
-      The row sits at --z-sticky, above --z-raised, so the live hold button's
-      portal bubbles scroll under it rather than over it.
-  
+<div class="max-w-6xl mx-auto px-4 pt-6 pb-16">
+  <%# The page's title and its section tabs: studio/_page_header, the row of the
+      triple stack (docs/PAGE_HEADER.md). It sits at --z-sticky, above --z-raised,
+      so the live hold button's portal bubbles scroll under it rather than over it.
+
       The style-section-nav controller moves the highlight as the page scrolls
       (studio/style_section_nav). Theme starts active, so the first paint is
       right before the module loads. %>
-  <nav class="sticky -mx-4 mt-6 px-4 py-2 bg-surface border-y border-subtle flex items-center gap-2"
-       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)"
-       aria-label="Style guide sections"
-       data-studio-controller="style-section-nav">
-    <h1 class="text-xl font-bold text-heading shrink-0">Style</h1>
-    <div class="fade-edge-x overflow-x-auto min-w-0 flex-1" data-style-section-nav-target="scroller">
-      <div class="flex items-center gap-2 min-w-max px-8">
-        <% sections.each_with_index do |(anchor, label), index| %>
-          <a href="#<%= anchor %>"
-             class="btn btn-sm <%= index.zero? ? "btn-primary" : "btn-neutral" %>"
-             <%= 'aria-current="true"'.html_safe if index.zero? %>
-             data-style-section-nav-target="link"><%= label %></a>
-        <% end %>
-      </div>
-    </div>
-    <p class="label-upper shrink-0 hidden md:block" title="studio-engine">v<%= Studio::VERSION %></p>
-  </nav>
+  <%= render "studio/page_header",
+        title: "Style",
+        meta: "v#{Studio::VERSION}",
+        meta_title: "studio-engine",
+        label: "Style guide sections",
+        data: { studio_controller: "style-section-nav" },
+        tabs_data: { style_section_nav_target: "scroller" },
+        tabs: sections.each_with_index.map { |(anchor, label), index|
+          { label: label, href: "##{anchor}", current: (index.zero? ? "true" : nil),
+            data: { style_section_nav_target: "link" } }
+        } %>
 
   <div class="space-y-16 pt-10">
     <%= render "style/theme" %>

data/docs/SITE_FOOTER.md

@@ -53,6 +53,9 @@ It prints only what the engine knows to be true of the app:
   when a GET reaches it and its path needs no arguments. A host with neither
   gets the © line alone.
 
+- **A Marketing Kit link**, when the app has the page: every app that calls
+  `Studio.routes` does ([The marketing kit](#the-marketing-kit)).
+
 It has no address, no map, no phone, no email, no tagline, no social row and no
 link columns, and the page names no Leaflet. The engine cannot know those, and
 a guessed link is a dead one. For any of them, add a location (below) or
@@ -150,8 +153,9 @@ Leave `config.site_footer` unset and the same app gets
 [the default footer](#the-default-footer), its name read from `config.app_name`
 since there is no site-identity table to ask.
 
-Do not call `Studio.routes(self)`: everything it draws (sign-in, admin, error
-logs) needs a database. The app also needs an asset pipeline (Propshaft or
+Do not call `Studio.routes(self)`: what it draws (sign-in, admin, error logs)
+needs a database. The one route that does not is the marketing kit's, which such
+an app can draw alone ([The marketing kit](#the-marketing-kit)). The app also needs an asset pipeline (Propshaft or
 Sprockets), as every Rails 8 app has, and a mapping of the theme tokens onto its
 own palette (see [Colours](#colours)).
 
@@ -200,6 +204,7 @@ Every key is optional. A missing key removes its part of the footer.
 | `columns` | Link columns under bold headings. A column may carry a width hint: `[ "Contact", links, { width: 1.5 } ]` | Brand only |
 | `legal` | The centred line above the © | The © alone |
 | `booking` | `{ label:, title: }` for the popup's heading and the frame's accessible name | "Schedule a call", and "Schedule a call with <name>" |
+| `marketing_kit` | `false` removes the footer's link to the kit ([The marketing kit](#the-marketing-kit)) | The link, on an app with the page |
 
 Rows may be tuples, as above, or hashes (`{ label:, href: }`, `{ heading:, links: }`,
 `{ label:, icon:, url: }`). The rules a row can carry:
@@ -319,6 +324,103 @@ config.site_footer = ->(view) {
   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.
 
+## The marketing kit
+
+Every app has a public page at `/marketing-kit`, with its logos, colours and
+typefaces, and the footer links it. Neither needs a line of setup.
+
+**The page.** `Studio.routes` draws it by default, with no sign-in. The route's
+helper is `studio_marketing_kit_path`.
+
+| Setting | Meaning | Unset |
+|---------|---------|-------|
+| `config.draw_marketing_kit_routes` | `false` draws no page, and with no page the footer links none | `true` |
+| `config.marketing_kit` | The kit: a Hash, or a callable taking the view | Derived from the theme (below) |
+
+```ruby
+# config/initializers/studio.rb
+config.marketing_kit = {
+  tagline:   "Everything, by example",
+  logos:     [ { title: "Icon", light: { png: "/brand/icon-light.png", svg: "/brand/icon-light.svg" },
+                                dark:  { png: "/brand/icon-dark.png",  svg: "/brand/icon-dark.svg" } } ],
+  palette:   [ { name: "Ink", hex: "#1A1535" } ],
+  typefaces: [ { role: "Headings", family: "Montserrat", weight: 800, name: "Montserrat ExtraBold" } ]
+}
+```
+
+Every key is optional, and each key stands alone: a kit that declares only
+`tagline:` still derives its logos and colours. `logos: []` shows none. `name:`
+overrides the site name in the page's first line.
+
+| Key | With no declaration |
+|-----|---------------------|
+| `logos` | `config.navbar_wordmark` and the footer's `lockup`, each with its two tones, then one logo for each entry in `config.theme_logos` but the favicon. A theme entry names one file, so the rest is looked for beside it: a `-light`/`-dark` or `_light`/`_dark` sibling. A name with no tone in it is the light artwork. Every file's other format (`.png`, `.svg`) is looked for too |
+| `palette` | The colours the app paints: its `/admin/theme` values over `Studio.theme_config` (primary, dark, light, success, warning, danger, accent) |
+| `typefaces` | None. The engine cannot know them, so the section is gone |
+| `tagline` | None |
+
+- **`light` is the artwork for a light background**, and `dark` for a dark one.
+- **A logo offers "Download Light" and "Download Dark".** Each downloads the PNG when
+  there is one, else the SVG. Make the PNG transparent. The tile shows the SVG when
+  there is one. Only PNG and SVG are offered.
+- **A file that is not there is not an error.** Each file is looked for before it is
+  linked, in `public/` and, for a name with no leading `/`, in the asset pipeline. A
+  tone with no file has no tile and no link. A logo with no file has no card. An
+  `http(s)` URL is taken at its word and is not fetched, so a dead one shows a broken
+  image; a browser downloads a cross-origin file only if that host says so.
+- **A colour copies on one click**, on the chip, the name or the hex, and shows
+  "Copied" on the chip. It runs from the lazy `copy-text` controller
+  (`studio/controllers/copy_text_controller`). Only a real hex is printed.
+- **A tile's image carries `?kit`.** A host may repaint its own logo by the image's
+  exact `src` on a dark page, as the hub's `.dark img[src="/brand/icon-light.svg"]`
+  does, and that would turn a light tile's artwork dark. The download keeps the plain URL.
+- **A callable that raises** shows locally. In production it is logged once and the
+  page shows what derives from the theme.
+
+**A host's own page wins.** A GET route of the path `/marketing-kit` beats the
+engine's, whichever side of `Studio.routes` it is drawn on. Drawn before, the engine
+draws nothing; drawn after, the engine's route yields at request time. So the hub
+keeps its page until it adopts this one.
+
+**Sign-in.** `Studio::MarketingKitController` inherits the host's
+`ApplicationController` for its layout and skips each gate it knows by name
+(`HOST_GATES`): `require_authentication`, the hub's `require_admin_wall`,
+`require_admin`, `require_login`, `authenticate_user!` and
+`require_profile_completion`. A gate of another name needs one line:
+
+```ruby
+# config/initializers/studio.rb
+Rails.application.config.to_prepare do
+  Studio::MarketingKitController.skip_before_action :my_gate, raise: false
+end
+```
+
+A host whose test suite walks its route table sees `studio/marketing_kit#show` as a
+public page; list it wherever that suite lists them.
+
+**An app with no database** does not call `Studio.routes`, so it has no page and its
+footer links none. To have both, draw the one route. The page reads no table and no
+session:
+
+```ruby
+# config/routes.rb
+Studio.marketing_kit_routes(self)
+```
+
+**The footer link** is "Marketing Kit", in the brand block, under the tagline and the
+email. Every viewer who sees the footer sees it, on every app with the page, with
+nothing declared. It is not in a link column or on the legal line, so an app's columns
+and legal line stay exactly what it wrote.
+
+- An app that already links the page in a column or on the legal line keeps its own
+  row and gets no second link. The comparison is on the path, so a query or a trailing
+  `/` still counts.
+- `marketing_kit: false` in the facts shows no link.
+- A signed-in viewer sees the footer on the page itself, as on the booking page.
+
+To render the kit in a page of your own:
+`render "studio/marketing_kit/kit", kit: Studio.marketing_kit_for(self)`.
+
 ## The Chat link
 
 The standard way to reach an app's agent chat ([`AGENT_CHAT.md`](AGENT_CHAT.md)):
@@ -478,6 +580,7 @@ These class names are stable, and an app may style against them:
 | `.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-kit` | The Marketing Kit link's line in the brand block |
 | `.ftr-map` | The map |
 | `.ftr-lockup`, `.ftr-lockup-light`, `.ftr-lockup-dark` | The lockup's images; `--ftr-lockup-height` on `.ftr` is its height |
 
@@ -527,5 +630,13 @@ link. Those rules are more specific than the engine's and still apply.
   line inside its column at each, and the line heights. These lab pages load Turbo, so the map's remount after a Turbo visit is
   covered.
 
+- `test/lib/studio/marketing_kit_test.rb`: what a kit resolves to, derived and
+  declared, and that a missing file or a malformed row costs nothing.
+- `test/integration/marketing_kit_test.rb`: the page through a real signed-out
+  request in a host that gates every controller, the footer link and its no-double
+  rule, and a host route of the same path winning from either side.
+- `e2e/marketing_kit.spec.js`: the hex on the clipboard, the confirmation, the
+  refused copy, and the downloads, in a browser.
+
 `/admin/style` shows the footer under Tricks, with this app's own facts, or a
 sample when it has declared none (the default footer or `false`).

data/lib/studio/marketing_kit.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+# THE MARKETING KIT (docs/SITE_FOOTER.md, "The marketing kit"): the public page
+# at /marketing-kit, with the app's logos, colours and typefaces for anyone to
+# use. Studio.marketing_kit declares it, as a Hash or a callable taking the view:
+#
+#   config.marketing_kit = {
+#     tagline:   "Everything, by example",
+#     logos:     [ { title: "Icon", light: { png: "/brand/icon-light.png", svg: "/brand/icon-light.svg" },
+#                                   dark:  { png: "/brand/icon-dark.png",  svg: "/brand/icon-dark.svg" } } ],
+#     palette:   [ { name: "Ink", hex: "#1A1535" } ],
+#     typefaces: [ { role: "Headings", family: "Montserrat", weight: 800, name: "Montserrat ExtraBold" } ]
+#   }
+#
+# Every key is optional. A missing `logos` derives from the app's brand artwork
+# (Studio.navbar_wordmark, the footer's lockup, Studio.theme_logos) and a missing
+# `palette` from the colours it paints (ThemeSetting, else Studio.theme_config),
+# so a new app has a working page with no setup. The engine knows no typeface or tagline, so those parts are
+# simply absent until declared.
+#
+# A FILE THAT IS NOT THERE IS NOT AN ERROR. Each file is looked for before it is
+# linked: a tone with no file has no tile and no link, and a logo with no file
+# has no card. So the page shows no broken image, and it does not raise.
+#
+# `light` means the artwork made for a light background; `dark`, for a dark one.
+module Studio
+  module MarketingKit
+    PATH = "/marketing-kit"
+    LABEL = "Marketing Kit"
+    CONTROLLER = "studio/marketing_kit"
+    ROUTE_NAME = :studio_marketing_kit
+
+    LIGHT_GROUND = "#FFFFFF"
+    FALLBACK_DARK_GROUND = "#111827"
+
+    HEX = /\A#(?:\h{3}|\h{4}|\h{6}|\h{8})\z/
+    # What may sit inside a style attribute: a family list, and a CSS weight.
+    FONT_FAMILY = /\A[\w\s"',.-]+\z/
+    FONT_WEIGHT = /\A(?:[1-9]00|normal|bold|lighter|bolder)\z/
+
+    DOWNLOAD_LABELS = { light: "Download Light", dark: "Download Dark" }.freeze
+    FORMATS = %i[png svg].freeze
+
+    module_function
+
+    def validate!(declared)
+      return if declared.nil? || declared == false || declared.is_a?(Hash) || declared.respond_to?(:call)
+
+      raise ArgumentError,
+            "Studio.marketing_kit must be nil (derive it), a Hash, or a callable receiving the view " \
+            "(got #{declared.class}). See docs/SITE_FOOTER.md."
+    end
+
+    # The kit the page prints.
+    #
+    #   logos:       Studio.theme_logos, for a kit that declares no `logos`
+    #   artwork:     brand artwork of one file per theme, [ title, { light:, dark: } ]
+    #                rows that come before them (the wordmark, the lockup)
+    #   theme:       the colours the app paints, for a kit that declares no `palette`
+    #   name:        the site's name, for a kit that declares none
+    #   dark_ground: the dark tile's background
+    #   locate:      a callable answering a file's URL, or nil when it is not there
+    def resolve(declared, view, logos: [], artwork: [], theme: {}, name: nil, dark_ground: nil,
+                locate: ->(file) { locate(file, view) })
+      raw = declared.respond_to?(:call) ? declared.call(view) : declared
+      validate!(raw)
+      facts = raw ? SiteFooter.symbolize(raw) : {}
+      ground = hex(dark_ground) || FALLBACK_DARK_GROUND
+
+      {
+        name: SiteFooter.text(facts[:name]) || SiteFooter.text(name),
+        tagline: SiteFooter.text(facts[:tagline]),
+        logos: logo_cards(facts.key?(:logos) ? facts[:logos] : derived_artwork(artwork) + derived_logos(logos), locate, ground),
+        palette: swatches(facts.key?(:palette) ? facts[:palette] : derived_palette(theme)),
+        typefaces: typefaces(facts[:typefaces])
+      }
+    end
+
+    # ---- logos ---------------------------------------------------------------
+
+    # One card per logo that has a file, each with one tile per tone that has one.
+    # Two theme entries for one file (a Navbar Logo that is also the Auth Logo)
+    # are one card.
+    def logo_cards(declared, locate, dark_ground)
+      Array(declared).filter_map do |row|
+        next unless row.respond_to?(:to_h) && !row.is_a?(Array)
+
+        logo = SiteFooter.symbolize(row)
+        tones = { light: LIGHT_GROUND, dark: dark_ground }.filter_map do |tone, ground|
+          tile(logo[:title], tone, ground, logo[tone], locate)
+        end
+        { title: SiteFooter.text(logo[:title]), tones: tones } unless tones.empty?
+      end.uniq { |card| card[:tones].map { |tone| tone[:href] } }
+    end
+
+    # A download is the PNG when there is one, else the SVG. The tile shows the
+    # SVG when there is one, since it stays sharp at any size.
+    def tile(title, tone, ground, files, locate)
+      found = formats(files).transform_values { |file| locate.call(file) }.compact
+      href = found[:png] || found[:svg]
+      return nil if href.nil?
+
+      { tone: tone, ground: ground, label: DOWNLOAD_LABELS.fetch(tone), href: href,
+        src: tile_src(found[:svg] || found[:png]),
+        alt: [SiteFooter.text(title), "for a #{tone} background"].compact.join(", ") }
+    end
+
+    # { png:, svg: }, or one path whose extension says which it is.
+    def formats(files)
+      return SiteFooter.symbolize(files).slice(*FORMATS) if files.is_a?(Hash)
+      return {} unless files.is_a?(String)
+
+      format = File.extname(files.split(/[?#]/).first.to_s).delete_prefix(".").downcase.to_sym
+      FORMATS.include?(format) ? { format => files } : {}
+    end
+
+    # ?kit keeps a tile's tone. A host may repaint its own logo by the image's
+    # exact src on a dark page (the hub's `.dark img[src="/brand/icon-light.svg"]`),
+    # which would turn the light tile's artwork into the dark one. The download
+    # keeps the plain URL.
+    def tile_src(url)
+      return url if url.match?(%r{\Ahttps?://}i)
+
+      "#{url}#{url.include?('?') ? '&' : '?'}kit"
+    end
+
+    # Artwork that already names its file per tone, as the wordmark and the
+    # lockup do. Each file may have its other format beside it.
+    def derived_artwork(rows)
+      Array(rows).filter_map do |title, files|
+        next unless files.respond_to?(:to_h) && !files.is_a?(Array)
+
+        tones = SiteFooter.symbolize(files).slice(:light, :dark).compact
+        { title: title }.merge(tones.transform_values { |file| both_formats(file.to_s.delete_suffix(File.extname(file.to_s))) })
+      end
+    end
+
+    # The logos Studio.theme_logos implies. It names one file per logo and says
+    # nothing about tone, so the rest is looked for beside it: the same stem as
+    # the other format, and a -light/-dark (or _light/_dark) sibling. A stem with
+    # no such hint is the light artwork.
+    def derived_logos(theme_logos)
+      entries = Array(theme_logos).map { |entry| entry.is_a?(Hash) ? SiteFooter.symbolize(entry) : { file: entry } }
+      entries.filter_map do |entry|
+        file = SiteFooter.text(entry[:file])
+        next if file.nil?
+
+        title = SiteFooter.text(entry[:title]) || humanize(file)
+        next if title.match?(/favicon/i)
+
+        { title: title }.merge(tone_candidates(file))
+      end
+    end
+
+    def tone_candidates(file)
+      stem = file.delete_suffix(File.extname(file))
+      base, separator, hint = stem.match(/\A(.+)([-_])(light|dark)\z/)&.captures
+
+      return { light: both_formats(stem), dark: both_formats("#{stem}-dark") } if hint.nil?
+
+      other = hint == "light" ? "dark" : "light"
+      { hint.to_sym => both_formats(stem), other.to_sym => both_formats("#{base}#{separator}#{other}") }
+    end
+
+    def both_formats(stem) = { png: "#{stem}.png", svg: "#{stem}.svg" }
+
+    def humanize(file)
+      File.basename(file, File.extname(file)).tr("-_", " ").split.map(&:capitalize).join(" ")
+    end
+
+    # ---- colours and type ----------------------------------------------------
+
+    def derived_palette(theme)
+      theme.to_h.map { |name, value| { name: name.to_s.capitalize, hex: value } }
+    end
+
+    # Only a real hex is printed: it goes into a style attribute and the clipboard.
+    def swatches(declared)
+      Array(declared).filter_map do |row|
+        next unless row.respond_to?(:to_h) && !row.is_a?(Array)
+
+        swatch = SiteFooter.symbolize(row)
+        value = hex(swatch[:hex])
+        { name: SiteFooter.text(swatch[:name]), hex: value } unless value.nil?
+      end
+    end
+
+    def hex(value)
+      string = value.to_s.strip
+      string.match?(HEX) ? string : nil
+    end
+
+    # A face with no family cannot be shown. A family or weight CSS would not
+    # read leaves the specimen in the page's own type, with its label intact.
+    def typefaces(declared)
+      Array(declared).filter_map do |row|
+        next unless row.respond_to?(:to_h) && !row.is_a?(Array)
+
+        face = SiteFooter.symbolize(row)
+        family = SiteFooter.text(face[:family])
+        next if family.nil?
+
+        { role: SiteFooter.text(face[:role]), family: (family if family.match?(FONT_FAMILY)),
+          weight: face[:weight].to_s[FONT_WEIGHT], name: SiteFooter.text(face[:name]) || family }
+      end
+    end
+
+    # ---- finding a file ------------------------------------------------------
+
+    # The URL of a file, or nil when it is not there. An http(s) URL is taken at
+    # its word, since looking would cost the page a network call. A path is
+    # looked for in public/; a bare name, then in the asset pipeline.
+    def locate(file, view = nil)
+      value = SiteFooter.text(file)
+      return nil if value.nil?
+      return value if value.match?(%r{\Ahttps?://[^\s]+\z}i)
+      return nil unless local?(value)
+
+      path = "/#{value.delete_prefix('/')}"
+      return path if public_file?(path)
+
+      value.start_with?("/") ? nil : pipeline_path(value, view)
+    rescue StandardError
+      nil
+    end
+
+    # No scheme, no host, no control character and no climbing out of public/.
+    def local?(value)
+      return false if value.match?(/[\x00-\x1f\x7f\s]/) || value.start_with?("//")
+      return false if value.match?(/\A[a-z][a-z0-9+.-]*:/i)
+
+      !value.split(/[?#]/).first.to_s.split("/").include?("..")
+    end
+
+    def public_file?(path)
+      !PublicFileVersion.version(path.split(/[?#]/).first).nil?
+    end
+
+    def pipeline_path(name, view)
+      return nil unless view.respond_to?(:asset_path) && in_pipeline?(name)
+
+      view.asset_path(name)
+    end
+
+    # Propshaft answers through its load path; Sprockets through its environment
+    # or, precompiled, its manifest. asset_path alone cannot say: a host may have
+    # it fall back to a plain path for a file that is not there.
+    def in_pipeline?(name)
+      return false unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+      app = ::Rails.application
+      assets = app.respond_to?(:assets) ? app.assets : nil
+      return !assets.load_path.find(name).nil? if assets.respond_to?(:load_path)
+      return !assets.find_asset(name).nil? if assets.respond_to?(:find_asset)
+
+      manifest = app.respond_to?(:assets_manifest) ? app.assets_manifest : nil
+      manifest.respond_to?(:assets) && manifest.assets.key?(name)
+    end
+
+    # ---- the route -----------------------------------------------------------
+
+    # True when the route set holds a GET of /marketing-kit that is not the
+    # engine's: the host's own page, which wins. Asked for every footer on a page
+    # that has no engine route, and by the engine route's constraint, so the
+    # answer is kept per route set until that set changes size.
+    def host_route?(routes)
+      table = routes.routes
+      known = host_route_memo[routes]
+      return known.last if known && known.first == table.size
+
+      answer = table.any? { |route| host_page_route?(route) }
+      host_route_memo[routes] = [table.size, answer]
+      answer
+    end
+
+    def host_route_memo
+      @host_route_memo ||= {}.compare_by_identity
+    end
+
+    def host_page_route?(route)
+      return false if route.defaults[:controller] == CONTROLLER
+      return false unless route.path.spec.to_s.delete_suffix("(.:format)") == PATH
+
+      verbs = route.verb.to_s
+      verbs.empty? || verbs.split("|").include?("GET")
+    end
+
+    # The engine's route gives way to a host route drawn AFTER Studio.routes.
+    # (One drawn before it wins by order, and then the engine draws nothing.)
+    class YieldToHostRoute
+      def initialize(routes) = @routes = routes
+      def matches?(_request) = !MarketingKit.host_route?(@routes)
+    end
+
+    # Where the footer links: the page's path, or nil when this app has no page.
+    def page_path(view, routes)
+      return nil if routes.nil?
+
+      SiteFooter.host_path(view, ROUTE_NAME, routes) || (PATH if host_route?(routes))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/studio/site_footer.rb

@@ -31,8 +31,8 @@ module Studio
     DEFAULT_BOOKING_LABEL = "Schedule a call"
     DEFAULT_ZOOM = 15
 
-    # The engine's own booking page keeps the footer for a signed-in viewer.
-    OWN_CONTROLLERS = %w[studio/bookings].freeze
+    # The engine's own public pages keep the footer for a signed-in viewer.
+    OWN_CONTROLLERS = %w[studio/bookings studio/marketing_kit].freeze
 
     # The only schemes a footer href may carry. Anything else, notably
     # `javascript:` and `data:`, is never written into an href: the label is
@@ -124,7 +124,7 @@ module Studio
     # THE DEFAULT FOOTER'S FACTS: what an app that sets nothing gets. Only what
     # is known to be true of the host: a legal line linking the routes in
     # DEFAULT_LEGAL that the host really has. The name and the logo come from
-    # `resolve`'s own fallbacks. No address, no email, no tagline, no social row
+    # `resolve`'s own fallbacks, and so does the Marketing Kit link. No address, no email, no tagline, no social row
     # and no link columns: the engine cannot know them, and a guessed link is a
     # dead one.
     #
@@ -171,13 +171,16 @@ module Studio
     #   address:      Studio.site_footer_address: the address of facts that
     #                 carry none of their own
     #   chat:         the Chat entry's [label, path] (`chat_row`), or nil
-    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil, chat: nil)
+    #   marketing_kit: the kit page's path (Studio::MarketingKit.page_path), or nil
+    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil, chat: nil, marketing_kit: nil)
       raw = declared.respond_to?(:call) ? declared.call(view) : declared
       return nil if raw.nil? || raw == false
 
       facts = symbolize(raw)
       site_name = text(facts[:name]) || text(name)
       booking = symbolize(facts[:booking] || {})
+      columns = with_chat(Array(facts[:columns]).filter_map { |row| column(row, booking_path) }, chat)
+      legal = Array(facts[:legal]).filter_map { |row| link(row, booking_path) }
 
       {
         name: site_name,
@@ -190,8 +193,9 @@ module Studio
         email: text(facts[:email]),
         address: address_for(facts, address),
         social: Array(facts[:social]).filter_map { |row| social(row) },
-        columns: with_chat(Array(facts[:columns]).filter_map { |row| column(row, booking_path) }, chat),
-        legal: Array(facts[:legal]).filter_map { |row| link(row, booking_path) },
+        columns: columns,
+        legal: legal,
+        marketing_kit: marketing_kit_link(facts, marketing_kit, columns, legal),
         booking_label: text(booking[:label]) || DEFAULT_BOOKING_LABEL,
         booking_title: text(booking[:title])
       }
@@ -417,6 +421,18 @@ module Studio
       end
     end
 
+    # THE MARKETING KIT LINK, in the brand block: every app with the page gets it
+    # without declaring it. An app that links the page itself keeps its own row
+    # and gets no second one, and `marketing_kit: false` in the facts shows none.
+    def marketing_kit_link(facts, path, columns, legal)
+      return nil if path.nil? || (facts.key?(:marketing_kit) && !facts[:marketing_kit])
+
+      declared = columns.flat_map { |column| column[:links] } + legal
+      return nil if declared.any? { |row| Studio::Booking.same_path?(row[:href], path) }
+
+      link([ Studio::MarketingKit::LABEL, path ])
+    end
+
     # A column's width hint, or nil for the default share. Anything that is not a
     # number between MIN_COLUMN_WIDTH and MAX_COLUMN_WIDTH is no hint.
     MIN_COLUMN_WIDTH = 0.5

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.123.0"
+  VERSION = "0.124.0"
 end