studio-engine 0.81.1 → 0.82.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2737532cb60e04de35ec057552292f8307aa863eec2413751cdf4080b079d712
-  data.tar.gz: cd3a407b3e61463686f245a4e93a30fdbdd67250a2fd6ca09a9a2abbbd507e46
+  metadata.gz: ad8be51b6366f71e083ae5bb7ce69e83e08330b826f6acb6027692e0857f9b9a
+  data.tar.gz: 216b21e17a79e2f635bfbdbb3996607cfa767ca1e06cac11e63b337c9864771a
 SHA512:
-  metadata.gz: 912655e55dd7e8a93eace9c7a237390144087b72611d88a08075ea8190961a0ba3f0266e8c724c093505cf3fc69596bb6eacce5019347a1c4d9bffd02552d13a
-  data.tar.gz: cbf461654e119d53e2d7c626b34014d3769f0a536a0d46ecd32c4af25255ff981997e4a8c14ab2d784c27966c5f7085be608250b974e2f1d46f8e14b06c513e8
+  metadata.gz: 06e416fbb35ec33fdaa8c0cceb76d994196dcb6898992cc31d1135f67f3e0804dab3c0e7eb4230bfe162a78adc348423d17e9cc7d484556b04eac0b46f18a7c7
+  data.tar.gz: 63334a9f39dde930606ebf7b23943287ff4d94bce68afcd4718c30cfc8838c1b52cef6f2f791474ec744db3ebfb66a6ef14cc5eebd1aa4894adbf651385666b4

data/CHANGELOG.md

@@ -4,6 +4,157 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.82.1 — 2026-09-30
+
+### Fixed
+
+- **Link previews now reach iMessage from a Rails 8 app.** Rails 8's
+  `allow_browser versions: :modern` answered iMessage's fetcher, which sends a
+  Safari 9.0.1 User-Agent, with a `406`, so no preview was drawn. This was live on
+  mcritchie.studio and cyvasse.xyz. `include Studio::LinkPreviewBots` now exempts a
+  preview fetcher's GET or HEAD from every `allow_browser` guard on the controller,
+  with no app code. It overrides the private method Rails' guard calls, so it
+  covers a guard declared anywhere in the controller chain. A POST, an old browser
+  that is not a fetcher, and every person are still checked. An app that already
+  wrote `allow_browser ..., unless: :link_preview_bot_request?` (the hub, cyvasse)
+  keeps working and can drop the `unless:`.
+- **A failed slim render is logged to `ErrorLog`.** `Studio::LinkPreviewBots` now
+  captures it with `ErrorLog.capture!` instead of a log line, and still serves the
+  fetcher the full page.
+- **`rails g studio:site_identity` indents the include it writes** into
+  `ApplicationController`. It landed at column 0 in cyvasse.
+
+### Added
+
+- **`og:image:width`, `og:image:height` and `og:image:alt`.** The size tags appear
+  when the image's size is known without a fetch: an analyzed Active Storage blob
+  (the operator's image or a page's attachment) or the static fallback file, whose
+  PNG, JPEG, GIF or WebP header is read. The alt is the page's new
+  `link_preview image_alt:`, else the card's title; `twitter:image:alt` matches.
+  The site identity cache key moves to `v2`, so the sizes appear without waiting
+  out the old entry.
+- **`config.link_preview_base_url`** pins the canonical base for previews. When
+  set, `og:url` is that base plus the path with no query string, and relative
+  images are made absolute on it, so a `herokuapp.com` host or a `?utm_` link does
+  not split one page's share count. The default, `nil`, keeps the request's URL.
+- [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md) gains *The allow_browser 406
+  trap*, with a curl check that uses the iMessage User-Agent, and notes Applebot's
+  slim page as a known trade-off.
+
+## 0.82.0 — 2026-09-30
+
+### Added
+
+- **A public user page at `/u/:username`, and the helpers that link to it.** It
+  shows the user's avatar and username and nothing else (no name, email or
+  wallet), and it is where a click on a username in any Studio app should lead.
+  See [`docs/PUBLIC_USER_PAGE.md`](docs/PUBLIC_USER_PAGE.md).
+  - **Link preview.** The page calls `link_preview image: user.avatar, title:
+    username`, so it unfurls with the avatar when one is set and with the site
+    identity's image when not. The avatar URL is permanent (a public service's own
+    URL, else Rails' storage proxy), never signed and expiring. With
+    `Studio::LinkPreviewBots` included, preview bots get the slim page carrying it.
+  - **Lookup.** Case-insensitive, with an exact spelling first. It reads
+    `username` only, never the email or the slug, so it cannot reveal whether an
+    address has an account. A `User#public_profile_visible?` that answers false
+    hides an account. Every miss gets the same friendly page with a `404` status.
+  - **Public.** The page skips `require_authentication` and renders in the host's
+    own layout.
+  - **Helpers.** `studio_user_profile_path(user)`, `studio_user_profile_url(user)`
+    and `link_to_user_profile(user, text = nil, **html_options, &block)` take a user
+    or a username. They answer `nil` (the link helper renders a plain `<span>`)
+    when the route is not drawn or the user has no username, so any view can call
+    them. The route helper is `studio_public_user_path(username:)`; the rules are
+    `Studio::PublicUser`.
+  - `components/_avatar` gains an `xl` size and an optional `alt:` local. Existing
+    calls render the same.
+  - **Opt-in:** `config.draw_public_user_routes` defaults to `false`, so an app that
+    owns `/u` is not broken. No consumer owns `/u` or the helper name today.
+
+  **Adopting, per app** (this release changes none of them on its own):
+
+  1. **cyvasse, turf-monster** (already have `users.username` with a
+     `lower(username)` index): set `config.draw_public_user_routes = true` in
+     `config/initializers/studio.rb`. Define `User#public_profile_visible?` if some
+     accounts must not have a page (cyvasse's merged-away accounts, say). Then
+     point username links at `link_to_user_profile(user)`.
+  2. **mcritchie-studio, mcritchie-industries** (no `username` column): add
+     `users.username` with a unique `lower(username)` index, backfill it
+     (`Studio::UsernameGenerator.generate` drafts one), then do step 1. Do not
+     reuse `slug`: it is keyed on the email.
+  3. For an avatar unfurl on a private bucket, nothing more is needed: the proxy
+     URL serves it. An app with a public-read service gets that service's URL
+     automatically.
+
+- **Site identity and link previews: a core primitive for every app.** Each app
+  now has a site identity, `Studio::SiteIdentity`: a title, a description and an
+  image. The operator edits all three at `/admin/link_preview`, beside a live card
+  drawn the way an unfurl draws it (image, domain, title, description). Every page
+  unfurls with it unless the page overrides it, and a missing override image falls
+  back to the site image. Lifted from turf-monster's `OgHelper`, `SiteSetting` and
+  `OgImageAttachable`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).
+  - **Reusable copy.** `Studio.site_identity(base_url:)` (and `studio_site_identity`
+    in a view) returns `{ title:, description:, image_url: }`: the operator's saved
+    value, then the drafted `config.site_title` / `config.site_description`, then
+    `Studio.app_name`. Read it for a meta description, share text or an email footer.
+  - **One page override.** `link_preview image:, title:, description:` from any
+    view. `image:` takes a URL, a path, or an Active Storage attachment, so
+    `link_preview image: user.avatar` works whether or not the user has one.
+    turf-monster's `content_for(:title)`, `content_for(:meta_description)` and
+    `content_for(:og_image)` keys are honoured beneath it.
+  - **Permanent image URLs.** A public service answers its own URL; any other
+    service goes through Rails' storage proxy, never a signed, expiring URL. Name a
+    public service with `config.link_preview_image_service`.
+  - **Preview bots get a slim page.** `include Studio::LinkPreviewBots` serves the
+    known fetchers (iMessage, Facebook, X, Discord, Slack, LinkedIn, WhatsApp,
+    Telegram, Applebot, Skype, Reddit, Embedly) the page's head tags and a one-card
+    body, under Apple LinkPresentation's 1 MiB limit (1,048,000 bytes previews,
+    1,049,000 fails). People and in-app browsers always get the full page.
+  - **Opt-in by installation, and duplicate-safe.** Under the new default
+    `config.link_preview_tags = :auto`, the head emits the tags only once the app
+    has installed the `studio_site_identities` table AND no template under its
+    `app/views` writes its own `og:title` or `og:image` (scanned once per process,
+    logged when it holds the tags off). So turf-monster and cyvasse, which write
+    their own, get no second set even after `studio_engine:install:migrations`
+    brings the table in. Set `true` to override the scan, `false` to keep the head
+    silent. The slim bot page also keeps only the first of any duplicated tag.
+  - **One adoption step.** `bin/rails g studio:site_identity --title "..."
+    --description "..."` copies only this migration (in the form
+    `studio_engine:install:migrations` writes, so that task skips it later), writes
+    the drafted copy into `config/initializers/studio.rb`, and includes
+    `Studio::LinkPreviewBots` in `ApplicationController`. `--own-tags` also sets
+    `config.link_preview_tags = false`. It is idempotent.
+  - **Drafted defaults.** An agent drafts the title and description when setting an
+    app up; the operator edits them on the page, and a saved value wins.
+    `Studio::SiteIdentity.seed!(title:, description:)` carries a draft into the row
+    from `db/seeds.rb` or a release task, filling only blank fields.
+  - `/admin/link_preview` is drawn by default (`config.draw_link_preview_routes`);
+    no consumer owns `admin_link_preview_path` or `admin_link_preview_image_path`.
+    It needs Active Storage for the upload; without it the page still edits the
+    words.
+
+  **Adopting, per app** (each is one short change; this release changes none of
+  them on its own):
+
+  1. **mcritchie-studio, mcritchie-industries** (no og tags of their own):
+     `bin/rails g studio:site_identity --title "..." --description "..."`, then
+     `bin/rails db:migrate`. The tags come from `layouts/studio/head`, which both
+     layouts already render. Optionally add a 1200 × 630 `public/og.png` as the
+     last-resort image. Set the image at `/admin/link_preview`.
+  2. **cyvasse** (writes og tags in `layouts/_seo.html.erb`): run the generator with
+     `--own-tags` and migrate. Then in `_seo`, replace the og:/twitter: tags with
+     `link_preview title: page.title, description: page.description, image: og_image`
+     (keep description, robots, canonical and JSON-LD, which are SEO, not preview),
+     and delete `config.link_preview_tags = false`.
+  3. **turf-monster** (writes og tags through `OgHelper` and
+     `layouts/_link_preview_meta`): run the generator with `--own-tags`, set
+     `config.link_preview_image_service = OgImageAttachable::PUBLIC_OG_SERVICE`, and
+     migrate. Copy `SiteSetting`'s title, description and image into
+     `Studio::SiteIdentity`. Then delete the `_link_preview_meta` renders, `OgHelper`'s
+     resolution, `SiteSetting`'s og fields and the app-local `LinkPreviewBot` (the
+     engine concern replaces it; contest pages keep `content_for(:og_image)` or move
+     to `link_preview`), and delete `config.link_preview_tags = false`.
+
 ## 0.81.1 — 2026-09-30
 
 ### Fixed

data/README.md

@@ -38,6 +38,8 @@ resolved.
 - **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
 - **Geo**: `Studio::GeoDetection` places every visitor (IP → country + subdivision, session-cached), `Studio::GeoSetting` stores the operator's blocked countries and regions, `require_geo_allowed` locks whichever surfaces an app chooses, and the shared badge + `/admin/geo` manager ship with it. See [`docs/GEO.md`](docs/GEO.md).
+- **Site identity and link previews**: `Studio::SiteIdentity` holds the app's title, description and image, edited at `/admin/link_preview` beside a live unfurl card and read anywhere through `Studio.site_identity`. Every page unfurls with it unless it calls `link_preview image:, title:, description:`, and `Studio::LinkPreviewBots` serves preview fetchers a slim page under iMessage's 1 MiB limit. Adopt with `bin/rails g studio:site_identity`. See [`docs/LINK_PREVIEW.md`](docs/LINK_PREVIEW.md).
+- **Public user page**: `/u/:username` shows a user's avatar and username (nothing else), and unfurls with their avatar, falling back to the site image. Link any username to it with `link_to_user_profile(user)` or `studio_user_profile_path(user)`. Opt in with `config.draw_public_user_routes = true`. See [`docs/PUBLIC_USER_PAGE.md`](docs/PUBLIC_USER_PAGE.md).
 - **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 
 ## Configuration

data/app/controllers/concerns/studio/link_preview_bots.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Studio
+  # Serve link-preview fetchers (iMessage, Slack, Discord, X, WhatsApp...) a
+  # SLIM document — the page's own identity tags and a one-card body — instead
+  # of the full page.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Studio::LinkPreviewBots
+  #   end
+  #
+  # WHY: Apple's LinkPresentation (the iMessage unfurler) aborts any HTML page
+  # over 1 MiB (WebKitErrorDomain 102, "Frame load interrupted"; measured
+  # 2026-09-30: 1,048,000 bytes previewed, 1,049,000 failed). A page carrying a
+  # big inline script or template passes that without anyone noticing, and every
+  # link to it stops previewing in Messages while Discord keeps working.
+  #
+  # HOW: the action and its view run as usual — so a page's `link_preview`
+  # override is set — and the full page renders. Then, for a known fetcher only,
+  # the body is replaced by Studio::LinkPreview.slim_document, which lifts the
+  # <title>, meta and icon tags out of that page's <head> and drops every script,
+  # style and template. Built from the rendered page, the slim document cannot
+  # drift from what a person's page says, and it works under ANY layout.
+  #
+  # DUPLICATE-SAFE: a tag the page emits twice (an app's own og tags and the
+  # engine's) reaches the fetcher once, the first occurrence.
+  #
+  # People, in-app browsers and unknown agents are never matched and always get
+  # the full page. The allow-list is Studio::LinkPreview::BOT_TOKENS.
+  #
+  # ALLOW_BROWSER: Rails 8's `allow_browser versions: :modern` (in every new
+  # app's ApplicationController) answers Apple's LinkPresentation — which sends a
+  # Safari 9.0.1 User-Agent — with a 406, so no iMessage preview. Including this
+  # concern exempts preview fetchers from every allow_browser guard on the
+  # controller, GET and HEAD only, with no app code. An app that already wrote
+  # `allow_browser ..., unless: :link_preview_bot_request?` keeps working: its
+  # guard never runs for a fetcher, so this override is never reached.
+  module LinkPreviewBots
+    extend ActiveSupport::Concern
+
+    SLIM_HEADER = "X-Studio-Link-Preview"
+
+    included do
+      after_action :serve_link_preview_slim_document
+
+      helper_method :link_preview_bot_request? if respond_to?(:helper_method)
+    end
+
+    # A preview fetcher reading a page. No format check: an unfurler often sends
+    # `Accept: */*`, which Rails reads as Mime::ALL rather than html, though the
+    # response it gets is HTML — the after_action checks the RESPONSE instead.
+    def link_preview_bot_request?
+      (request.get? || request.head?) && Studio::LinkPreview.bot?(request.user_agent)
+    end
+
+    private
+
+    # Rails' allow_browser macro installs
+    # `before_action -> { allow_browser(versions:, block:) }`, which dispatches to
+    # the PRIVATE instance method ActionController::AllowBrowser#allow_browser (the
+    # same in Rails 7.2.3 and 8.1.4). This concern is included below
+    # ActionController::Base, so it sits above that module in the ancestor chain and
+    # this method answers first: a preview fetcher's GET/HEAD skips the browser
+    # check, everything else goes to Rails. Overriding the method rather than
+    # skipping the callback covers every allow_browser declaration (this
+    # controller, a parent or a subclass, before or after the include), and a
+    # lambda callback cannot be named to skip_before_action anyway. The integration
+    # suite pins the method, so a Rails rename fails loudly
+    # (test/integration/link_preview_test.rb).
+    def allow_browser(*args, **kwargs, &block)
+      return if link_preview_bot_request?
+
+      super
+    end
+
+    def serve_link_preview_slim_document
+      return unless link_preview_bot_request?
+      return unless response.status == 200
+      return unless response.media_type == "text/html"
+
+      body = response.body
+      return unless body.is_a?(String) && !body.empty?
+
+      response.body = Studio::LinkPreview.slim_document(body, url: studio_link_preview_page_url)
+      response.headers[SLIM_HEADER] = "slim"
+      # A shared cache must never hand the slim page to a person.
+      response.headers["Vary"] = [response.headers["Vary"], "User-Agent"].compact.join(", ")
+    rescue StandardError => e
+      # The full page is still a valid (if large) answer; never 500 a fetcher.
+      # The failure goes to ErrorLog (and Sentry, when the host loads it) so it
+      # is triaged rather than lost in a log line; never re-raised, because the
+      # response is already rendered and the fetcher must still get the page.
+      studio_link_preview_capture(e)
+    end
+
+    def studio_link_preview_capture(error)
+      ErrorLog.capture!(error)
+    rescue StandardError, NameError => capture_error
+      Rails.logger&.warn("[studio.link_preview] slim render skipped: #{error.class}: #{error.message} " \
+                         "(ErrorLog unavailable: #{capture_error.class})")
+    end
+
+    # The page's canonical URL for the slim card's link: Studio.link_preview_base_url
+    # plus the path when the app pins one, else the URL as requested.
+    def studio_link_preview_page_url
+      Studio::LinkPreview.page_url(base_url: Studio.link_preview_base_url,
+                                   request_url: request.original_url, path: request.path)
+    end
+  end
+end

data/app/controllers/studio/public_users_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Studio
+  # /u/:username — the public page a username links to in every Studio app.
+  #
+  # It shows the avatar and the username, and nothing else: no name, no email,
+  # no wallet. Its link preview is the avatar when one is set, else the site
+  # identity's image (Studio::LinkPreviewHelper#link_preview does the fallback).
+  #
+  # Public by design, so it skips the host's sign-in gate (mcritchie-industries
+  # and cyvasse gate every controller through Studio::ErrorHandling). It inherits
+  # the host's ApplicationController for the same reason ProfilesController
+  # does: the page renders inside the app's own layout, navbar and theme, and a
+  # host that includes Studio::LinkPreviewBots serves unfurlers the slim page.
+  #
+  # An unknown username gets a friendly page with a real 404 status. Every miss
+  # looks the same (unknown, hidden, or an app with no username column), and the
+  # lookup never touches the email, so the page cannot be used to learn whether
+  # an account exists behind an address. Drawn only when the host opts in:
+  # Studio.draw_public_user_routes.
+  class PublicUsersController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+
+    def show
+      @public_user = Studio::PublicUser.find(params[:username])
+      return if @public_user
+
+      @requested_username = params[:username].to_s
+      render :not_found, status: :not_found
+    end
+  end
+end

data/app/controllers/studio/site_identities_controller.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Studio
+  # /admin/link_preview — the operator edits the SITE IDENTITY (Studio::
+  # SiteIdentity): the image, title and description an unfurl shows for any page
+  # that does not name its own, and the copy Studio.site_identity hands any
+  # other reader. All three on one page, beside a live card drawn the way an
+  # unfurl draws it.
+  #
+  # A plain host-inherited controller whose view is a bare content wrapper, like
+  # /admin/geo and /admin/emails, so it renders inside each host's application
+  # layout. Lifted from turf-monster's admin dashboard (update_link_preview and
+  # update_link_preview_image), which ran it in production first.
+  #
+  # The image and the words post SEPARATELY: the cropper submits a form holding
+  # only the image, the text form holds only the words. So #update changes only
+  # the fields a request actually carried.
+  class SiteIdentitiesController < ApplicationController
+    before_action :require_admin
+
+    IMAGE_TYPES = Studio::SiteIdentity::IMAGE_TYPES
+    MAX_IMAGE_BYTES = Studio::SiteIdentity::MAX_IMAGE_BYTES
+
+    def edit
+      @installed = Studio::SiteIdentity.table_ready?
+      @setting = @installed ? Studio::SiteIdentity.current : nil
+      @uploads_available = @installed && @setting.respond_to?(:image)
+      @default_image_url = default_image_url
+      @static_image_url = static_image_url
+      @domain = preview_domain
+    end
+
+    def update
+      return redirect_to(admin_link_preview_path, alert: not_installed_message, status: :see_other) unless installed?
+
+      attrs = params.fetch(:site_identity, {})
+      file = attrs[:image]
+
+      if attrs.key?(:image) && !valid_image?(file)
+        message = file.blank? ? "Choose an image to upload." : "Use a PNG, JPG, WebP or GIF under 8 MB."
+        return redirect_to admin_link_preview_path, alert: message, status: :see_other
+      end
+
+      setting = Studio::SiteIdentity.current!
+      rescue_and_log(target: setting) do
+        setting.title = attrs[:title].to_s.strip.presence if attrs.key?(:title)
+        setting.description = attrs[:description].to_s.strip.presence if attrs.key?(:description)
+        setting.save!
+        setting.image.attach(file) if file.present?
+        # An attach does not touch the row, so after_commit does not fire for it.
+        Studio::SiteIdentity.bust_cache!
+      end
+
+      redirect_to admin_link_preview_path, status: :see_other,
+                                           notice: file.present? ? "Default link-preview image updated." : "Link-preview defaults updated."
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to admin_link_preview_path, status: :see_other, alert: e.record.errors.full_messages.to_sentence
+    rescue StandardError
+      redirect_to admin_link_preview_path, status: :see_other, alert: "Couldn't save the link preview. Please try again."
+    end
+
+    # DELETE /admin/link_preview/image — drop the uploaded default, so previews
+    # fall back to the static image (or none).
+    def destroy_image
+      return redirect_to(admin_link_preview_path, alert: not_installed_message, status: :see_other) unless installed?
+
+      setting = Studio::SiteIdentity.current
+      if setting&.persisted? && setting.image_attached?
+        rescue_and_log(target: setting) do
+          setting.image.purge
+          Studio::SiteIdentity.bust_cache!
+        end
+      end
+
+      redirect_to admin_link_preview_path, status: :see_other, notice: "Default link-preview image removed."
+    rescue StandardError
+      redirect_to admin_link_preview_path, status: :see_other, alert: "Couldn't remove the image. Please try again."
+    end
+
+    private
+
+    def installed?
+      Studio::SiteIdentity.table_ready?
+    end
+
+    def not_installed_message
+      "Install the site identity table first: bin/rails g studio:site_identity && bin/rails db:migrate"
+    end
+
+    def valid_image?(file)
+      file.respond_to?(:content_type) && IMAGE_TYPES.include?(file.content_type.to_s) &&
+        file.respond_to?(:size) && file.size.to_i.positive? && file.size <= MAX_IMAGE_BYTES
+    end
+
+    # The uploaded image as the card shows it: the same URL the head emits.
+    def default_image_url
+      stored = Studio::SiteIdentity.stored
+      Studio::LinkPreview.absolute_url(stored[:image_url] || stored[:image_path], base_url: preview_base_url)
+    rescue StandardError
+      nil
+    end
+
+    # The same base the head's tags are built on (Studio.link_preview_base_url,
+    # else this request's), so the card shows the domain and URL an unfurl does.
+    def preview_base_url
+      Studio::LinkPreview.base_url(pinned: Studio.link_preview_base_url, request_base_url: request.base_url)
+    end
+
+    def preview_domain
+      URI.parse(preview_base_url.to_s).host || request.host
+    rescue URI::InvalidURIError
+      request.host
+    end
+
+    def static_image_url
+      Studio::LinkPreview.absolute_url(Studio::SiteIdentity.static_image, base_url: preview_base_url)
+    end
+  end
+end

data/app/helpers/studio/link_preview_helper.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Studio
+  # View-side link preview: the ONE override a page uses, and the tags the head
+  # renders. The policy (which rung wins) is Studio::LinkPreview.resolve; this
+  # module only gathers the rungs, and it is where the request's base URL and
+  # the asset paths are known.
+  #
+  # Method names are prefixed (`link_preview`, `studio_link_preview*`) for the
+  # reason Studio::GeoHelper gives: every helper module is included into every
+  # view, so an unprefixed name would collide with a host's own helper.
+  module LinkPreviewHelper
+    OVERRIDE_KEYS = %i[image title description image_alt].freeze
+
+    # THE PAGE OVERRIDE. Call it from any view (the layout renders later, so it
+    # sees the call):
+    #
+    #   <% link_preview image: @contest.banner, title: @contest.name,
+    #                   description: @contest.tagline %>
+    #
+    # `image:` takes a URL, a root-relative path, or an Active Storage
+    # attachment/blob (a user's avatar). An image that is nil, blank, or an
+    # attachment with nothing attached falls back to the operator's default, so
+    # a page can pass `image: user.avatar` without asking whether there is one.
+    # `image_alt:` is the image's text alternative (og:image:alt); without it the
+    # card's title stands in, which is what the picture illustrates.
+    # Only the keys passed are set; a second call overrides just its own keys.
+    # Returns nil, so `<%= link_preview ... %>` prints nothing either.
+    def link_preview(**overrides)
+      unknown = overrides.keys - OVERRIDE_KEYS
+      raise ArgumentError, "link_preview takes #{OVERRIDE_KEYS.join(", ")}; got #{unknown.join(", ")}" if unknown.any?
+
+      (@studio_link_preview_overrides ||= {}).merge!(overrides)
+      nil
+    end
+
+    # The resolved preview for this page:
+    # { title:, description:, image:, image_source:, image_width:, image_height:,
+    #   image_alt:, site_name:, url: }.
+    # `image` is absolute (or nil). `image_width`/`image_height` are the
+    # winning image's pixel size when it is KNOWN — an attachment whose blob has
+    # been analyzed, or the static fallback file — and nil otherwise; a URL handed
+    # in as a string is never fetched to measure it. `url` is the page's og:url
+    # (Studio.link_preview_base_url plus the path when the app pins one).
+    # Never raises: a preview must not 500 a page.
+    #
+    # Rungs, most specific first: the page's `link_preview`, then the page's
+    # own content_for(:title) / content_for(:meta_description) /
+    # content_for(:og_image) (turf-monster's existing keys, honoured so its
+    # pages keep their overrides on adoption), then the site identity.
+    def studio_link_preview
+      overrides = @studio_link_preview_overrides || {}
+      stored = studio_site_identity_stored
+      override_image = studio_link_preview_image_location(overrides[:image])
+
+      preview = Studio::LinkPreview.resolve(
+        site_name: Studio.app_name,
+        titles: [overrides[:title], studio_link_preview_content(:title), stored[:title], Studio.site_title],
+        descriptions: [overrides[:description], studio_link_preview_content(:meta_description),
+                       stored[:description], Studio.site_description],
+        page_images: [override_image, studio_link_preview_content(:og_image)],
+        default_image: stored[:image_url] || stored[:image_path],
+        static_image: Studio::SiteIdentity.static_image
+      )
+
+      width, height = studio_link_preview_image_size(preview[:image_source], overrides[:image], override_image, stored)
+
+      preview.merge(
+        image: Studio::LinkPreview.absolute_url(preview[:image], base_url: studio_request_base_url) || preview[:image],
+        image_width: width,
+        image_height: height,
+        image_alt: (overrides[:image_alt].to_s.strip.presence || preview[:title] if preview[:image]),
+        site_name: Studio.app_name.to_s,
+        url: studio_link_preview_page_url
+      )
+    end
+
+    # The app's IDENTITY COPY — { title:, description:, image_url: } — for any
+    # view that wants the words, not the tags: a meta description, share text,
+    # an email footer. The site-wide answer, ignoring this page's overrides.
+    # Studio.site_identity is the same call outside a view.
+    def studio_site_identity
+      Studio.site_identity(base_url: studio_request_base_url)
+    end
+
+    # The og:/twitter: tags for this page. layouts/studio/_head renders this
+    # when Studio.link_preview_tags? says so; an app that set
+    # `link_preview_tags = false` can render it wherever it likes.
+    def studio_link_preview_tags
+      render "layouts/studio/link_preview_tags", preview: studio_link_preview
+    rescue StandardError => e
+      Rails.logger&.warn("[studio.link_preview] tags skipped: #{e.class}: #{e.message}")
+      "".html_safe
+    end
+
+    private
+
+    def studio_site_identity_stored
+      Studio::SiteIdentity.stored
+    rescue StandardError => e
+      Rails.logger&.warn("[studio.link_preview] site identity unavailable: #{e.class}: #{e.message}")
+      {}
+    end
+
+    def studio_link_preview_image_location(image)
+      return nil if image.nil?
+      return image.to_s if image.is_a?(String) || image.is_a?(Symbol)
+
+      location = Studio::SiteIdentity.image_location(image)
+      location && (location[:url] || location[:path])
+    rescue StandardError
+      nil
+    end
+
+    # content_for holds ESCAPED text in a SafeBuffer, and the resolver's strip
+    # returns a plain String the tag partial escapes again ("Pass &amp;amp; Run").
+    # Hand the resolver the plain text instead.
+    def studio_link_preview_content(key)
+      value = content_for(key)
+      value && CGI.unescapeHTML(value.to_str)
+    end
+
+    # The app's pinned canonical base (Studio.link_preview_base_url), else the
+    # request's. Every preview URL is built on it.
+    def studio_request_base_url
+      Studio::LinkPreview.base_url(pinned: Studio.link_preview_base_url,
+                                   request_base_url: (request.base_url if studio_link_preview_request?))
+    end
+
+    def studio_link_preview_page_url
+      return nil unless studio_link_preview_request?
+
+      Studio::LinkPreview.page_url(base_url: Studio.link_preview_base_url,
+                                   request_url: request.original_url, path: request.path)
+    end
+
+    def studio_link_preview_request?
+      respond_to?(:request) && request ? true : false
+    end
+
+    # [width, height] of the image that won, when it is known without a fetch.
+    # The override rung counts only when the page handed in an ATTACHMENT (its
+    # blob's analyzed metadata); a URL string or a content_for(:og_image) is
+    # unmeasured, so its tags are left out rather than guessed.
+    def studio_link_preview_image_size(source, override, override_location, stored)
+      case source
+      when :page
+        return nil if override_location.nil? || override.is_a?(String) || override.is_a?(Symbol)
+
+        Studio::SiteIdentity.image_dimensions(override)
+      when :default
+        width, height = stored[:image_width], stored[:image_height]
+        width && height ? [width, height] : nil
+      when :static
+        Studio::SiteIdentity.static_image_dimensions
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/helpers/studio/public_user_helper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Studio
+  # Links to the public user page (/u/:username). Clicking a username anywhere
+  # in a Studio app should land here, so every app reaches it the same way:
+  #
+  #   <%= link_to_user_profile(entry.user) %>                  # text: display_name
+  #   <%= link_to_user_profile(user, "@#{user.username}", class: "font-semibold") %>
+  #   <%= link_to_user_profile(user) do %> ...avatar... <% end %>
+  #   studio_user_profile_path(user)   # => "/u/alex", or nil
+  #
+  # The path helpers answer nil, and link_to_user_profile renders its text in a
+  # plain <span> with no link, whenever there is no page to go to: the app has
+  # not drawn the route (Studio.draw_public_user_routes), or the user has no
+  # username. So a view can call them for every user without asking first.
+  #
+  # Prefixed names for the reason Studio::GeoHelper gives: every helper module is
+  # included into every view. The ROUTE helper is studio_public_user_path; these
+  # take a user rather than a username, which is why they are named apart.
+  module PublicUserHelper
+    def studio_user_profile_path(user, **options)
+      studio_user_profile_location(:path, user, options)
+    end
+
+    def studio_user_profile_url(user, **options)
+      studio_user_profile_location(:url, user, options)
+    end
+
+    def link_to_user_profile(user, name = nil, html_options = nil, **options, &block)
+      html_options, name = name, nil if name.is_a?(Hash)
+      html_options = (html_options || {}).merge(options)
+      path = studio_user_profile_path(user)
+
+      content = block ? capture(&block) : (name || studio_user_profile_label(user))
+      if path
+        html_options[:data] = { public_user_link: "" }.merge(html_options[:data] || {})
+        link_to(content, path, html_options)
+      else
+        content_tag(:span, content, html_options)
+      end
+    end
+
+    private
+
+    def studio_user_profile_location(kind, user, options)
+      return nil unless respond_to?(:"studio_public_user_#{kind}")
+
+      username = Studio::PublicUser.username_for(user)
+      return nil if username.nil?
+
+      public_send(:"studio_public_user_#{kind}", username: username, **options)
+    end
+
+    def studio_user_profile_label(user)
+      return user.to_s if user.is_a?(String) || user.is_a?(Symbol)
+
+      label = user.display_name if user.respond_to?(:display_name)
+      label.presence || Studio::PublicUser.username_for(user).to_s
+    end
+  end
+end