studio-engine 0.134.0 → 0.135.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28427df3b5517371576bbd0cc5c159220393748f14c7a31ed39214a223fd0b86
-  data.tar.gz: 2268ea35dc8219f05a5dc2f1e28c639478538782ba664d69125f7e63556ddfac
+  metadata.gz: 1b8bd497e5ba5d6c113a0e6c221b03200f395b1c3d4032aa1327691b7c584c34
+  data.tar.gz: 0a64eb7f3a70bcbe03a50550d36a1d8da938498d91d5cf0a1fcb257845a76759
 SHA512:
-  metadata.gz: 7c48c6796c363df39d913088657f89ac9ee7ffec99e3b3f685095006890c405ec3de5f8aaee936a50d3aa1a4c4250a445de484c0debff38166917bd6a3f08f34
-  data.tar.gz: 3fe116b2ea6ebfd22e920cacb672ead1e4f999e7c0d5f15b31ad208653e104627d6305c65d2cc24b021041bff9f3e31d9d3569841d8fc51f88daae1b1d6e18a7
+  metadata.gz: c325e02d5e2f0c2a9123ab2b342281b59d27635e48cca92396f792cd39a6fc403cf6e79bfc2e920f891ef9dcc30063e0460e393db83e7148470d3895615b4aad
+  data.tar.gz: 96424698d12cf9d7d60bfee31c6f8d97f5bb464439bb421d8f47ba3ab78f1ce359e9a01bd543f3baab4c45d502c73e117ed3074d4bc306c40582b9819ab3aa53

data/CHANGELOG.md

@@ -4,6 +4,16 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.135.0 — 2026-11-07
+
+### Fixed
+
+- The not-found page's og:url is the app's home, not the address it was asked for: `link_preview` takes `url:` (a path or an absolute URL), and a 404 at a hidden route no longer names that route in its link-preview tags.
+
+### Added
+
+- **A friendly not-found page.** `config.exceptions_app = Studio::ExceptionsApp.new` in `config/application.rb` gives a lost visitor the app's name, brand mark, a short message and a button home, inside the app's own layout, for an unknown address and a missing record alike. The status stays 404. A JSON request still gets Rails' 404 JSON, and other statuses keep `public/<status>.html`. If the page cannot render, or the host answers anything but a 404, the static `public/404.html` answers instead, so it cannot loop or change the status. An app with its own wall lists `"studio/not_found" => %w[show]`. See `docs/NOT_FOUND_PAGE.md`.
+
 ## 0.134.0 — 2026-11-07
 
 ### Changed

data/README.md

@@ -45,6 +45,7 @@ resolved.
 - **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).
 - **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer. It is on by default: with nothing configured it prints the app's name, logo and the legal links the app has routes for, and no address. `config.site_footer` declares the app's own facts (brand, social profiles, link columns, an address with a live map, legal links), every part optional; `config.site_footer_address` adds a location in one setting; `config.site_footer = false` turns the footer off; `config.site_footer_chat_path` adds a standard Chat link to the Contact column. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).
+- **Not-found page**: `config.exceptions_app = Studio::ExceptionsApp.new` in `config/application.rb` gives a lost visitor a friendly 404 with the app's name, brand mark and a button home, inside the app's layout. The status stays 404, JSON requests keep Rails' 404 JSON, and `public/404.html` is the fallback if the page cannot render. See [`docs/NOT_FOUND_PAGE.md`](docs/NOT_FOUND_PAGE.md).
 - **Booking**: a simple scheduler on Google Calendar appointment schedules, with or without the footer. With `config.booking_url`, `studio_booking_frame` embeds Google's booking page, `studio_booking_link` opens it in a popup, and `config.draw_booking_routes = true` draws `/schedule` (or name the app's own page with `config.booking_path`). `config.booking_crop` crops the frame to the slot picker at rest, from numbers `bin/booking-crop-measure` reads off the app's own schedule. See [`docs/BOOKING.md`](docs/BOOKING.md).
 - **Voice profile**: an opt-in row on `/profile` ("Set up your voice"): the person reads three phrases with a live level meter, their device turns each take into a speaker embedding (WeSpeaker via transformers.js), and only the averaged vector is saved on their user, never audio. `Studio::VoiceMatch.identify(embedding, among: User.all, model:)` answers who is speaking. Turn it on with `config.voice_profile = true` after installing the migration. See [`docs/VOICE_PROFILE.md`](docs/VOICE_PROFILE.md).
 - **Voice capture**: the microphone chip (names the microphone a page records from, picks another, Chrome help dialog), one level meter, and a record button that refuses a silent take and hands a heard one to the page as a `studio:voice-recorder:take` event with the blob; it uploads nothing. Render `studio/voice/microphone_chip` and `studio/voice/recorder`. See [`docs/VOICE_CAPTURE.md`](docs/VOICE_CAPTURE.md).

data/app/controllers/studio/not_found_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Studio
+  # The friendly not-found page, drawn by Studio::ExceptionsApp for an HTML 404
+  # (docs/NOT_FOUND_PAGE.md). It has no route: only the exceptions app calls it.
+  #
+  # It inherits the host's ApplicationController so the page sits inside the
+  # app's own layout, navbar, footer and theme, as Studio::PublicUsersController
+  # does. A signed-out visitor must see it, so it skips the engine's sign-in gate.
+  # A host with its own wall lists it there (the hub's AdminWall names
+  # "studio/not_found" => %w[show]). If the host still answers anything but a
+  # 404 here, the exceptions app throws that answer away and serves the static
+  # public/404.html, so a wall can cost the page its layout but never its status.
+  class NotFoundController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+    # No forgery skip: Rails' ShowExceptions calls the exceptions app as a GET
+    # (request_method = "GET"), which never needs the token, so the host's CSRF
+    # allow-lists stay as they are.
+
+    def show
+      @studio_not_found = {
+        app_name: Studio.app_name,
+        logo: not_found_logo,
+        home_path: not_found_home_path,
+        back_path: not_found_back_path
+      }
+      render "studio/not_found/show", status: :not_found, formats: [:html], content_type: "text/html"
+    end
+
+    private
+
+    def not_found_logo
+      Studio.navbar_brand&.dig(:logo) || Studio.logo_for("Navbar Logo")
+    end
+
+    def not_found_home_path
+      main_app.respond_to?(:root_path) ? main_app.root_path : "/"
+    end
+
+    # The page the visitor came from, when it is on this app: "Go back" returns
+    # there. A link from elsewhere, or none, draws no second link.
+    def not_found_back_path
+      referer = URI.parse(request.referer.to_s)
+      return nil unless referer.host == request.host && referer.path.present?
+      # "//other.host/x" is a same-host path a browser reads as another site.
+      return nil if referer.path.start_with?("//")
+      return nil if referer.path == request.env["action_dispatch.original_path"]
+
+      [referer.path, referer.query].compact.join("?")
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/app/helpers/studio/link_preview_helper.rb

@@ -10,7 +10,7 @@ module Studio
   # 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
+    OVERRIDE_KEYS = %i[image title description image_alt url].freeze
 
     # THE PAGE OVERRIDE. Call it from any view (the layout renders later, so it
     # sees the call):
@@ -71,7 +71,7 @@ module Studio
         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
+        url: studio_link_preview_page_url(overrides[:url])
       )
     end
 
@@ -127,9 +127,22 @@ module Studio
                                    request_base_url: (request.base_url if studio_link_preview_request?))
     end
 
-    def studio_link_preview_page_url
+    # The page's og:url: the request's own URL, or the `url:` a page passed to
+    # link_preview. A path is built on the same base as the request's; an
+    # absolute URL is used as is. The not-found page passes the app's home, so a
+    # 404 never advertises the broken address it was asked for (a 404 at a
+    # hidden route would otherwise name that route in its og:url).
+    def studio_link_preview_page_url(override = nil)
       return nil unless studio_link_preview_request?
 
+      override = override.to_s.strip
+      return override if override.match?(%r{\Ahttps?://}i)
+
+      if override.start_with?("/")
+        return Studio::LinkPreview.page_url(base_url: Studio.link_preview_base_url,
+                                            request_url: "#{request.base_url}#{override}", path: override)
+      end
+
       Studio::LinkPreview.page_url(base_url: Studio.link_preview_base_url,
                                    request_url: request.original_url, path: request.path)
     end

data/app/views/studio/_not_found.html.erb

@@ -0,0 +1,30 @@
+<%# locals: (app_name:, home_path:, logo: nil, back_path: nil, heading: :h1) %>
+<%# THE NOT-FOUND PAGE: what a lost visitor sees on an unknown address or a
+    record that is not there (docs/NOT_FOUND_PAGE.md). Studio::NotFoundController
+    renders it inside the app's own layout, from the app's Studio config:
+
+      app_name   Studio.app_name: named in the button home.
+      home_path  the app's root: the primary button.
+      logo       the app's brand mark (Studio.navbar_brand's logo, else the
+                 Navbar Logo theme image). nil draws no image.
+      back_path  a page on this app the visitor came from: a second link back.
+                 nil draws no second link.
+      heading    the title's tag: :h1 on the page, a lower level where the page
+                 is shown inside another (the style guide's card).
+
+    Theme tokens only, so it reads in light and dark. The static last resort,
+    public/404.html, carries the same words and the same data-test hooks. %>
+<section class="mx-auto w-full max-w-md px-4 py-16 sm:py-24 text-center" data-studio-not-found data-test="not-found" aria-labelledby="studio-not-found-title">
+  <% if logo.present? %>
+    <img src="<%= logo %>" alt="<%= app_name %>" width="64" height="64" class="mx-auto mb-6 h-16 w-16 object-contain" data-studio-not-found-logo>
+  <% end %>
+  <p class="type-fine font-semibold uppercase tracking-wide text-primary-ink mb-2">404 &middot; Not found</p>
+  <%= content_tag heading, "This page isn’t here", id: "studio-not-found-title", class: "type-h2 text-heading mb-3" %>
+  <p class="type-body text-secondary mb-8">The address may be mistyped, or the page may have moved. Head back home and pick up from there.</p>
+  <div class="flex flex-col sm:flex-row items-center justify-center gap-3">
+    <a href="<%= home_path %>" class="btn btn-primary w-full sm:w-auto" data-test="not-found-home">Back to <%= app_name %></a>
+    <% if back_path.present? %>
+      <a href="<%= back_path %>" class="btn btn-outline w-full sm:w-auto" data-test="not-found-back">Go back</a>
+    <% end %>
+  </div>
+</section>

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

@@ -0,0 +1,5 @@
+<%# Studio::NotFoundController#show: the not-found page in the app's layout. %>
+<% content_for(:title, "Page not found · #{Studio.app_name}") %>
+<%# A 404's og:url is the app's home, never the broken address it was asked for. %>
+<% link_preview(url: @studio_not_found[:home_path]) %>
+<%= render "studio/not_found", **@studio_not_found %>

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

@@ -0,0 +1,19 @@
+<%#  The Pages group of the Tricks board (admin/style): whole pages an app
+     adopts with one line. Not Found is the friendly 404 (docs/NOT_FOUND_PAGE.md),
+     drawn here with THIS app's name and brand mark; the Go back link shows as it
+     does when the visitor came from a page on this app. %>
+<section id="pages" class="section-subtarget space-y-5">
+  <div class="space-y-1">
+    <h3 class="type-h4 text-heading">Pages</h3>
+    <p class="text-muted text-sm">Whole pages an app adopts with one line in config/application.rb.</p>
+  </div>
+
+  <div class="grid gap-4 sm:grid-cols-2">
+    <%= render layout: "style/specimen", locals: { trick: "not_found" } do %>
+      <div class="card w-full">
+        <%= render "studio/not_found", app_name: Studio.app_name, logo: Studio.navbar_brand&.dig(:logo) || Studio.logo_for("Navbar Logo"),
+              home_path: "/", back_path: "#pages", heading: :h4 %>
+      </div>
+    <% end %>
+  </div>
+</section>

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

@@ -527,4 +527,7 @@
 
   <!-- Site footer and booking -->
   <%= render "style/site_footer" %>
+
+  <!-- Pages -->
+  <%= render "style/pages" %>
 </section>

data/config/studio_tricks.yml

@@ -462,6 +462,13 @@ booking_frame:
       note: "Cropped to the slot picker at rest; bin/booking-crop-measure prints yours."
       resolve: [config:booking_crop]
 
+not_found:
+  name: Not Found
+  group: Pages
+  token: "config.exceptions_app = Studio::ExceptionsApp.new"
+  note: "A lost visitor's 404 page, with the app's brand and a button home."
+  resolve: [partial:studio/not_found]
+
 board:
   name: Board
   group: Tasks

data/lib/studio/exceptions_app.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+module Studio
+  # The friendly not-found page, as an exceptions app. An app opts in with one
+  # line in config/application.rb (docs/NOT_FOUND_PAGE.md):
+  #
+  #   config.exceptions_app = Studio::ExceptionsApp.new
+  #
+  # Rails hands this app every exception ShowExceptions renders, with PATH_INFO
+  # rewritten to "/<status>" and the method set to GET. That is the path a
+  # RoutingError takes (an unknown address) and the path a RecordNotFound takes
+  # (Studio::ErrorHandling#handle_not_found re-raises on purpose so it lands here).
+  #
+  # What it answers:
+  #
+  #   404, an HTML request   Studio::NotFoundController#show: the app's name and
+  #                          brand mark, a short message and a button home,
+  #                          inside the app's own layout. Status 404.
+  #   404, a data request    ActionDispatch::PublicExceptions, unchanged: a JSON
+  #                          request gets {"status":404,"error":"Not Found"} with
+  #                          status 404, never the HTML page.
+  #   any other status       ActionDispatch::PublicExceptions, unchanged (500,
+  #                          422 and the rest keep public/<status>.html).
+  #
+  # IT CANNOT LOOP AND IT CANNOT CHANGE THE STATUS. The page renders through the
+  # app's ApplicationController, so the app's before_actions, layout and database
+  # all run. If any of them raises, or answers anything but a 404 (a sign-in
+  # redirect from a wall that does not list the page, a 406 from allow_browser),
+  # the answer is thrown away and PublicExceptions serves public/404.html, the
+  # static last resort, with status 404. PublicExceptions only reads a file, so
+  # the fallback has nothing left that can fail into this app again.
+  #
+  # Which requests are HTML is PublicExceptions' own rule, so the split never
+  # drifts from Rails': a format whose body PublicExceptions can serialize (JSON,
+  # XML) is data, and everything else, `Accept: */*` included, is the page.
+  class ExceptionsApp
+    NOT_FOUND = 404
+    PAGE_PARAMS = { controller: "studio/not_found", action: "show" }.freeze
+    # Cached by the failed request; the page's request must not read them.
+    STALE_KEYS = %w[action_dispatch.request.path_parameters
+                    action_dispatch.request.parameters
+                    action_dispatch.request.query_parameters
+                    action_dispatch.request.request_parameters
+                    action_controller.instance].freeze
+
+    # public_path: where the static pages live. Defaults to Rails.public_path,
+    # read on each call, so the line works before the app finishes booting.
+    # page: the Rack endpoint that draws the page (a seam for tests).
+    def initialize(public_path = nil, page: nil)
+      @public_path = public_path
+      @page = page
+    end
+
+    def call(env)
+      return static(env) unless page_request?(env)
+
+      response = draw_page(env)
+      return response if response
+
+      static(env)
+    end
+
+    private
+
+    def page_request?(env)
+      request = ActionDispatch::Request.new(env)
+      return false unless request.path_info.delete_prefix("/").to_i == NOT_FOUND
+
+      html?(request)
+    end
+
+    # PublicExceptions renders a body in a format the error hash serializes to
+    # (to_json, to_xml) and the HTML file for anything else.
+    def html?(request)
+      content_type = begin
+        request.formats.first
+      rescue ActionDispatch::Http::MimeNegotiation::InvalidType
+        Mime[:text]
+      end
+      return true unless content_type
+
+      !{}.respond_to?("to_#{content_type.to_sym}")
+    end
+
+    # The page's answer, or nil when it raised or came back as anything but a
+    # 404 HTML page.
+    def draw_page(env)
+      page_env = env.except(*STALE_KEYS)
+      page_env["action_dispatch.request.path_parameters"] = PAGE_PARAMS.dup
+      status, headers, body = page.call(page_env)
+      return [status, headers, body] if status.to_i == NOT_FOUND && html_body?(headers)
+
+      body.close if body.respond_to?(:close)
+      log("answered #{status}, not 404")
+      nil
+    rescue StandardError, ScriptError => e
+      log("#{e.class}: #{e.message}")
+      nil
+    end
+
+    def html_body?(headers)
+      type = headers["content-type"] || headers["Content-Type"]
+      type.to_s.start_with?("text/html")
+    end
+
+    def page
+      @page || Studio::NotFoundController.action(:show)
+    end
+
+    def static(env)
+      ActionDispatch::PublicExceptions.new(public_path).call(env)
+    end
+
+    def public_path
+      (@public_path || Rails.public_path).to_s
+    end
+
+    def log(reason)
+      Rails.logger&.warn("[studio.not_found] the page fell back to public/404.html: #{reason}")
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.134.0"
+  VERSION = "0.135.0"
 end

data/lib/studio.rb

@@ -80,6 +80,7 @@ require "studio/survey/breakdown"
 require "studio/survey/export"
 require "studio/crumbs"
 require "studio/page_header"
+require "studio/exceptions_app"
 
 module Studio
   mattr_accessor :app_name,            default: "Studio"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.134.0
+  version: 0.135.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -470,6 +470,7 @@ files:
 - app/controllers/studio/local_reviews_controller.rb
 - app/controllers/studio/marketing_kit_controller.rb
 - app/controllers/studio/models_controller.rb
+- app/controllers/studio/not_found_controller.rb
 - app/controllers/studio/onboarding_controller.rb
 - app/controllers/studio/profiles_controller.rb
 - app/controllers/studio/public_users_controller.rb
@@ -656,6 +657,7 @@ files:
 - app/views/studio/_hold_button.html.erb
 - app/views/studio/_hold_button_guard.html.erb
 - app/views/studio/_leveling_activity_assets.html.erb
+- app/views/studio/_not_found.html.erb
 - app/views/studio/_page_header.html.erb
 - app/views/studio/_section_header.html.erb
 - app/views/studio/_session_stamp.html.erb
@@ -771,6 +773,7 @@ files:
 - app/views/studio/models/show.html.erb
 - app/views/studio/newsletter_mailer/subscribed.html.erb
 - app/views/studio/newsletter_mailer/subscribed.text.erb
+- app/views/studio/not_found/show.html.erb
 - app/views/studio/profile_mailer/email_change_notification.html.erb
 - app/views/studio/profile_mailer/email_change_notification.text.erb
 - app/views/studio/profiles/_birthday_fields.html.erb
@@ -817,6 +820,7 @@ files:
 - app/views/style/_loaders_feed_page.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
+- app/views/style/_pages.html.erb
 - app/views/style/_scrims.html.erb
 - app/views/style/_site_footer.html.erb
 - app/views/style/_specimen.html.erb
@@ -884,6 +888,7 @@ files:
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
 - lib/studio/environment_banner.rb
+- lib/studio/exceptions_app.rb
 - lib/studio/geo.rb
 - lib/studio/geo/countries.rb
 - lib/studio/geo/lookup.rb