shiplog 0.2.0 → 0.3.1

data/app/controllers/shiplog/admin/entries/images_controller.rb

@@ -0,0 +1,76 @@
+module Shiplog
+  module Admin
+    module Entries
+      # An entry's screenshots on the edit page: upload, alt text, remove. :id is the image's blob id, the key of
+      # the entry's order and alt texts. Not found while screenshots are off.
+      class ImagesController < ApplicationController
+        before_action :require_images
+        before_action :set_entry
+
+        def create
+          files = uploads
+          return back(alert: t("shiplog.admin.entries.images.none_selected", default: "Choose at least one image.")) if files.empty?
+
+          checked = files.index_with { |file| inspect_upload(file) }
+          rejected = checked.select { |_file, info| info.nil? }.keys
+          if rejected.any?
+            names = rejected.map { |file| file.original_filename.to_s.scrub.first(100) }.to_sentence
+            return back(alert: t("shiplog.admin.entries.images.rejected", names:, default: "Not added, only PNG, JPEG, GIF and WebP images up to 5 MB and 10,000 pixels a side are accepted: %{names}"))
+          end
+
+          @entry.add_images(checked.map { |file, info| attachable(file, info) }) # uploads first, locks only to attach
+          back(notice: t("shiplog.admin.entries.images.added", count: files.size, default: { one: "Image added.", other: "%{count} images added." }))
+        end
+
+        def update
+          return head(:not_found) unless @entry.find_image(params[:id])
+
+          @entry.update_image_alt(params[:id], params[:alt])
+          back(notice: t("shiplog.admin.entries.images.alt_saved", default: "Alt text saved."))
+        end
+
+        def destroy
+          return head(:not_found) unless @entry.find_image(params[:id])
+
+          @entry.remove_image(params[:id])
+          back(notice: t("shiplog.admin.entries.images.removed", default: "Image removed."))
+        end
+
+        private
+
+        def require_images
+          head :not_found unless Shiplog.images?
+        end
+
+        def set_entry
+          @entry = Entry.find(params[:entry_id])
+        end
+
+        def back(**flash)
+          redirect_to edit_entry_path(@entry, inbox_filter_params), **flash
+        end
+
+        def uploads
+          Array(params[:images]).select { |file| file.is_a?(ActionDispatch::Http::UploadedFile) }
+        end
+
+        # Decided by the file's bytes and size, never by the declared name or content type: the type, and the
+        # pixel size read from the header, which must be within the limits (see ImageType). Nil when refused.
+        def inspect_upload(file)
+          return unless file.size.between?(1, ImageType::MAX_BYTES)
+
+          file.rewind
+          ImageType.analyze(file.read(ImageType::MAX_BYTES + 1))
+        rescue ImageType::Invalid
+          nil
+        ensure
+          file.rewind
+        end
+
+        def attachable(file, info)
+          { io: file.tempfile, filename: file.original_filename.to_s.scrub.presence || "image", content_type: info.content_type, metadata: { width: info.width, height: info.height } }
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/translations/retranslations_controller.rb

@@ -0,0 +1,23 @@
+module Shiplog
+  module Admin
+    module Entries
+      module Translations
+        # Translates the entry into the locale again, ignoring the stored digest and an admin's edit.
+        class RetranslationsController < ApplicationController
+          def create
+            entry = Entry.find(params[:entry_id])
+            locale = params[:translation_locale].to_s
+            return head(:not_found) unless Entry.translated_locale?(locale)
+
+            back = edit_entry_path(entry, inbox_filter_params)
+            return redirect_to(back, alert: t("shiplog.admin.entries.translations.only_approved", default: "Only approved entries are translated.")) unless entry.approved?
+            return redirect_to(back, alert: t("shiplog.admin.entries.translations.no_rewriter", default: "Translating needs config.rewriter, which is not set.")) unless Shiplog.config.rewriter
+
+            TranslateEntryJob.perform_later(entry, locale.to_sym, force: true)
+            redirect_to back, notice: t("shiplog.admin.entries.translations.queued", default: "Translation queued. Refresh in a moment.")
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/translations_controller.rb

@@ -0,0 +1,35 @@
+module Shiplog
+  module Admin
+    module Entries
+      # An admin's edit of an entry's translation (title and body) into one of config.locales. It is published
+      # at once and kept until the English text changes: the translation is marked edited and made from the
+      # entry's current English text, so it shows even if it was stale.
+      class TranslationsController < ApplicationController
+        before_action :set_entry_and_locale
+
+        def update
+          translation = @entry.translations.find_or_initialize_by(locale: @locale)
+          translation.assign_attributes(translation_params)
+          translation.assign_attributes(edited_by_admin: true, source_digest: @entry.translation_source_digest)
+          if translation.save
+            redirect_to edit_entry_path(@entry, inbox_filter_params), notice: t("shiplog.admin.entries.translations.saved", default: "Translation saved.")
+          else
+            redirect_to edit_entry_path(@entry, inbox_filter_params), alert: translation.errors.full_messages.to_sentence
+          end
+        end
+
+        private
+
+        def set_entry_and_locale
+          @entry = Entry.find(params[:entry_id])
+          @locale = params[:translation_locale].to_s
+          head :not_found unless Entry.translated_locale?(@locale)
+        end
+
+        def translation_params
+          params.expect(translation: %i[title body])
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries_controller.rb

@@ -12,7 +12,7 @@ module Shiplog
         @page = page_number
         scope = Entry.where(status: @status)
         scope = scope.where(kind: @kind) if @kind
-        records = scope.includes(:subject).order(updated_at: :desc, id: :desc)
+        records = scope.includes(:subject, :area).order(updated_at: :desc, id: :desc)
           .offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
         @more = records.size > PER_PAGE
         @entries = records.first(PER_PAGE)
@@ -23,11 +23,17 @@ module Shiplog
       end
 
       def update
-        if @entry.update(entry_params)
+        @entry.assign_attributes(entry_params)
+        @entry.area_set_by_admin = true if @entry.area_id_changed? # the admin's choice, which detection never overwrites
+        if @entry.save
           redirect_to root_path(inbox_filter_params), notice: t("shiplog.admin.entries.saved")
         else
           render :edit, status: :unprocessable_content
         end
+      rescue ActiveRecord::InvalidForeignKey
+        # The selected area was deleted between the validation and the save.
+        @entry.errors.add(:area_id, t("shiplog.admin.entries.area_gone", default: "no longer exists"))
+        render :edit, status: :unprocessable_content
       rescue ActiveRecord::RecordNotUnique
         # Two concurrent kind switches can both pass the validation; the unique index has the last word.
         @entry.errors.add(:changelog_kind, :taken)
@@ -48,7 +54,7 @@ module Shiplog
       end
 
       def entry_params
-        params.expect(entry: %i[title body released_on changelog_kind])
+        params.expect(entry: %i[title body released_on changelog_kind area_id])
       end
 
       def page_number

data/app/controllers/shiplog/changelog_entries_controller.rb

@@ -0,0 +1,26 @@
+module Shiplog
+  # The permalink page of a published feature or change: /changelog/:slug.
+  class ChangelogEntriesController < PublicController
+    def show
+      @entry = Entry.published_changelog.with_images_loaded.find_by(slug: params[:slug])
+      return pass_to_host_routes unless @entry
+
+      notify_changelog_seen
+      @newer = @entry.newer_changelog_entry
+      @older = @entry.older_changelog_entry
+      preload_translations(@entry, @newer, @older)
+      fresh_when etag: [ *shiplog_etag_parts, *shiplog_area_etag_parts, [ @entry, @newer, @older ].map { |entry| [ entry&.id, entry&.updated_at, entry&.area_id ] },
+        shiplog_image_etag_parts([ @entry ]), shiplog_translation_etag_parts([ @entry, @newer, @older ]) ]
+    end
+
+    private
+
+    # The engine is usually mounted at "/", so /changelog/:slug can shadow a host route below the changelog
+    # path (/changelog/archive, declared after the mount). An unknown slug answers 404 with X-Cascade: pass,
+    # which makes the router try the routes after the engine's mount; if none matches, the host's own 404 shows.
+    def pass_to_host_routes
+      response.set_header("X-Cascade", "pass")
+      head :not_found
+    end
+  end
+end

data/app/controllers/shiplog/changelog_feeds_controller.rb

@@ -0,0 +1,19 @@
+module Shiplog
+  # The Atom feed of the latest published features and changes: /changelog.atom.
+  class ChangelogFeedsController < PublicController
+    LIMIT = 50
+
+    layout false
+    before_action :set_area
+
+    def show
+      scope = Entry.published_changelog.newest_first
+      scope = scope.where(area_id: @area.id) if @area
+      @entries = scope.includes(:area).with_images_loaded.limit(LIMIT).to_a
+      @entries.select!(&:permalink?) # no slug (or an invalid one) means no stable id: left out
+      preload_translations(@entries)
+      fresh_when etag: [ *shiplog_etag_parts, *shiplog_area_etag_parts, @entries.map { |entry| [ entry.id, entry.updated_at, entry.area_id ] },
+        shiplog_image_etag_parts(@entries), shiplog_translation_etag_parts(@entries) ]
+    end
+  end
+end

data/app/controllers/shiplog/changelogs_controller.rb

@@ -2,24 +2,40 @@ module Shiplog
   class ChangelogsController < PublicController
     PER_PAGE = 30
     MAX_PAGE = 100_000
+    MIN_FILTER_AREAS = 2
+
+    before_action :set_area, only: :show
 
     def show
       @page = page_number
-      scope = Entry.approved.where(kind: %w[feature change]).where.not(released_on: nil)
-        .order(released_on: :desc, approved_at: :desc, id: :desc)
+      scope = Entry.published_changelog.newest_first
       @query = search_query
-      scope = scope.search(@query) if @query
-      records = scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
+      scope = scope.search(@query, locale: I18n.locale) if @query
+      scope = scope.where(area_id: @area.id) if @area
+      @areas = filter_areas
+      records = scope.includes(:area).with_images_loaded.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
       return head(:not_found) if @page > 1 && records.empty?
 
+      notify_changelog_seen
       @older = records.size > PER_PAGE
       @months = records.first(PER_PAGE).group_by { |entry| entry.released_on.beginning_of_month }
       @result_count = scope.count if @query
-      fresh_when etag: [ *shiplog_etag_parts, @query, @page, @older, @months.values.flatten.map { |entry| [ entry.id, entry.updated_at ] } ]
+      shown = @months.values.flatten
+      preload_translations(shown)
+      fresh_when etag: [ *shiplog_etag_parts, *shiplog_area_etag_parts, @areas.map(&:id), @query, @page, @older,
+        shown.map { |entry| [ entry.id, entry.updated_at, entry.area_id ] },
+        shiplog_image_etag_parts(shown), shiplog_translation_etag_parts(shown) ]
     end
 
     private
 
+    # The areas to offer as filter links: those with published entries, in the admin's order, and only when there
+    # are at least two (a single area filters nothing).
+    def filter_areas
+      areas = Area.ordered.where(id: Entry.published_changelog.where.not(area_id: nil).select(:area_id)).to_a
+      areas.size >= MIN_FILTER_AREAS ? areas : []
+    end
+
     # The normalised search query (words joined by one space), or nil when search is off or the query is blank.
     def search_query
       return unless Shiplog.config.changelog_search && params[:q].is_a?(String)

data/app/controllers/shiplog/public_controller.rb

@@ -8,10 +8,67 @@ module Shiplog
     helper Shiplog::SwitcherHelper
     helper Shiplog::RoadmapHelper
     helper Shiplog::HostRoutesHelper
+    helper Shiplog::PermalinkHelper
+    helper Shiplog::StructuredDataHelper
+    helper Shiplog::HeadHelper
     layout -> { Shiplog.config.public_layout }
 
     private
 
+    # Calls config.on_changelog_seen for a visit to the changelog index or a permalink page. It runs before
+    # the page renders (the actions call it once they know the page exists, ahead of fresh_when and the
+    # implicit render), so a host navbar badge in the same response shows the count the callback just stored,
+    # also when the answer ends up a 304 (a revisit is a visit). Not called for 404s or the feed.
+    # The response is not sent yet, so the callback can still set cookies or headers. A failing callback is
+    # logged and never breaks the page.
+    def notify_changelog_seen
+      callback = Shiplog.config.on_changelog_seen
+      return unless callback && request.format.html?
+
+      callback.call(self)
+    rescue StandardError => error
+      Rails.logger.error("[shiplog] on_changelog_seen failed: #{error.class}: #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
+    end
+
+    # Sets @area from ?area=<slug>. A blank or non-string value is ignored; a slug no area has is a 404 (a
+    # renamed or deleted area has no page to show, rather than the unfiltered list under a filtered URL).
+    def set_area
+      slug = params[:area]
+      return unless slug.is_a?(String) && slug.present?
+
+      @area = Area.find_by(slug:)
+      head(:not_found) unless @area
+    end
+
+    # What the markup shows of the areas: names, translated names, slugs and order of every area (the tags and the filter), which
+    # entries' updated_at don't reflect when an area is renamed or entries are moved in bulk.
+    def shiplog_area_etag_parts
+      [ @area&.id, Area.ordered.pluck(:id, :name, :slug, :position, :name_translations) ]
+    end
+
+    # What the markup shows of the entries' screenshots: their blob ids, order and alt texts. Nothing while
+    # screenshots are off. Load the entries with `Entry.with_images_loaded` to avoid a query per entry.
+    def shiplog_image_etag_parts(entries)
+      Shiplog.images? ? entries.compact.map { |entry| [ entry.id, entry.image_etag_parts ] } : []
+    end
+
+    # Loads the translations the page shows (the request locale's) for these entries in one query; see
+    # Entry.preload_translations. Call it before the entries are rendered or their ETag is computed.
+    def preload_translations(*entries)
+      Entry.preload_translations(entries.flatten)
+    end
+
+    # What the markup shows of the entries' translations: which current translation each entry shows, and when
+    # it last changed. Nothing under a locale that is not translated.
+    def shiplog_translation_etag_parts(entries)
+      return [] unless Entry.translated_locale?(I18n.locale)
+
+      entries.compact.filter_map do |entry|
+        translation = entry.translation
+        [ entry.id, translation.id, translation.updated_at ] if translation
+      end
+    end
+
     # What the rendered markup depends on besides the data: the locale, the gem version and the styling
     # config. Host parent controllers rendering per-user layout content should declare `etag { current_user&.id }`.
     def shiplog_etag_parts

data/app/controllers/shiplog/roadmaps_controller.rb

@@ -4,7 +4,9 @@ module Shiplog
       @columns = Roadmap.new(published_only: true).columns
       preload_cards(@columns)
       @shipped = recently_shipped
-      fresh_when etag: [ *shiplog_etag_parts, etag_for(@columns), shipped_etag(@shipped) ]
+      shown = [ *@columns.values.flatten.map(&:entry), *@shipped ]
+      preload_translations(shown)
+      fresh_when etag: [ *shiplog_etag_parts, etag_for(@columns), shipped_etag(@shipped), shiplog_translation_etag_parts(shown) ]
     end
 
     private

data/app/frontend/shiplog/admin.css

@@ -103,6 +103,7 @@
   }
   .shiplog-admin .shiplog-badge--warning { border-color: #bf8700; color: #9a6700; }
   .shiplog-admin .shiplog-badge--error { border-color: #cf222e; color: #cf222e; }
+  .shiplog-admin .shiplog-badge--area { border-color: var(--sa-accent); color: var(--sa-accent); }
 
   .shiplog-admin .shiplog-button {
     background: var(--sa-surface);
@@ -115,6 +116,7 @@
     padding: 0.25rem 0.75rem;
     text-decoration: none;
   }
+  .shiplog-admin .shiplog-button:disabled { cursor: default; opacity: 0.5; }
   .shiplog-admin .shiplog-button--primary { background: var(--sa-accent); border-color: var(--sa-accent); color: #fff; }
 
   .shiplog-admin .shiplog-admin-split { display: grid; gap: 1.5rem; grid-template-columns: repeat(auto-fit, minmax(20rem, 1fr)); }
@@ -125,6 +127,13 @@
   .shiplog-admin .shiplog-admin-form textarea { box-sizing: border-box; font: inherit; width: 100%; }
   .shiplog-admin .shiplog-admin-actions { border-top: 1px solid var(--sa-border); display: grid; gap: 0.75rem; margin-top: 1rem; padding-top: 1rem; }
   .shiplog-admin .shiplog-admin-inline-form { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+  .shiplog-admin .shiplog-admin-images { margin-top: 1rem; }
+  .shiplog-admin .shiplog-admin-images__list { display: grid; gap: 1rem; list-style: none; margin: 0 0 1rem; padding: 0; }
+  .shiplog-admin .shiplog-admin-images__item { align-items: flex-start; border-bottom: 1px solid var(--sa-border); display: flex; flex-wrap: wrap; gap: 1rem; padding-bottom: 1rem; }
+  .shiplog-admin .shiplog-admin-images__thumb { border: 1px solid var(--sa-border); border-radius: 0.25rem; height: auto; max-height: 8rem; max-width: 12rem; object-fit: contain; }
+  .shiplog-admin .shiplog-admin-images__controls { display: grid; flex: 1; gap: 0.5rem; min-width: 16rem; }
+  .shiplog-admin .shiplog-admin__visually-hidden { border: 0; clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }
+  .shiplog-admin .shiplog-area-row__count { text-align: right; }
   .shiplog-admin .shiplog-admin-source { background: var(--sa-bg); overflow-x: auto; padding: 0.75rem; white-space: pre-wrap; word-break: break-word; }
 
   .shiplog-admin .shiplog-board { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); }

data/app/frontend/shiplog/shiplog.css

@@ -152,7 +152,8 @@
   .shiplog-entries { display: grid; gap: 0.75rem; list-style: none; margin: 0; padding: 0; }
 
   .shiplog-card,
-  .shiplog-entry {
+  .shiplog-entry,
+  .shiplog-permalink {
     background: var(--sl-card);
     border: 1px solid var(--sl-border);
     border-radius: var(--sl-radius);
@@ -241,10 +242,14 @@
     width: 0.75rem;
   }
 
-  .shiplog-entry { align-items: center; display: flex; flex-wrap: wrap; gap: 0.25rem 0.625rem; }
+  .shiplog-entry,
+  .shiplog-permalink { align-items: center; display: flex; flex-wrap: wrap; gap: 0.25rem 0.625rem; }
   .shiplog-entry__title,
   .shiplog-entry__body { flex-basis: 100%; }
   .shiplog-entry__title { font-size: 1rem; margin: 0.25rem 0 0; }
+  .shiplog-entry__title a { color: inherit; text-decoration: none; }
+  .shiplog-entry__title a:hover { color: var(--sl-accent); text-decoration: underline; }
+  .shiplog-entry__title a:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
   .shiplog-entry__body { color: var(--sl-muted); }
   .shiplog-entry__date { color: var(--sl-muted); font-size: 0.8125rem; }
 
@@ -256,6 +261,9 @@
     font-weight: 600;
     padding: 0 0.5rem;
   }
+  .shiplog-permalink .shiplog-entry__title { font-size: 1.5rem; }
+  .shiplog-permalink--feature { border-left: 4px solid var(--sl-accent); }
+  .shiplog-permalink--feature .shiplog-entry__category { background: var(--sl-accent); border-color: var(--sl-accent); color: #fff; }
   .shiplog-entry--feature { border-left: 4px solid var(--sl-accent); padding: var(--sl-space) calc(var(--sl-space) * 1.25); }
   .shiplog-entry--feature .shiplog-entry__title { font-size: 1.25rem; }
   .shiplog-entry--feature .shiplog-entry__category { background: var(--sl-accent); border-color: var(--sl-accent); color: #fff; }
@@ -264,6 +272,43 @@
   .shiplog-pagination__link { color: var(--sl-accent); }
   .shiplog-pagination__link--older { margin-left: auto; }
 
+  .shiplog-permalink__back { color: var(--sl-accent); display: inline-block; margin-top: var(--sl-space); }
+  .shiplog-permalink__nav {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--sl-space);
+    justify-content: space-between;
+    margin-top: calc(var(--sl-space) * 2);
+  }
+  .shiplog-permalink__nav-link { color: var(--sl-accent); }
+  .shiplog-permalink__nav-link--older { margin-left: auto; text-align: right; }
+  .shiplog-permalink__back:focus-visible,
+  .shiplog-permalink__nav-link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+
+  .shiplog-entry__area {
+    color: var(--sl-muted);
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+  }
+
+  .shiplog-entry__images { display: grid; flex-basis: 100%; gap: 0.75rem; margin-top: 0.5rem; }
+  .shiplog-entry__image { border: 1px solid var(--sl-border); border-radius: 0.5rem; display: block; height: auto; max-width: 100%; }
+
+  .shiplog-areas { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: var(--sl-space) 0; }
+  .shiplog-areas__link {
+    border: 1px solid var(--sl-border);
+    border-radius: 1rem;
+    color: var(--sl-fg);
+    font-size: 0.875rem;
+    padding: 0.125rem 0.75rem;
+    text-decoration: none;
+  }
+  .shiplog-areas__link:hover { border-color: var(--sl-accent); }
+  .shiplog-areas__link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+  .shiplog-areas__link--current { background: var(--sl-accent); border-color: var(--sl-accent); color: #fff; }
+
   .shiplog-search { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: var(--sl-space) 0; }
   .shiplog-search__input {
     flex: 1 1 14rem;

data/app/helpers/shiplog/admin/entries_helper.rb

@@ -19,6 +19,21 @@ module Shiplog
         entry.title.presence || source_title(entry.subject)
       end
 
+      # The URL of an image's thumbnail: a 200x200 variant when the host can make them (image_processing and a
+      # processor, see Shiplog.image_variants?), else the original (the stylesheet sizes it).
+      def image_thumbnail_path(image)
+        source = Shiplog.image_variants? && image.variable? ? image.variant(resize_to_limit: [ 200, 200 ]) : image
+        polymorphic_path(source)
+      rescue ActionController::UrlGenerationError, NoMethodError, ArgumentError
+        nil
+      end
+
+      # "Spanish (es)" for a locale of config.locales; the code alone when Shiplog has no name for the language.
+      def translation_language_label(locale)
+        name = Shiplog::Translator.language_name(locale)
+        name == locale.to_s ? name : "#{name} (#{locale})"
+      end
+
       def entries_filter_path(status: nil, kind: nil, page: nil)
         root_path({ status:, kind:, page: }.compact_blank)
       end

data/app/helpers/shiplog/head_helper.rb

@@ -0,0 +1,95 @@
+module Shiplog
+  # The data side of `<%= shiplog_head_tags %>` (see HeadTagsHelper, the only helper every view gets). Included
+  # in the engine's public controllers only.
+  #
+  # The views declare their page with #shiplog_head_page (which also fills the older `content_for` blocks, kept
+  # for backward compatibility); the partials below are overridable by the host app:
+  #   shiplog/_head_tags             renders the four below
+  #   shiplog/head/_meta             description, canonical, robots
+  #   shiplog/head/_open_graph       og:* and twitter:*
+  #   shiplog/head/_feed             the Atom alternate link
+  #   shiplog/head/_structured_data  the JSON-LD script
+  # Each receives the locals `head` (a Hash: :kind, :title, :url, :entry, :image, :canonical), `description`,
+  # `canonical`, `robots`, `open_graph` and `twitter` (Hashes of tag name => content), `feed_url`, `feed_title`
+  # and `json_ld`. Whatever `except:` removed arrives as nil or an empty Hash.
+  module HeadHelper
+    # Renders the head tags of the current page, leaving out the `skip` groups (see HeadTagsHelper, which
+    # validates and guards). An empty string when the page declared none.
+    def shiplog_render_head_tags(skip)
+      return "".html_safe unless @shiplog_head
+
+      render(partial: "shiplog/head_tags", locals: shiplog_head_locals(skip))
+    end
+
+    # Declares the page for shiplog_head_tags and fills the older content_for blocks (which shiplog_head_tags
+    # never reads). `kind` is :permalink,
+    # :changelog or :roadmap; the rest is what the page computed: entry (permalink), title, url (the page's
+    # absolute URL, nil for a search), query (a search), json_ld, feed (whether it advertises the Atom feed).
+    def shiplog_head_page(kind, title:, url: nil, entry: nil, query: nil, json_ld: nil, feed: true)
+      @shiplog_head = { kind:, title:, url:, entry:, query:, json_ld:, feed: }
+      shiplog_fill_legacy_blocks
+    end
+
+    private
+
+    def shiplog_fill_legacy_blocks
+      head = @shiplog_head
+      entry = head[:entry]
+      blocks = {
+        shiplog_description: (shiplog_entry_description(entry) if entry),
+        shiplog_og: (shiplog_og_tags(entry, url: head[:url]) if entry),
+        shiplog_robots: ("noindex" if head[:query]),
+        shiplog_feed: shiplog_head_feed_link(head),
+        shiplog_structured_data: head[:json_ld]
+      }
+      blocks.each { |name, value| content_for(name, value) if value.present? }
+    end
+
+    def shiplog_head_feed_link(head)
+      return unless head[:feed]
+
+      auto_discovery_link_tag(:atom, shiplog_absolute_url(:changelog_feed), title: shiplog_feed_title)
+    end
+
+    def shiplog_feed_title = t("shiplog.feed.link_title", default: "Changelog (Atom)")
+
+    def shiplog_head_locals(skip)
+      head = @shiplog_head
+      entry = head[:entry]
+      # A search page has no canonical: it is noindex, and noindex with a canonical sends search engines two
+      # signals that disagree.
+      canonical = head[:url] unless head[:query]
+      image = shiplog_entry_og_image(entry) if entry
+      description = shiplog_entry_description(entry) if entry
+      page = head.slice(:kind, :title, :entry).merge(canonical:, image:, description:)
+
+      {
+        head: page,
+        description: (description unless skip.include?(:description)),
+        canonical: (canonical unless skip.include?(:canonical)),
+        robots: ("noindex" if head[:query] && !skip.include?(:robots)),
+        open_graph: (skip.include?(:open_graph) ? {} : shiplog_head_open_graph(head, canonical, image, description)),
+        twitter: (skip.include?(:twitter) ? {} : shiplog_head_twitter(image)),
+        feed_url: (shiplog_absolute_url(:changelog_feed) if head[:feed] && !skip.include?(:feed)),
+        feed_title: shiplog_feed_title,
+        json_ld: (head[:json_ld] unless skip.include?(:structured_data))
+      }
+    end
+
+    def shiplog_head_open_graph(head, canonical, image, description)
+      entry = head[:entry]
+      {
+        "og:title" => (entry ? entry.display_title : head[:title]),
+        "og:description" => description,
+        "og:type" => (entry ? "article" : "website"),
+        "og:url" => canonical,
+        "og:image" => image,
+        "og:image:alt" => (entry.display_title if image)
+      }.compact_blank
+    end
+
+    def shiplog_head_twitter(image)
+      { "twitter:card" => (image ? "summary_large_image" : "summary"), "twitter:image" => image }.compact_blank
+    end
+  end
+end

data/app/helpers/shiplog/head_tags_helper.rb

@@ -0,0 +1,24 @@
+module Shiplog
+  # The one helper added to every view of the host (like a pagination gem's `paginate`), so a layout shared
+  # with the host's own pages can call `shiplog_head_tags`. The rest lives in Shiplog::HeadHelper, which only
+  # the engine's controllers include.
+  module HeadTagsHelper
+    EXCEPT_KEYS = %i[description canonical robots open_graph twitter feed structured_data].freeze
+
+    # The head tags of the current Shiplog page; an empty string on any other page. `except:` leaves groups
+    # out, for tags your layout already writes: :description, :canonical, :robots, :open_graph, :twitter,
+    # :feed, :structured_data. An unknown key raises ArgumentError.
+    #
+    # Use it OR the older `content_for :shiplog_*` blocks in a layout, not both: both would emit the tags twice.
+    def shiplog_head_tags(except: [])
+      keys = Array(except).map { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+      unknown = keys - EXCEPT_KEYS
+      if unknown.any?
+        raise ArgumentError, "Unknown shiplog_head_tags except: key(s) #{unknown.map(&:inspect).join(", ")}. Valid keys: #{EXCEPT_KEYS.map(&:inspect).join(", ")}"
+      end
+      return "".html_safe unless controller.is_a?(Shiplog::PublicController)
+
+      shiplog_render_head_tags(keys)
+    end
+  end
+end