studio-engine 0.123.0 → 0.125.0

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

@@ -1,23 +1,15 @@
 <% content_for(:title, "#{@config.fetch(:label)} - Models - Admin") %>
 
-<div class="max-w-7xl mx-auto px-4 pb-8 space-y-6">
-  <%# The title and a tab per model, one sticky row, as on /admin/style. A tab is a
-      link, so the open one is the page's own model. %>
-  <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="Models">
-    <h1 class="text-xl font-bold text-heading shrink-0">Models</h1>
-    <div class="overflow-x-auto min-w-0 flex-1">
-      <div class="flex items-center gap-2 min-w-max pl-4">
-        <% admin_model_configs.each do |key, config| %>
-          <% open = key.to_s == @key %>
-          <%= link_to config.fetch(:label), admin_model_path(key),
-                class: "btn btn-sm #{open ? 'btn-primary' : 'btn-neutral'}",
-                aria: { current: (open ? "page" : nil) } %>
-        <% end %>
-      </div>
-    </div>
-  </nav>
+<div class="max-w-7xl mx-auto px-4 pt-6 pb-8 space-y-6">
+  <%# The title and a tab per model: studio/_page_header, as on /admin/style. A
+      tab is a link, so the open one is the page's own model. The table's sticky
+      header sits under this row (docs/PAGE_HEADER.md). %>
+  <%= render "studio/page_header",
+        title: "Models",
+        label: "Models",
+        tabs: admin_model_configs.map { |key, config|
+          { label: config.fetch(:label), href: admin_model_path(key), current: (key.to_s == @key ? "page" : nil) }
+        } %>
 
   <p class="text-muted text-sm">
     <%= @config.fetch(:description) %>.

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

@@ -3,8 +3,8 @@
     first answer, never on a page view. %>
 <% content_for(:title, "Surveys") %>
 <div class="max-w-4xl mx-auto px-4 py-6" data-admin-surveys>
-  <h1 class="text-2xl font-extrabold text-heading mb-1">Surveys</h1>
-  <p class="text-sm text-secondary mb-6">Defined in <code>config/surveys/</code>. A response counts as started at its first answer.</p>
+  <%= render "studio/page_header", title: "Surveys" %>
+  <p class="text-sm text-secondary mt-1 mb-6">Defined in <code>config/surveys/</code>. A response counts as started at its first answer.</p>
 
   <% if @rows.empty? %>
     <div class="empty-state">

data/app/views/studio/agent_chat/_form.html.erb

@@ -3,7 +3,7 @@
 <%= form_with url: studio_agent_chat_messages_path, method: :post, local: true,
               html: { style: "view-transition-name: agent-composer;" },
               class: "sticky bottom-3 z-10 rounded-3xl border border-subtle bg-surface shadow-lg focus-within:border-primary transition-colors p-2 flex flex-col gap-2",
-              data: { agent_chat_form: true, turbo: false, test: "agent-chat-form" } do |f| %>
+              data: { agent_chat_form: true, turbo: false, test: "agent-chat-form", vt_morph: ("agent-composer" if @studio_page_transition_direction || Studio.page_transition_direction) } do |f| %>
   <%= hidden_field_tag :soul, soul, id: nil %>
   <p class="px-3 pt-1 text-xs text-danger-ink" role="alert" data-agent-chat-error hidden data-test="agent-chat-error"></p>
   <p class="sr-only" role="status" aria-live="polite" data-agent-chat-status data-test="agent-chat-status"></p>

data/app/views/studio/agent_chat/_header.html.erb

@@ -1,7 +1,7 @@
 <%# locals: (name:, portrait: nil, role: nil) %>
 <%# The chat's head (studio/agent_chat/_chat): the agent's portrait, a big circle centered on top, its name and role under it. `portrait` is ready markup; with none, the name's initial on a plain circle. The portrait keeps one view-transition name, as on the hub's agent pages. %>
 <div class="flex flex-col items-center gap-2 text-center min-w-0" data-test="agent-chat-header" data-agent-name="<%= name %>">
-  <div class="rounded-full shadow-md overflow-hidden" style="view-transition-name: agent-portrait;" data-test="agent-chat-portrait">
+  <div class="rounded-full shadow-md overflow-hidden" style="view-transition-name: agent-portrait;"<% if @studio_page_transition_direction || Studio.page_transition_direction %> data-vt-morph="agent-portrait"<% end %> data-test="agent-chat-portrait">
     <% if portrait.present? %>
       <%= portrait %>
     <% else %>

data/app/views/studio/marketing_kit/_assets.html.erb

@@ -0,0 +1,44 @@
+<%# The kit's scoped styles, read from the theme's tokens with a fallback beside
+    each, like the footer's. Inline, so nothing joins the app's asset manifest or
+    its Tailwind build. %>
+<style>
+  .mkit { --mkit-ink: var(--color-text, #111827); --mkit-soft: var(--color-text-secondary, #4b5563);
+    --mkit-line: var(--color-border, rgb(127 127 127 / .3)); --mkit-card: var(--color-surface, transparent);
+    --mkit-primary: var(--color-primary, currentColor);
+    --mkit-link: var(--color-primary-ink, var(--mkit-primary));
+    max-width: 64rem; margin-inline: auto; padding: 4rem 1rem; display: grid; gap: 3rem; }
+  .mkit-hero { max-width: 48rem; margin-inline: auto; text-align: center; }
+  .mkit-tagline { margin: 0 0 .5rem; color: var(--mkit-link); font-weight: 600; letter-spacing: .05em; text-transform: uppercase; }
+  .mkit-title { margin: 0; color: var(--mkit-ink); font-size: 2.25rem; line-height: 1.1; font-weight: 800; letter-spacing: -.025em; }
+  .mkit-lede { margin: 1rem 0 0; color: var(--mkit-soft); font-size: 1.125rem; line-height: 1.625; }
+  .mkit-heading { margin: 0 0 1rem; color: var(--mkit-ink); font-size: 1.25rem; font-weight: 700; }
+  .mkit-card { overflow: hidden; border: 1px solid var(--mkit-line); border-radius: .75rem; background: var(--mkit-card); }
+  .mkit-card-body { display: block; padding: 1rem; }
+  .mkit-name { display: block; margin: 0; color: var(--mkit-ink); font-weight: 600; }
+
+  .mkit-logos { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fill, minmax(min(100%, 18rem), 1fr)); }
+  .mkit-tiles { display: grid; grid-auto-flow: column; grid-auto-columns: minmax(0, 1fr); }
+  .mkit-tile { display: flex; align-items: center; justify-content: center; height: 8rem; padding: 1rem; }
+  .mkit-tile-img { max-width: 100%; max-height: 100%; object-fit: contain; }
+  .mkit-downloads { display: flex; flex-wrap: wrap; gap: .25rem 1rem; margin-top: .5rem; font-size: .875rem; }
+  .mkit-download { color: var(--mkit-link); text-decoration: underline; text-underline-offset: 2px; }
+  .mkit-download:hover { text-decoration-thickness: 2px; }
+
+  .mkit-palette { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fill, minmax(9rem, 1fr)); }
+  .mkit-swatch { position: relative; }
+  .mkit-swatch-button { display: block; width: 100%; padding: 0; border: 0; background: none; color: inherit; font: inherit; text-align: left; cursor: copy; }
+  .mkit-swatch-button:focus-visible { outline: 2px solid var(--mkit-primary); outline-offset: -2px; }
+  .mkit-swatch:hover { border-color: var(--mkit-primary); }
+  .mkit-chip { display: block; height: 5rem; border-bottom: 1px solid var(--mkit-line); }
+  .mkit-hex { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .875rem; color: var(--mkit-soft); user-select: text; }
+  /* The confirmation sits on the chip, on a ground of its own, so it reads over any colour. */
+  .mkit-status { position: absolute; top: .5rem; right: .5rem; padding: .125rem .5rem; border-radius: 9999px;
+    background: #111827; color: #fff; font-size: .75rem; font-weight: 600; pointer-events: none; }
+  /* Empty, it shows nothing but stays in the tree: a live region that was display: none can miss its announcement. */
+  .mkit-status:empty { padding: 0; background: none; }
+
+  .mkit-face { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: .75rem; padding: 1rem; }
+  .mkit-face + .mkit-face { border-top: 1px solid var(--mkit-line); }
+  .mkit-specimen { margin: 0; color: var(--mkit-ink); font-size: 1.25rem; }
+  .mkit-face-label { margin: 0; color: var(--mkit-soft); font-size: .875rem; }
+</style>

data/app/views/studio/marketing_kit/_kit.html.erb

@@ -0,0 +1,84 @@
+<%# The marketing kit: logos, colours and typefaces (a resolved `kit`, from
+    Studio::MarketingKit.resolve). Each part goes when it has nothing to show. The
+    layout is scoped CSS (.mkit-*), not Tailwind utilities, for the footer's
+    reason: a utility a consumer's build has not seen compiles to nothing. %>
+<%= render "studio/marketing_kit/assets" %>
+<div class="mkit" data-marketing-kit>
+  <header class="mkit-hero">
+    <% if kit[:tagline] %>
+      <p class="mkit-tagline"><%= kit[:tagline] %></p>
+    <% end %>
+    <h1 class="mkit-title"><%= Studio::MarketingKit::LABEL %></h1>
+    <p class="mkit-lede">The <%= kit[:name] ? "#{kit[:name]} " : "" %>logos, colours and typefaces. Use them when you write about us.</p>
+  </header>
+
+  <% if kit[:logos].any? %>
+    <section aria-labelledby="mkit-logos" data-test="kit-logos">
+      <h2 id="mkit-logos" class="mkit-heading">Logos</h2>
+      <div class="mkit-logos">
+        <% kit[:logos].each do |logo| %>
+          <div class="mkit-card">
+            <div class="mkit-tiles">
+              <% logo[:tones].each do |tone| %>
+                <div class="mkit-tile" style="background-color: <%= tone[:ground] %>">
+                  <img src="<%= tone[:src] %>" alt="<%= tone[:alt] %>" class="mkit-tile-img">
+                </div>
+              <% end %>
+            </div>
+            <div class="mkit-card-body">
+              <% if logo[:title] %>
+                <p class="mkit-name"><%= logo[:title] %></p>
+              <% end %>
+              <div class="mkit-downloads">
+                <% logo[:tones].each do |tone| %>
+                  <a href="<%= tone[:href] %>" download class="mkit-download"><%= tone[:label] %></a>
+                <% end %>
+              </div>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    </section>
+  <% end %>
+
+  <% if kit[:palette].any? %>
+    <section aria-labelledby="mkit-colours" data-test="kit-colours">
+      <h2 id="mkit-colours" class="mkit-heading">Colours</h2>
+      <div class="mkit-palette">
+        <% kit[:palette].each do |swatch| %>
+          <%# One button holds the chip, the name and the hex, so a click on any of
+              them copies. The confirmation sits outside it: a button's children
+              are not announced, and a status must be. %>
+          <div class="mkit-card mkit-swatch" data-studio-controller="copy-text" data-copy-text-text-value="<%= swatch[:hex] %>">
+            <button type="button" class="mkit-swatch-button" data-studio-action="click->copy-text#copy"
+                    aria-label="Copy <%= [ swatch[:name], swatch[:hex] ].compact.join(", ") %>">
+              <span class="mkit-chip" style="background-color: <%= swatch[:hex] %>"></span>
+              <span class="mkit-card-body">
+                <% if swatch[:name] %>
+                  <span class="mkit-name"><%= swatch[:name] %></span>
+                <% end %>
+                <code class="mkit-hex"><%= swatch[:hex] %></code>
+              </span>
+            </button>
+            <span class="mkit-status" role="status" data-copy-text-target="status"></span>
+          </div>
+        <% end %>
+      </div>
+    </section>
+  <% end %>
+
+  <% if kit[:typefaces].any? %>
+    <section aria-labelledby="mkit-type" data-test="kit-type">
+      <h2 id="mkit-type" class="mkit-heading">Typefaces</h2>
+      <div class="mkit-card">
+        <% kit[:typefaces].each do |face| %>
+          <div class="mkit-face">
+            <% style = [ ("font-family: #{face[:family]}, sans-serif" if face[:family]), ("font-weight: #{face[:weight]}" if face[:weight]) ].compact.join("; ") %>
+            <p class="mkit-specimen"<% if style.present? %> style="<%= style %>"<% end %>><%= kit[:name] || face[:name] %></p>
+            <p class="mkit-face-label"><%= [ face[:role], face[:name] ].compact.join(" · ") %></p>
+          </div>
+        <% end %>
+      </div>
+    </section>
+  <% end %>
+</div>

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

@@ -0,0 +1,6 @@
+<%# /marketing-kit (Studio::MarketingKitController). The kit is a partial so a host
+    can render it in a page of its own. %>
+<% kit = studio_marketing_kit %>
+<% content_for(:title, [ Studio::MarketingKit::LABEL, kit[:name] ].compact.join(" · ")) %>
+<% content_for(:full_width, true) %>
+<%= render "studio/marketing_kit/kit", kit: kit %>

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

@@ -78,6 +78,7 @@
   .ftr-wordmark-accent { color: var(--ftr-primary); }
   .ftr-tagline { margin: 1.5rem 0 0; line-height: 1.625; color: var(--color-text-secondary, inherit); }
   .ftr-email { margin: .75rem 0 0; }
+  .ftr-kit { margin: .75rem 0 0; }
   .ftr-socials { display: flex; flex-wrap: wrap; align-items: center; gap: .75rem; margin: 2rem 0 0; padding: 0; list-style: none; }
   .ftr-social { display: inline-flex; align-items: center; justify-content: center; width: 2.5rem; height: 2.5rem;
     border-radius: 9999px; background: var(--ftr-primary); color: #fff; transition: transform .15s ease, filter .15s ease; }

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/engine.rb

@@ -89,8 +89,9 @@ module Studio
       # loaded as an ES module (Alpine by the head's type="module" tag,
       # canvas-confetti and SortableJS through their importmap pins, Leaflet by
       # studio/footer_map's import()), and studio/session.js, the one classic
-      # script (layouts/studio/_head says why). The engine's own modules are
-      # under app/javascript, enumerated below.
+      # script (layouts/studio/_head says why), with studio/page_transition_reveal.js,
+      # the other classic one. The engine's own modules are under app/javascript,
+      # enumerated below.
       app.config.assets.precompile += %w[
         studio/sticky_table_header.css
         studio/alpine.js
@@ -99,6 +100,8 @@ module Studio
         studio/leaflet.js
         studio/leaflet.css
         studio/session.js
+        studio/page_transition_full_load.css
+        studio/page_transition_reveal.js
         studio/montserrat-latin.woff2
         studio/montserrat-latin-ext.woff2
       ]