studio-engine 0.81.1 → 0.82.0

data/lib/generators/studio/site_identity/site_identity_generator.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Studio
+  module Generators
+    # Adopt the site identity + link-preview primitive in one repeatable step:
+    #
+    #   bin/rails g studio:site_identity \
+    #     --title "Turf Monster" \
+    #     --description "Skill-based pick'em contests with transparent payouts."
+    #   bin/rails db:migrate
+    #
+    # What it does, each step idempotent (a second run changes nothing):
+    #
+    #   1. copies the engine's studio_site_identities migration into
+    #      db/migrate, in exactly the form `studio_engine:install:migrations`
+    #      writes (so that task later sees it and skips it) — and ONLY that
+    #      migration, not every pending engine migration;
+    #   2. writes the DRAFTED title and description into
+    #      config/initializers/studio.rb as config.site_title /
+    #      config.site_description (the standing convention: an agent drafts them
+    #      when it sets an app up, Alex edits them at /admin/link_preview);
+    #   3. includes Studio::LinkPreviewBots in ApplicationController, so preview
+    #      fetchers get the slim page under Apple's 1 MiB limit.
+    #
+    # --own-tags is for an app that still writes its own og tags (turf-monster,
+    # cyvasse): it sets config.link_preview_tags = false, so installing the table
+    # does not add a second set before the app's own are deleted.
+    class SiteIdentityGenerator < Rails::Generators::Base
+      MIGRATION_NAME = "create_studio_site_identities"
+      ENGINE_SCOPE = "studio_engine"
+      INITIALIZER = "config/initializers/studio.rb"
+      CONTROLLER = "app/controllers/application_controller.rb"
+
+      class_option :title, type: :string, desc: "The drafted site title (config.site_title)"
+      class_option :description, type: :string, desc: "The drafted site description (config.site_description)"
+      class_option :own_tags, type: :boolean, default: false,
+                              desc: "This app still writes its own og tags: set config.link_preview_tags = false"
+      class_option :skip_bots, type: :boolean, default: false,
+                               desc: "Do not include Studio::LinkPreviewBots in ApplicationController"
+
+      def copy_migration
+        existing = Dir.glob(File.join(destination_root, "db/migrate/*_#{MIGRATION_NAME}{,.#{ENGINE_SCOPE}}.rb"))
+        if existing.any?
+          say_status :identical, relative(existing.first), :blue
+          return
+        end
+
+        source = self.class.engine_migration
+        original_version = File.basename(source)[/\A\d+/]
+        body = "# This migration comes from #{ENGINE_SCOPE} (originally #{original_version})\n#{File.read(source)}"
+        create_file "db/migrate/#{self.class.next_version}_#{MIGRATION_NAME}.#{ENGINE_SCOPE}.rb", body
+      end
+
+      def configure_initializer
+        path = File.join(destination_root, INITIALIZER)
+        unless File.exist?(path)
+          say_status :skip, "#{INITIALIZER} not found — add the site_title/site_description lines by hand", :yellow
+          return
+        end
+
+        content = File.read(path)
+        if content.include?("config.site_title")
+          say_status :identical, "#{INITIALIZER} (config.site_title already set)", :blue
+          return
+        end
+
+        anchor = content[/^Studio\.configure do \|(\w+)\|\n/]
+        unless anchor
+          say_status :skip, "#{INITIALIZER} has no `Studio.configure do |config|` block", :yellow
+          return
+        end
+
+        inject_into_file INITIALIZER, initializer_block(anchor[/\|(\w+)\|/, 1]), after: anchor
+      end
+
+      def include_bot_concern
+        return if options[:skip_bots]
+
+        path = File.join(destination_root, CONTROLLER)
+        return say_status(:skip, "#{CONTROLLER} not found", :yellow) unless File.exist?(path)
+        return say_status(:identical, "#{CONTROLLER} (Studio::LinkPreviewBots)", :blue) if File.read(path).include?("Studio::LinkPreviewBots")
+
+        inject_into_class CONTROLLER, "ApplicationController", <<~RUBY
+          # Preview fetchers (iMessage, Slack, Discord, X...) get a slim page under
+          # Apple's 1 MiB limit. studio-engine docs/LINK_PREVIEW.md.
+          include Studio::LinkPreviewBots
+        RUBY
+      end
+
+      def next_steps
+        say <<~TEXT
+
+          Site identity installed. Next:
+            bin/rails db:migrate
+            Visit /admin/link_preview to set the image and edit the title and description.
+          Read the copy anywhere with Studio.site_identity (or studio_site_identity in a view).
+        TEXT
+      end
+
+      def self.engine_migration
+        File.expand_path("../../../../db/migrate/20260930120000_#{MIGRATION_NAME}.rb", __dir__)
+      end
+
+      def self.next_version
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      private
+
+      def relative(path)
+        path.delete_prefix("#{destination_root}/")
+      end
+
+      def initializer_block(var)
+        title = options[:title].to_s.strip
+        description = options[:description].to_s.strip
+        lines = []
+        lines << ""
+        lines << "  # ---- Site identity + link preview (studio-engine docs/LINK_PREVIEW.md) ----"
+        lines << "  # The DRAFTED title and description; the operator edits them at"
+        lines << "  # /admin/link_preview, and Studio.site_identity reads the result."
+        lines << (title.empty? ? "  # #{var}.site_title = \"Draft the site title\"" : "  #{var}.site_title = #{title.inspect}")
+        lines << (description.empty? ? "  # #{var}.site_description = \"Draft one or two sentences\"" : "  #{var}.site_description = #{description.inspect}")
+        if options[:own_tags]
+          lines << "  # This app still writes its own og tags. Delete them, then remove this line."
+          lines << "  #{var}.link_preview_tags = false"
+        end
+        lines << ""
+        lines.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/studio/link_preview.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Studio
+  # The house link-preview primitive: what an unfurl (iMessage, Slack, Discord,
+  # X, WhatsApp...) shows when someone pastes a link to this app.
+  #
+  # Deliberately PURE, like Studio::Geo: plain strings in, plain strings and
+  # hashes out, no request and no database. The pieces that need the world live
+  # beside it:
+  #
+  #   Studio::SiteIdentity  (model) the operator's default image, title and
+  #                               description, set at /admin/link_preview
+  #   Studio::LinkPreviewHelper   (view helper) the page override
+  #                               (`link_preview`) and the tags the head renders
+  #   Studio::LinkPreviewBots     (controller concern) the slim document preview
+  #                               fetchers get instead of the full page
+  #
+  # Lifted from turf-monster (OgHelper, SiteSetting, OgImageAttachable and the
+  # app-local LinkPreviewBot of task imessage-link-preview-fix), which carried
+  # all of this in production first. See docs/LINK_PREVIEW.md.
+  module LinkPreview
+    # Apple's LinkPresentation (the iMessage unfurler, which runs on the SENDER's
+    # phone) aborts any HTML page over this many bytes with WebKitErrorDomain 102,
+    # "Frame load interrupted". Measured 2026-09-30: 1,048,000 bytes previewed,
+    # 1,049,000 failed. The slim document is held under it.
+    MAX_DOCUMENT_BYTES = 1_048_576
+
+    # The preview fetchers, by User-Agent token. An ALLOW-LIST: only an agent
+    # named here gets the slim document; a person, or an agent nobody named,
+    # always gets the full page. Each token is a product's own FETCHER, not its
+    # in-app browser: Facebook's in-app browser sends FBAN/FBAV, LinkedIn's sends
+    # LinkedInApp, X's sends "Twitter for iPhone", and none of those match.
+    #
+    # iMessage has no token of its own. LinkPresentation sends an old-Safari UA
+    # suffixed "facebookexternalhit/1.1 Facebot Twitterbot/1.0", so it rides the
+    # Facebook and X tokens.
+    BOT_TOKENS = [
+      "facebookexternalhit",    # Facebook, Messenger; also Apple LinkPresentation (iMessage)
+      "Facebot",                # Facebook; also iMessage
+      "Twitterbot",             # X; also iMessage
+      "Discordbot",
+      "Slackbot-LinkExpanding",
+      "LinkedInBot",
+      "WhatsApp/",              # the fetcher sends WhatsApp/<version>
+      "TelegramBot",
+      "Applebot",               # Siri / Spotlight suggestions
+      "SkypeUriPreview",        # Skype and Teams
+      "redditbot",
+      "Embedly"
+    ].freeze
+
+    BOT_PATTERN = Regexp.union(BOT_TOKENS.map { |token| /#{Regexp.escape(token)}/i }).freeze
+
+    # What the slim document keeps from the page's head. Everything a fetcher
+    # reads for a card, and nothing it executes: no script, style or template.
+    KEPT_META_NAMES = %w[
+      description robots theme-color application-name author keywords
+    ].freeze
+    KEPT_LINK_RELS = %w[
+      canonical icon shortcut\ icon apple-touch-icon apple-touch-icon-precomposed manifest mask-icon image_src
+    ].freeze
+
+    module_function
+
+    # The first view template under `views_root` that writes its own og:title or
+    # og:image, or nil. Studio.link_preview_tags? asks this under :auto, so an
+    # app that still writes its own preview tags (turf-monster's
+    # layouts/_link_preview_meta, cyvasse's layouts/_seo) does not get a second
+    # set the day it installs the engine's migrations — which docs/
+    # NEW_APP_SETUP.md tells every app to do after every upgrade.
+    #
+    # Deliberately BROAD: any mention counts, a comment included. A false
+    # positive only keeps the engine's tags off (an app sets
+    # link_preview_tags = true to override); a false negative would double them.
+    OWN_TAG_PATTERN = /og:(?:title|image)\b/
+    TEMPLATE_GLOB = "**/*.{erb,haml,slim}"
+
+    def own_tag_file(views_root)
+      root = views_root.to_s
+      return nil if root.empty? || !File.directory?(root)
+
+      Dir.glob(File.join(root, TEMPLATE_GLOB)).sort.find do |path|
+        File.read(path, encoding: "UTF-8").scrub.match?(OWN_TAG_PATTERN)
+      rescue SystemCallError
+        false
+      end
+    end
+
+    # Is this User-Agent a link-preview fetcher? Blank is never a bot.
+    def bot?(user_agent)
+      ua = user_agent.to_s
+      return false if ua.strip.empty?
+
+      BOT_PATTERN.match?(ua)
+    end
+
+    # THE RESOLUTION CHAIN. Each argument is a list of rungs, most specific
+    # first; the first present rung wins.
+    #
+    #   title        page override(s) -> operator default -> site name
+    #   description  page override(s) -> operator default -> none (tag omitted)
+    #   image        page override(s) -> operator default -> static fallback -> none
+    #
+    # A page override with NO image (a user with no avatar) is simply a blank
+    # rung, so it falls through to the default: that is the whole override rule.
+    # `image_source` says which rung answered (:page, :default, :static, :none).
+    def resolve(site_name:, titles: [], descriptions: [], page_images: [], default_image: nil, static_image: nil)
+      page_image = first_present(page_images)
+      image, source =
+        if page_image then [page_image, :page]
+        elsif present?(default_image) then [default_image.to_s, :default]
+        elsif present?(static_image) then [static_image.to_s, :static]
+        else [nil, :none]
+        end
+
+      {
+        title: first_present(titles) || site_name.to_s,
+        description: first_present(descriptions),
+        image: image,
+        image_source: source
+      }
+    end
+
+    # An image URL a fetcher can follow from anywhere. Unfurlers resolve nothing
+    # relative, so a root-relative path is joined to the request's base URL; a
+    # protocol-relative one is given https. Absolute URLs pass through.
+    def absolute_url(url, base_url:)
+      value = url.to_s.strip
+      return nil if value.empty?
+      return "https:#{value}" if value.start_with?("//")
+      return "#{base_url.to_s.chomp("/")}#{value}" if value.start_with?("/")
+
+      value
+    end
+
+    # The whole response a preview fetcher gets: the page's own identity tags,
+    # lifted out of its <head>, and a one-card body. Built FROM the rendered
+    # page, so the slim document cannot drift from what a person's page says.
+    #
+    # DUPLICATE-SAFE: a meta tag named twice (an app emitting its own og tags
+    # AND the engine's) is kept once, the FIRST occurrence — the one the page
+    # put first, which is the one an app that owns its tags writes.
+    def slim_document(html, url: nil)
+      source = html.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      head = source[%r{<head\b[^>]*>(.*?)</head\s*>}mi, 1] || source
+      head = head.gsub(%r{<(script|style|template|noscript)\b.*?</\1\s*>}mi, "").gsub(/<!--.*?-->/m, "")
+      lang = source[/<html\b[^>]*\blang\s*=\s*["']([^"']+)["']/i, 1]
+      title = head[%r{<title\b[^>]*>(.*?)</title\s*>}mi, 1]&.strip
+
+      tags = kept_tags(head)
+      document = build_document(tags, title: title, lang: lang, url: url)
+      return document if document.bytesize < MAX_DOCUMENT_BYTES
+
+      # A head that is itself enormous (an inline data: icon, say). Keep only
+      # what an unfurl card is made of.
+      core = tags.select { |tag| tag_key(tag).to_s.match?(/\A(og:|twitter:|description\z)/) }
+      build_document(core, title: title, lang: lang, url: url)
+    end
+
+    def kept_tags(head)
+      seen = {}
+      head.scan(/<meta\b[^>]*>|<link\b[^>]*>/i).select do |tag|
+        next false unless keep_tag?(tag)
+
+        key = tag_key(tag)
+        next true if key.nil?
+        next false if seen[key]
+
+        seen[key] = true
+      end
+    end
+
+    def keep_tag?(tag)
+      if tag.match?(/\A<link/i)
+        rel = attribute(tag, "rel").to_s.downcase.strip
+        return KEPT_LINK_RELS.include?(rel)
+      end
+      return false if attribute(tag, "charset") # the document writes its own
+
+      property = attribute(tag, "property").to_s
+      return true unless property.empty?
+
+      name = attribute(tag, "name").to_s.downcase
+      name.start_with?("twitter:") || KEPT_META_NAMES.include?(name)
+    end
+
+    # The identity a duplicate is judged by: a meta's property or name, a link's
+    # rel. Case-folded, because <meta name="Description"> is the same claim.
+    def tag_key(tag)
+      if tag.match?(/\A<link/i)
+        rel = attribute(tag, "rel")
+        return rel ? "link:#{rel.downcase}:#{attribute(tag, "sizes")}" : nil
+      end
+      (attribute(tag, "property") || attribute(tag, "name"))&.downcase
+    end
+
+    def attribute(tag, name)
+      tag[/\s#{Regexp.escape(name)}\s*=\s*"([^"]*)"/i, 1] || tag[/\s#{Regexp.escape(name)}\s*=\s*'([^']*)'/i, 1]
+    end
+
+    def build_document(tags, title:, lang:, url:)
+      og_title = content_of(tags, "og:title") || title
+      og_description = content_of(tags, "og:description") || content_of(tags, "description")
+      lang_attr = lang ? %( lang="#{ERB::Util.html_escape(lang)}") : ""
+
+      body = +""
+      body << "<h1>#{og_title}</h1>\n" if og_title
+      body << "<p>#{og_description}</p>\n" if og_description
+      body << %(<p><a href="#{ERB::Util.html_escape(url)}">#{og_title || ERB::Util.html_escape(url)}</a></p>\n) if url
+
+      <<~HTML
+        <!DOCTYPE html>
+        <html#{lang_attr}>
+        <head>
+        <meta charset="utf-8">
+        #{"<title>#{title}</title>\n" if title}#{tags.join("\n")}
+        </head>
+        <body>
+        #{body}</body>
+        </html>
+      HTML
+    end
+
+    # Already escaped: the value came out of a rendered attribute, so it is
+    # emitted back into markup exactly as the page wrote it.
+    def content_of(tags, key)
+      tag = tags.find { |t| tag_key(t) == key }
+      tag && attribute(tag, "content")
+    end
+
+    def first_present(values)
+      Array(values).each do |value|
+        return value.to_s.strip if present?(value)
+      end
+      nil
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+  end
+end

data/lib/studio/public_user.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Studio
+  # The public user page's two rules, in one place: which account a /u/:username
+  # URL names, and which username a link to an account carries.
+  #
+  # THE KEY IS `username` AND NOTHING ELSE. It is the one identity field a person
+  # chose to show other people. The hub apps' `slug` is keyed on the email, and a
+  # lookup by email would tell a stranger whether an address has an account, so
+  # neither ever stands in: an app without a username column serves no public
+  # pages (every lookup misses, every link helper answers nil) until it adds one.
+  #
+  # Pure lookups, no request: Studio::PublicUsersController and
+  # Studio::PublicUserHelper both call these, so the page and the links to it
+  # cannot disagree about what a username is.
+  module PublicUser
+    COLUMN = "username"
+
+    module_function
+
+    # Whether the host's User model can have a public page at all.
+    def supported?(user_class = default_user_class)
+      return false if user_class.nil?
+
+      user_class.respond_to?(:column_names) && user_class.column_names.include?(COLUMN)
+    rescue StandardError
+      false
+    end
+
+    # The account a /u/:username URL names, or nil. Case-insensitive: /u/Alex
+    # and /u/alex are the same page. An exact match wins first, because an app
+    # whose lower(username) index is not unique (cyvasse's) can hold "Alex" and
+    # "alex" as two people, and the one who is exactly named should get the page.
+    #
+    # A host that must hide an account (frozen, merged away, banned) defines
+    # `public_profile_visible?` on User; false answers nil, the same miss an
+    # unknown username gets, so the page never says why.
+    def find(username, user_class: default_user_class)
+      name = username.to_s.strip
+      return nil if name.empty? || !supported?(user_class)
+
+      user = user_class.find_by(COLUMN => name) ||
+             user_class.where(user_class.arel_table[COLUMN].lower.eq(name.downcase)).order(:id).first
+      return nil if user.nil?
+      return nil if user.respond_to?(:public_profile_visible?) && !user.public_profile_visible?
+
+      user
+    end
+
+    # The username a link to this account carries, or nil when it has none.
+    # Takes a user, or a username string as given.
+    def username_for(user_or_username)
+      value = if user_or_username.is_a?(String) || user_or_username.is_a?(Symbol)
+                user_or_username.to_s
+              elsif user_or_username.respond_to?(COLUMN)
+                user_or_username.public_send(COLUMN).to_s
+              end
+      value&.strip.presence
+    end
+
+    def default_user_class
+      defined?(::User) ? ::User : nil
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.81.1"
+  VERSION = "0.82.0"
 end

data/lib/studio.rb

@@ -3,6 +3,7 @@ require "studio/log_rotation"
 require "studio/ip_locations"
 require "studio/geo"
 require "studio/geo/lookup"
+require "studio/link_preview"
 require "studio/engine"
 require "studio/color_scale"
 require "studio/environment_banner"
@@ -19,6 +20,7 @@ require "studio/profile_image"
 require "studio/oauth_identity"
 require "studio/newsletter"
 require "studio/username_generator"
+require "studio/public_user"
 require "studio/name_parts"
 require "studio/s3"
 require "studio/image_cache"
@@ -471,6 +473,125 @@ module Studio
   # is loading — taking its entire route set down, not just this page.
   mattr_accessor :draw_geo_routes, default: false
 
+  # ---- Link preview (Studio::LinkPreview, SiteIdentity, LinkPreviewHelper)
+  #
+  # What an unfurl shows when someone pastes a link to this app: the SITE
+  # IDENTITY (Studio::SiteIdentity — image, title, description) the operator sets
+  # at /admin/link_preview, which any page may override (`link_preview image:
+  # ..., title: ...`). See docs/LINK_PREVIEW.md.
+
+  # Whether layouts/studio/_head emits the og:/twitter: tags.
+  #
+  #   :auto (default)  emit once this app has INSTALLED the engine's
+  #                    studio_site_identities table — installing the
+  #                    migration is the adoption act — and no template under
+  #                    app/views writes its own og:title/og:image. An app that
+  #                    emits its own tags (turf-monster, cyvasse) gets no second
+  #                    set, even after `install:migrations` brings the table in.
+  #   true             always emit (the static fallback and the site name still
+  #                    answer with no table).
+  #   false            never emit from the head; the app renders
+  #                    `studio_link_preview_tags` itself, or owns its tags.
+  #
+  # An app whose own tags live somewhere the scan cannot see (a helper that
+  # builds them in Ruby) sets this false until its adoption deletes them.
+  mattr_accessor :link_preview_tags, default: :auto
+
+  # The Active Storage service the DEFAULT image is attached to. nil = the app's
+  # default service. Unfurlers cache the og:image URL and re-fetch it days later,
+  # so the tag must be a PERMANENT URL: a service whose `public?` is true answers
+  # its own public URL; any other service is served through Rails' storage PROXY
+  # route (a permanent URL on this app's own domain, streaming from the private
+  # bucket). An app with a public-read service names it here, e.g. turf-monster:
+  #
+  #   config.link_preview_image_service = OgImageAttachable::PUBLIC_OG_SERVICE
+  #
+  # Read once, when Studio::SiteIdentity loads (has_one_attached's service
+  # is a literal fixed at class load), so set it in the initializer.
+  mattr_accessor :link_preview_image_service, default: nil
+
+  # The last image rung, when neither the page nor the operator supplied one. A
+  # root-relative path is used only when the file exists under public/, so an app
+  # without it emits no og:image rather than a broken one. An absolute URL is
+  # trusted as given.
+  mattr_accessor :link_preview_fallback_image, default: "/og.png"
+
+  # THE SITE IDENTITY'S DRAFTED DEFAULTS — this app's title and description as
+  # written in code, under whatever the operator saves at /admin/link_preview.
+  # The standing convention is that an agent drafts these when it sets an app up
+  # (`bin/rails g studio:site_identity --title "..." --description "..."` writes
+  # them here) and Alex edits them on the page. nil title means Studio.app_name;
+  # nil description means none. Read the resolved answer through
+  # Studio.site_identity, never these directly.
+  mattr_accessor :site_title, default: nil
+  mattr_accessor :site_description, default: nil
+
+  # Draw /admin/link_preview from Studio.routes. ON by default: no consumer owns
+  # these paths or helper names (admin_link_preview, admin_link_preview_image),
+  # checked 2026-09-30 across mcritchie-studio, turf-monster, cyvasse and
+  # mcritchie-industries. The page explains itself when the table is missing.
+  mattr_accessor :draw_link_preview_routes, default: true
+
+  # Draw the public user page, GET /u/:username (Studio::PublicUsersController,
+  # route helper studio_public_user_path; link to it with the view helpers
+  # studio_user_profile_path(user) / link_to_user_profile(user)). See
+  # docs/PUBLIC_USER_PAGE.md.
+  #
+  # OFF by default, like every route surface a consumer might already own. No
+  # consumer owns /u or the helper name today (checked 2026-09-30 across
+  # mcritchie-studio, mcritchie-industries, cyvasse and turf-monster), but the
+  # page also needs a `username` column, which the two hub apps do not have yet
+  # (their slug is keyed on the email, so it can never stand in). Each app's
+  # adoption turns it on:
+  #
+  #   config.draw_public_user_routes = true
+  mattr_accessor :draw_public_user_routes, default: false
+
+  # THE APP'S IDENTITY COPY, resolved: { title:, description:, image_url: }.
+  # The operator's saved value (Studio::SiteIdentity, edited at
+  # /admin/link_preview) wins, then the drafted Studio.site_title /
+  # site_description, then Studio.app_name for the title. image_url is the
+  # uploaded image, else the static fallback, else nil — absolute when
+  # `base_url` is given (pass request.base_url) or the image lives on a public
+  # service. Reuse it anywhere the app needs to say what it is: a meta
+  # description, share text, an email footer. Views have `studio_site_identity`.
+  # Never raises; an app without the table answers from the drafted defaults.
+  def self.site_identity(base_url: nil)
+    Studio::SiteIdentity.resolved(base_url: base_url)
+  rescue StandardError
+    { title: site_title.presence || app_name.to_s, description: site_description.presence, image_url: nil }
+  end
+
+  # :auto emits when the table is installed AND no view of this app writes its
+  # own og tags (Studio.link_preview_own_tags_file); true/false are taken as
+  # given.
+  def self.link_preview_tags?
+    case link_preview_tags
+    when :auto, "auto", nil then Studio::SiteIdentity.table_ready? && link_preview_own_tags_file.nil?
+    else !!link_preview_tags
+    end
+  rescue StandardError
+    false
+  end
+
+  # The host view that writes its own og tags, or nil — scanned once per process
+  # (app/views is fixed at deploy) and logged once when it keeps :auto off.
+  def self.link_preview_own_tags_file
+    return @link_preview_own_tags_file if defined?(@link_preview_own_tags_file)
+
+    views = defined?(Rails.root) && Rails.root ? Rails.root.join("app/views") : nil
+    found = Studio::LinkPreview.own_tag_file(views)
+    if found && defined?(Rails.logger) && Rails.logger
+      Rails.logger.info("[studio.link_preview] #{found} writes its own og tags, so the engine's head tags " \
+                        "stay off under link_preview_tags = :auto. Set it to true once they are removed.")
+    end
+    @link_preview_own_tags_file = found
+  end
+
+  def self.reset_link_preview_own_tags!
+    remove_instance_variable(:@link_preview_own_tags_file) if defined?(@link_preview_own_tags_file)
+  end
+
   # Whether the engine configures Geocoder on boot (provider, HTTPS, timeout, and
   # a Rails.cache-backed IP cache). An app that configures Geocoder itself sets
   # this false; an app with no geocoder gem is unaffected either way.
@@ -1110,6 +1231,25 @@ module Studio
         patch "admin/geo",        to: "studio/geo_settings#update",          as: :admin_geo_update
         post  "admin/geo/toggle", to: "studio/geo_settings#toggle_override", as: :admin_geo_toggle
       end
+
+      # The link-preview default (/admin/link_preview): the image, title and
+      # description every page unfurls with unless it overrides them. ON by
+      # default (Studio.draw_link_preview_routes) because no consumer owns these
+      # names; an app can still switch it off from its initializer.
+      if Studio.draw_link_preview_routes
+        get    "admin/link_preview",       to: "studio/site_identities#edit",          as: :admin_link_preview
+        patch  "admin/link_preview",       to: "studio/site_identities#update"
+        delete "admin/link_preview/image", to: "studio/site_identities#destroy_image", as: :admin_link_preview_image
+      end
+      # The public user page (/u/:username): avatar and username only, and the
+      # user's avatar as its link-preview image. OPT-IN — see
+      # Studio.draw_public_user_routes. `format: false` because usernames may
+      # carry a dot, which would otherwise be read as a format extension.
+      if Studio.draw_public_user_routes
+        get "u/:username", to: "studio/public_users#show", as: :studio_public_user,
+            format: false, constraints: { username: %r{[^/]+} }
+      end
+
       # The living style guide. Canonical at /admin/style (StyleController#index);
       # /admin/design_system redirects here but KEEPS its admin_design_system_path
       # helper so a shipped host sidebar link on the old helper still resolves.