studio-engine 0.81.1 → 0.82.0

data/app/models/studio/site_identity.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Studio
+  # This app's IDENTITY COPY: the title and description that say what the app is,
+  # and the picture that goes with them. The operator edits all three together
+  # at /admin/link_preview, beside a live preview card.
+  #
+  # Link previews are the first reader (every page unfurls with these unless it
+  # overrides them), but not the only one: the words are the app's reusable
+  # identity, so an app reads them through Studio.site_identity (or the view
+  # helper studio_site_identity) wherever it needs them — a meta description,
+  # share text, an email footer.
+  #
+  # One row per app (Studio.app_name), exactly like Studio::GeoSetting. Lifted
+  # from turf-monster's SiteSetting (default_og_image/title/description and the
+  # og_defaults cache), which ran it in production first.
+  #
+  # THE RESOLUTION, most specific first:
+  #
+  #   operator's saved value (this row)  ->  the drafted default in code
+  #   (Studio.site_title / Studio.site_description)  ->  Studio.app_name / none
+  #
+  # So an agent setting an app up drafts the words into the initializer, where
+  # they are reviewed in a PR, and the operator overrides them here without a
+  # deploy. `seed!` carries a drafted default into the row instead.
+  #
+  # NIL-SAFE THROUGHOUT, because the table is installed by a migration the host
+  # runs: an app that has not run it still renders every page.
+  class SiteIdentity < ApplicationRecord
+    include Sluggable
+
+    self.table_name = "studio_site_identities"
+
+    # Read on EVERY page render (the head's tags), edited a few times a year. So
+    # the stored values are cached, and busted on any write — see .stored.
+    CACHE_KEY_PREFIX = "studio/site_identity/v1"
+    CACHE_TTL = 1.hour
+
+    TITLE_MAX = 200
+    DESCRIPTION_MAX = 500
+
+    # What the image upload accepts. Here rather than on the controller so the
+    # page's file input can name it without reaching into a controller.
+    IMAGE_TYPES = %w[image/png image/jpeg image/webp image/gif].freeze
+    MAX_IMAGE_BYTES = 8 * 1024 * 1024
+
+    # The image. `service:` is a LITERAL fixed when this class loads, which is why
+    # Studio.link_preview_image_service must be set in the initializer. Guarded
+    # so a host without Active Storage still loads the class (and simply has no
+    # uploadable image).
+    if respond_to?(:has_one_attached)
+      if Studio.link_preview_image_service
+        has_one_attached :image, service: Studio.link_preview_image_service
+      else
+        has_one_attached :image
+      end
+    end
+
+    validates :app_name, presence: true, uniqueness: true
+    validates :title, length: { maximum: TITLE_MAX }
+    validates :description, length: { maximum: DESCRIPTION_MAX }
+
+    before_validation { self.app_name = Studio.app_name if app_name.blank? }
+
+    # A title/description write commits the row; an image attach does NOT touch
+    # it, so the controller busts explicitly after one (see bust_cache!).
+    after_commit { self.class.bust_cache! }
+
+    class << self
+      # This app's row, or an unsaved one — or nil when the table is not
+      # installed, because a model with no table cannot even be instantiated.
+      def current
+        return nil unless table_ready?
+
+        find_by(app_name: Studio.app_name) || new(app_name: Studio.app_name)
+      end
+
+      # This app's row, created on first write. The unique index makes a
+      # cold-start race raise RecordNotUnique for the loser; it re-reads.
+      def current!
+        find_or_create_by!(app_name: Studio.app_name)
+      rescue ActiveRecord::RecordNotUnique
+        find_by!(app_name: Studio.app_name)
+      end
+
+      # THE RESOLVED IDENTITY — what any caller should read:
+      #
+      #   Studio::SiteIdentity.resolved(base_url: request.base_url)
+      #   # => { title: "Turf Monster", description: "Skill-based pick'em...",
+      #   #      image_url: "https://.../og.png" }
+      #
+      # `image_url` is the operator's uploaded image, else the static fallback,
+      # else nil. It is absolute when it can be: a public service's own URL
+      # always is; a proxy path or a root-relative static path is joined to
+      # `base_url` when one is given, and left root-relative otherwise.
+      # Studio.site_identity is the same call.
+      def resolved(base_url: nil)
+        stored_values = stored
+        image = stored_values[:image_url] || stored_values[:image_path] || static_image
+        {
+          title: stored_values[:title] || Studio.site_title.presence || Studio.app_name.to_s,
+          description: stored_values[:description] || Studio.site_description.presence,
+          image_url: base_url ? Studio::LinkPreview.absolute_url(image, base_url: base_url) : image
+        }
+      end
+
+      # Only what the OPERATOR saved (nil where they saved nothing), with the
+      # image as a PERMANENT URL (a public service's own URL) or a host-relative
+      # PROXY path. Neither is a signed, expiring URL: an unfurler caches the
+      # og:image URL and re-fetches it days later. Cached; see CACHE_TTL.
+      #
+      # An app without the table is not cached as "nothing": the first request
+      # after the migration must see the table.
+      def stored
+        return empty_stored unless table_ready?
+
+        Rails.cache.fetch(cache_key_for_app, expires_in: CACHE_TTL) { compute_stored }
+      end
+
+      # Carry a DRAFTED default into the row, filling only what the operator has
+      # not already set — safe to run from db/seeds.rb or a release task on every
+      # deploy, because it never overwrites an operator's edit. Returns the row,
+      # or nil when the table is not installed yet.
+      #
+      #   Studio::SiteIdentity.seed!(title: "Turf Monster",
+      #                              description: "Skill-based pick'em contests.")
+      def seed!(title: nil, description: nil)
+        return nil unless table_ready?
+
+        row = current!
+        row.title = title if row.title.blank? && title.present?
+        row.description = description if row.description.blank? && description.present?
+        row.save! if row.changed?
+        row
+      end
+
+      def bust_cache!
+        Rails.cache.delete(cache_key_for_app)
+      rescue StandardError
+        nil
+      end
+
+      def cache_key_for_app
+        "#{CACHE_KEY_PREFIX}/#{Studio.app_name.to_s.parameterize}"
+      end
+
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+
+      # Whether an attachment's service answers a permanent public URL. A
+      # MirrorService never sets public? itself but delegates `url` to its
+      # primary, so ask the primary (turf-monster's R2 move depends on this).
+      def public_service?(service)
+        (service.respond_to?(:primary) ? service.primary : service).public?
+      rescue StandardError
+        false
+      end
+
+      # A permanent URL, or a host-relative proxy path, for any attachment or
+      # blob. Shared by the operator's image and a page override that hands in
+      # an attachment (a user's avatar), so both follow one rule.
+      def image_location(attachable)
+        return nil if attachable.nil?
+        return nil if attachable.respond_to?(:attached?) && !attachable.attached?
+
+        blob = attachable.respond_to?(:blob) ? attachable.blob : attachable
+        return nil if blob.nil?
+
+        if public_service?(blob.service)
+          { url: blob.url }
+        else
+          { path: Rails.application.routes.url_helpers.rails_storage_proxy_path(blob, only_path: true) }
+        end
+      end
+
+      # The app's own static card (public/og.png by default), used only when the
+      # file is really there — a missing one would be a broken image in every
+      # unfurl. Absolute URLs are trusted as given. Memoized per path for the
+      # life of the process: public/ is fixed at deploy.
+      def static_image
+        path = Studio.link_preview_fallback_image.to_s
+        return nil if path.empty?
+        return path unless path.start_with?("/") && !path.start_with?("//")
+
+        @static_files ||= Concurrent::Map.new
+        present = @static_files.compute_if_absent(path) do
+          File.file?(Rails.public_path.join(path.delete_prefix("/")))
+        end
+        present ? path : nil
+      end
+
+      def reset_static_image!
+        @static_files = nil
+      end
+
+      private
+
+      def empty_stored
+        { title: nil, description: nil, image_url: nil, image_path: nil }
+      end
+
+      def compute_stored
+        row = find_by(app_name: Studio.app_name)
+        return empty_stored if row.nil?
+
+        location = row.respond_to?(:image) ? image_location(row.image) : nil
+        {
+          title: row.title.presence,
+          description: row.description.presence,
+          image_url: location&.dig(:url),
+          image_path: location&.dig(:path)
+        }
+      end
+    end
+
+    def image_attached?
+      respond_to?(:image) && image.attached?
+    end
+
+    def name_slug
+      "site-identity-#{app_name.to_s.parameterize}"
+    end
+  end
+end

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

@@ -1,10 +1,12 @@
 <%# Avatar partial — shows attached image or colored initials circle
-    Locals: user (required), size: "sm" | "md" (default) | "lg" %>
+    Locals: user (required), size: "sm" | "nav" | "md" (default) | "lg" | "xl",
+            alt: the image's alt text (default user.display_name) %>
 <% size ||= "md" %>
-<% size_classes = { "sm" => "w-6 h-6 text-xs", "nav" => "w-8 h-8 text-xs", "md" => "w-10 h-10 text-sm", "lg" => "w-14 h-14 text-lg" }[size] %>
+<% alt = local_assigns[:alt].presence || user.display_name %>
+<% size_classes = { "sm" => "w-6 h-6 text-xs", "nav" => "w-8 h-8 text-xs", "md" => "w-10 h-10 text-sm", "lg" => "w-14 h-14 text-lg", "xl" => "w-28 h-28 text-4xl" }[size] %>
 
 <% if user.avatar.attached? %>
-  <%= image_tag user.avatar, class: "#{size_classes.split.first(2).join(' ')} rounded-full object-cover", alt: user.display_name %>
+  <%= image_tag user.avatar, class: "#{size_classes.split.first(2).join(' ')} rounded-full object-cover", alt: alt %>
 <% else %>
   <div class="<%= size_classes %> rounded-full flex items-center justify-center font-bold text-white"
        style="background-color: <%= user.avatar_color %>">

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

@@ -15,6 +15,12 @@
 <%= render "studio/session_stamp" %>
 <%= render "layouts/studio/smooth_load" %>
 <link rel="icon" type="image/png" href="/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
+    installed the studio_site_identities table, so an app that emits its
+    own tags gets no second set. See docs/LINK_PREVIEW.md. %>
+<%= studio_link_preview_tags if respond_to?(:studio_link_preview_tags) && Studio.link_preview_tags? %>
 
 <%= yield :head %>
 

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

@@ -0,0 +1,26 @@
+<%# locals: (preview:) — the Open Graph + Twitter tags an unfurl reads
+    (iMessage, Slack, Discord, X, WhatsApp...). `preview` is
+    Studio::LinkPreviewHelper#studio_link_preview: the page override, else the
+    operator default from /admin/link_preview, else the static fallback.
+    Lifted from turf-monster's layouts/_link_preview_meta. og:image is absolute
+    and permanent; the tag is omitted rather than emitted empty. %>
+<meta property="og:site_name" content="<%= preview[:site_name] %>">
+<meta property="og:type" content="website">
+<meta property="og:title" content="<%= preview[:title] %>">
+<% if preview[:description] %>
+<meta property="og:description" content="<%= preview[:description] %>">
+<% end %>
+<% if preview[:url] %>
+<meta property="og:url" content="<%= preview[:url] %>">
+<% end %>
+<% if preview[:image] %>
+<meta property="og:image" content="<%= preview[:image] %>">
+<% end %>
+<meta name="twitter:card" content="<%= preview[:image] ? "summary_large_image" : "summary" %>">
+<meta name="twitter:title" content="<%= preview[:title] %>">
+<% if preview[:description] %>
+<meta name="twitter:description" content="<%= preview[:description] %>">
+<% end %>
+<% if preview[:image] %>
+<meta name="twitter:image" content="<%= preview[:image] %>">
+<% end %>

data/app/views/studio/public_users/not_found.html.erb

@@ -0,0 +1,15 @@
+<%# The friendly 404 for /u/:username. Every miss renders this same page
+    (unknown, hidden by the host, or an app with no username column), so it
+    says nothing about why. Served with status 404. %>
+<% content_for(:title, "User not found") %>
+
+<div class="max-w-md mx-auto px-4 py-12" data-public-user-not-found>
+  <div class="card p-8 text-center">
+    <h1 class="text-xl font-bold text-heading mb-2">No one goes by that name here</h1>
+    <p class="text-secondary text-sm mb-6 break-all">
+      We couldn't find a user called <span class="font-semibold text-body"><%= @requested_username %></span>.
+      Check the spelling, or head back home.
+    </p>
+    <%= link_to "Go home", "/", class: "btn btn-primary" %>
+  </div>
+</div>

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

@@ -0,0 +1,28 @@
+<%# /u/:username — the public user page (Studio::PublicUsersController).
+
+    AVATAR AND USERNAME, NOTHING ELSE (operator's call, 2026-09-30). No name,
+    email or wallet, and the image alt is the username for the same reason:
+    _avatar's default alt is display_name, which a host may build from a name.
+
+    The preview is the avatar when one is attached; `link_preview image:` treats
+    an empty attachment as a blank rung, so an account with no picture unfurls
+    with the site identity's image. The avatar URL is the primitive's permanent
+    one (public service URL or the storage proxy), never a signed expiring URL.
+    The description is left to the site identity. %>
+<% username = @public_user.username.to_s %>
+<% content_for(:title, username) %>
+<% link_preview image: @public_user.avatar, title: username %>
+
+<div class="max-w-md mx-auto px-4 py-12" data-public-user="<%= username %>">
+  <div class="card p-8 flex flex-col items-center text-center gap-4">
+    <% if @public_user.avatar.attached? %>
+      <%= render "components/avatar", user: @public_user, size: "xl", alt: username %>
+    <% else %>
+      <%# Drawn from the username alone: a host's avatar_initials / avatar_color may read the name or email (cyvasse's do). %>
+      <% colors = Studio::UserProfile::AVATAR_COLORS %>
+      <div class="w-28 h-28 text-4xl rounded-full flex items-center justify-center font-bold text-white"
+           style="background-color: <%= colors[Digest::MD5.hexdigest(username).hex % colors.size] %>"><%= username[0].upcase %></div>
+    <% end %>
+    <h1 class="text-2xl font-bold text-heading break-all" data-public-user-username><%= username %></h1>
+  </div>
+</div>

data/app/views/studio/site_identities/edit.html.erb

@@ -0,0 +1,233 @@
+<%# /admin/link_preview — the operator edits the SITE IDENTITY
+    (Studio::SiteIdentity): the image, title and description an unfurl
+    (iMessage, Slack, Discord, X...) shows for any page of this app that does
+    not name its own, and the copy Studio.site_identity hands any other reader
+    (a meta description, share text, an email footer). Three parts,
+    in the order an operator asks: what does a link look like now, what picture
+    does it carry, and what words.
+
+    A bare content wrapper, like /admin/geo and /admin/emails, so it renders in
+    the host's layout. The crop and saving modals mount on a PAGE-SCOPED host
+    (linkPreviewModals), so the uploader works in an app that renders no shared
+    modal host at all — the /admin/emails pattern. %>
+<% content_for(:title) { "Link Preview" } %>
+<%
+  setting       = @setting
+  fallback_title = Studio.site_title.presence || Studio.app_name.to_s
+  fallback_desc  = Studio.site_description.to_s
+  card_title    = setting&.title.presence || fallback_title
+  card_desc     = setting&.description.presence || fallback_desc
+  card_image    = @default_image_url || @static_image_url
+  image_source  =
+    if @default_image_url then "the uploaded default"
+    elsif @static_image_url then "the app's static #{Studio.link_preview_fallback_image}"
+    else nil
+    end
+  tags_on       = Studio.link_preview_tags?
+%>
+<style>
+  /* The unfurl card. Plain CSS rather than utilities, so no host build has to
+     scan this gem for these names. Drawn the way iMessage and Slack draw a
+     large-image card: the picture at 1.91:1, then the domain, title and
+     description underneath. */
+  .lp-card {
+    max-width: 440px;
+    border-radius: 14px;
+    overflow: hidden;
+    border: 1px solid rgb(148 163 184 / 0.3);
+    background: rgb(148 163 184 / 0.08);
+  }
+  .lp-card-image {
+    aspect-ratio: 1200 / 630;
+    background: linear-gradient(135deg, var(--color-primary-700), var(--color-primary-900));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .lp-card-image img { width: 100%; height: 100%; object-fit: cover; display: block; }
+  .lp-card-body { padding: 10px 14px 12px; }
+  .lp-card-domain { font-size: 11px; letter-spacing: 0.04em; text-transform: uppercase; opacity: 0.7; }
+  .lp-card-title { font-weight: 700; line-height: 1.3; margin-top: 2px; }
+  .lp-card-desc {
+    font-size: 13px; line-height: 1.4; opacity: 0.8; margin-top: 2px;
+    display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;
+  }
+  .lp-card-desc:empty { display: none; }
+</style>
+
+<%# x-data on the root is load-bearing: studio/modals/scoped_host declares no
+    Alpine scope of its own, so without one here the crop modal's store opens
+    and its dialog never appears in a host whose body carries no x-data
+    (e2e/site_identity.spec.js). %>
+<div class="max-w-3xl mx-auto" x-data data-link-preview-page
+     data-fallback-title="<%= fallback_title %>"
+     data-fallback-description="<%= fallback_desc %>">
+  <h1 class="text-2xl font-extrabold text-heading mb-2">Link Preview</h1>
+  <p class="text-sm text-muted mb-6">
+    What a link to <%= Studio.app_name %> shows when it is pasted into Messages, Slack, Discord or X.
+    Any page can override it with its own picture and words (a contest banner, a profile photo);
+    everything else uses this default.
+  </p>
+
+  <% unless @installed %>
+    <div class="card p-6 mb-6" data-link-preview-not-installed>
+      <h2 class="text-lg font-bold text-heading mb-2">Not installed yet</h2>
+      <p class="text-sm text-body mb-3">
+        This app has not installed the site identity table, so there is nothing to edit yet and the
+        engine's preview tags are <%= tags_on ? "on, using the static fallback" : "off" %>. Install it with:
+      </p>
+      <pre class="bg-inset rounded-lg p-3 text-xs font-mono overflow-x-auto">bin/rails g studio:site_identity &amp;&amp; bin/rails db:migrate</pre>
+      <p class="text-xs text-muted mt-3">
+        An app that already writes its own og tags sets <span class="font-mono">config.link_preview_tags = false</span>
+        first. See docs/LINK_PREVIEW.md in studio-engine.
+      </p>
+    </div>
+  <% end %>
+
+  <%# -- The card, as an unfurl draws it ------------------------------------ %>
+  <div class="card p-6 mb-6">
+    <h2 class="text-lg font-bold text-heading mb-4">Preview</h2>
+    <div class="lp-card" data-link-preview-card>
+      <div class="lp-card-image">
+        <% if card_image %>
+          <img src="<%= card_image %>" alt="" data-link-preview-card-image>
+        <% else %>
+          <span class="text-xs text-white text-center px-4" data-link-preview-card-no-image>No image — links preview without a picture</span>
+        <% end %>
+      </div>
+      <div class="lp-card-body">
+        <div class="lp-card-domain" data-link-preview-card-domain><%= @domain %></div>
+        <div class="lp-card-title text-heading" data-link-preview-card-title><%= card_title %></div>
+        <div class="lp-card-desc text-body" data-link-preview-card-description><%= card_desc %></div>
+      </div>
+    </div>
+    <p class="text-xs text-muted mt-3">
+      <% if image_source %>
+        The picture is <%= image_source %>.
+      <% else %>
+        No default picture yet. Upload one below, or add <span class="font-mono">public/og.png</span> (1200 × 630).
+      <% end %>
+      <% unless tags_on %>
+        The engine's preview tags are <strong>off</strong> in this app
+        (<span class="font-mono">Studio.link_preview_tags</span>), so pages use the app's own tags<% if (own = Studio.link_preview_own_tags_file) %>, which
+        <span class="font-mono"><%= own.to_s.delete_prefix("#{Rails.root}/") %></span> writes<% end %>.
+      <% end %>
+    </p>
+  </div>
+
+  <% if @installed %>
+    <%# -- The picture -------------------------------------------------------- %>
+    <div class="card p-6 mb-6"
+      <% if @uploads_available %>
+        x-data="imageUploadHost({
+          store: 'linkPreviewModals',
+          aspectRatio: <%= 1200.0 / 630 %>,
+          maxWidth: 1200,
+          transparent: false,
+          filename: 'link-preview.png',
+          saving: 'Saving image…',
+          success: 'Image updated',
+          successMessage: 'Your new link-preview image is live.',
+          failure: 'Couldn\'t save the image'
+        })"
+        @crop-photo-confirmed.window="onCropConfirmed($event.detail)"
+      <% end %>>
+      <h2 class="text-lg font-bold text-heading mb-2">Image</h2>
+      <% if @uploads_available %>
+        <p class="text-sm text-muted mb-4">
+          Cropped to 1200 × 630, the shape every unfurl uses. It is served from a permanent URL, because
+          apps cache the picture and fetch it again days later.
+        </p>
+        <div class="flex flex-wrap gap-3 items-center">
+          <button type="button" @click="open()" class="btn btn-primary btn-sm" data-link-preview-upload>
+            <%= setting.image_attached? ? "Replace image" : "Upload image" %>
+          </button>
+          <% if setting.persisted? && setting.image_attached? %>
+            <%= button_to "Remove image", admin_link_preview_image_path, method: :delete,
+                  class: "btn btn-outline btn-sm",
+                  form: { data: { turbo_confirm: "Remove the default link-preview image?" } } %>
+          <% end %>
+        </div>
+        <%# The upload host writes the cropped file into THIS input and submits it
+            (see studio/emails/show for why the pair is load-bearing). %>
+        <%= form_with url: admin_link_preview_path, method: :patch,
+              html: { multipart: true, id: "link-preview-image-form", "x-ref": "form" } do %>
+          <%= file_field_tag "site_identity[image]", class: "hidden", "x-ref": "fileInput",
+                accept: Studio::SiteIdentity::IMAGE_TYPES.join(",") %>
+        <% end %>
+      <% else %>
+        <p class="text-sm text-muted">
+          Uploading needs Active Storage, which this app does not load. Pages still use the static
+          <span class="font-mono"><%= Studio.link_preview_fallback_image %></span>.
+        </p>
+      <% end %>
+    </div>
+
+    <%# -- The words --------------------------------------------------------- %>
+    <%# scope: :site_identity is REQUIRED: a namespaced model's param key
+        is studio_site_identity, which the controller never reads. %>
+    <%= form_with(model: setting, scope: :site_identity, url: admin_link_preview_path,
+                  method: :patch, local: true) do |f| %>
+      <div class="card p-6 mb-6">
+        <h2 class="text-lg font-bold text-heading mb-1">Site title and description</h2>
+        <p class="text-sm text-muted mb-4">
+          What <%= Studio.app_name %> is, in its own words. Link previews use them, and so can the rest
+          of the app (<span class="font-mono">Studio.site_identity</span>): a meta description, share
+          text, an email footer.
+        </p>
+        <div class="mb-4">
+          <%= f.label :title, "Title", class: "block text-sm font-bold text-heading mb-1" %>
+          <%= f.text_field :title, class: "input w-full", placeholder: fallback_title,
+                maxlength: Studio::SiteIdentity::TITLE_MAX, data: { link_preview_input: "title" } %>
+          <p class="text-xs text-muted mt-1">Blank uses the drafted default: <%= fallback_title %>.</p>
+        </div>
+        <div>
+          <%= f.label :description, "Description", class: "block text-sm font-bold text-heading mb-1" %>
+          <%= f.text_area :description, rows: 3, class: "input w-full", placeholder: fallback_desc.presence,
+                maxlength: Studio::SiteIdentity::DESCRIPTION_MAX, data: { link_preview_input: "description" } %>
+          <p class="text-xs text-muted mt-1">One or two sentences. Unfurls show about two lines.</p>
+        </div>
+      </div>
+      <div class="flex justify-end mb-6">
+        <%= f.submit "Save", class: "btn btn-primary" %>
+      </div>
+    <% end %>
+
+    <% if @uploads_available %>
+      <%= render "studio/cropper_assets" %>
+      <%# Optional chaining on current() is load-bearing: the outer template
+          unmounts one tick AFTER the stack empties (see studio/emails/index). %>
+      <%= render "studio/modals/scoped_host", store: "linkPreviewModals" do %>
+        <template x-if="$store.linkPreviewModals.current()?.id === 'crop-photo'">
+          <div><%= render "studio/modals/crop_photo", store: "linkPreviewModals" %></div>
+        </template>
+        <template x-if="$store.linkPreviewModals.current()?.id === 'saving'">
+          <div><%= render "studio/modals/saving", store: "linkPreviewModals" %></div>
+        </template>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>
+
+<script>
+  // LIVE CARD. Typing in the title or description repaints the card before
+  // anything is saved, falling back to what a blank field would really send.
+  (function () {
+    var page = document.querySelector("[data-link-preview-page]");
+    if (!page) return;
+    var fallbacks = {
+      title: page.dataset.fallbackTitle || "",
+      description: page.dataset.fallbackDescription || ""
+    };
+    function paint(input) {
+      var key = input.dataset.linkPreviewInput;
+      var target = page.querySelector("[data-link-preview-card-" + key + "]");
+      if (!target) return;
+      var value = input.value.trim();
+      target.textContent = value || fallbacks[key];
+    }
+    page.querySelectorAll("[data-link-preview-input]").forEach(function (input) {
+      input.addEventListener("input", function () { paint(input); });
+    });
+  })();
+</script>

data/db/migrate/20260930120000_create_studio_site_identities.rb

@@ -0,0 +1,30 @@
+# The SITE IDENTITY for one app: the title, description and image that say what
+# the app is. An unfurl (iMessage, Slack, Discord, X...) shows them for any page
+# that does not name its own, and Studio.site_identity hands the same copy to any
+# other reader. The operator edits them at /admin/link_preview.
+#
+# One row per app (Studio.app_name), like studio_geo_settings. The IMAGE is not a
+# column: it is an Active Storage attachment (Studio::SiteIdentity#image),
+# which rides the host's active_storage_* tables.
+#
+# INSTALLING THIS TABLE TURNS THE ENGINE'S HEAD TAGS ON under the default
+# Studio.link_preview_tags = :auto — unless a template under the app's
+# app/views writes its own og:title/og:image, in which case :auto stays off
+# until the app deletes them (or sets link_preview_tags = true).
+class CreateStudioSiteIdentities < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_site_identities do |t|
+      t.string :app_name, null: false
+      t.string :title
+      t.text   :description
+
+      # Sluggable, like every other Studio settings row.
+      t.string :slug
+
+      t.timestamps
+    end
+
+    add_index :studio_site_identities, :app_name, unique: true
+    add_index :studio_site_identities, :slug, unique: true
+  end
+end