shiplog 0.3.1 → 0.4.0

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

@@ -42,9 +42,11 @@ module Shiplog
 
       private
 
-      # Every subject type (issue, pull request, commit) belongs to a repository; load them once per type.
+      # Issues, pull requests and commits belong to a repository (periods don't); load them once per type.
       def preload_repositories(entries)
-        entries.filter_map(&:subject).group_by(&:class).each_value do |subjects|
+        entries.filter_map(&:subject).group_by(&:class).each do |type, subjects|
+          next unless type.reflect_on_association(:repository)
+
           ActiveRecord::Associations::Preloader.new(records: subjects, associations: :repository).call
         end
       end
@@ -53,8 +55,10 @@ module Shiplog
         @entry = Entry.find(params[:id])
       end
 
+      # An announcement's month, release date and area follow from its period: only its text is edited.
       def entry_params
-        params.expect(entry: %i[title body released_on changelog_kind area_id])
+        permitted = params.expect(entry: %i[title body released_on changelog_kind area_id])
+        @entry.announcement? ? permitted.slice(:title, :body) : permitted
       end
 
       def page_number

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

@@ -0,0 +1,47 @@
+module Shiplog
+  module Admin
+    # The newsletter's subscribers (the visitors who subscribed through Shiplog's form; the host's users are its
+    # own): counts per locale and status, a searchable paginated list, removal, and a CSV export (.csv, the
+    # search applied; cells that look like formulas are neutralised, see Newsletter::Csv).
+    class NewsletterSubscribersController < ApplicationController
+      PER_PAGE = 100
+      MAX_PAGE = 100_000
+
+      before_action :require_newsletter
+
+      def index
+        @query = params[:q].is_a?(String) ? params[:q].squish.first(NewsletterSubscriber::EMAIL_MAX_LENGTH) : ""
+        scope = NewsletterSubscriber.search(@query).newest_first
+        respond_to do |format|
+          format.html do
+            @counts = NewsletterSubscriber.counts_by_locale
+            @page = page_number
+            records = scope.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
+            @more = records.size > PER_PAGE
+            @subscribers = records.first(PER_PAGE)
+          end
+          format.csv do
+            send_data Newsletter::Csv.generate(scope), type: "text/csv; charset=utf-8", disposition: "attachment",
+              filename: "shiplog-newsletter-subscribers-#{Date.current.iso8601}.csv"
+          end
+        end
+      end
+
+      def destroy
+        subscriber = NewsletterSubscriber.find(params[:id])
+        subscriber.destroy!
+        redirect_to newsletter_subscribers_path(q: params[:q].presence), notice: t("shiplog.admin.newsletter.removed", email: subscriber.email)
+      end
+
+      private
+
+      def require_newsletter
+        head :not_found unless Shiplog.newsletter?
+      end
+
+      def page_number
+        Integer(params[:page].to_s, 10, exception: false).to_i.clamp(1, MAX_PAGE)
+      end
+    end
+  end
+end

data/app/controllers/shiplog/changelog_entries_controller.rb

@@ -1,11 +1,13 @@
 module Shiplog
-  # The permalink page of a published feature or change: /changelog/:slug.
+  # The permalink page of a published feature or change, or of a month's announcement: /changelog/:slug.
   class ChangelogEntriesController < PublicController
     def show
-      @entry = Entry.published_changelog.with_images_loaded.find_by(slug: params[:slug])
+      @entry = Entry.published_changelog.with_images_loaded.find_by(slug: params[:slug]) || published_announcement
       return pass_to_host_routes unless @entry
 
       notify_changelog_seen
+      return show_announcement if @entry.announcement?
+
       @newer = @entry.newer_changelog_entry
       @older = @entry.older_changelog_entry
       preload_translations(@entry, @newer, @older)
@@ -15,6 +17,16 @@ module Shiplog
 
     private
 
+    # An approved announcement with this slug, when Shiplog renders announcement pages (config.announcements).
+    def published_announcement
+      Entry.published_announcements.find_by(slug: params[:slug]) if Shiplog.announcement_pages?
+    end
+
+    def show_announcement
+      preload_translations(@entry)
+      render :announcement if stale?(etag: [ *shiplog_etag_parts, @entry.id, @entry.updated_at, shiplog_translation_etag_parts([ @entry ]) ])
+    end
+
     # 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.

data/app/controllers/shiplog/changelog_feeds_controller.rb

@@ -1,5 +1,6 @@
 module Shiplog
-  # The Atom feed of the latest published features and changes: /changelog.atom.
+  # The Atom feed of the latest published features and changes, and of the announcements when Shiplog renders
+  # their pages: /changelog.atom.
   class ChangelogFeedsController < PublicController
     LIMIT = 50
 
@@ -7,7 +8,10 @@ module Shiplog
     before_action :set_area
 
     def show
-      scope = Entry.published_changelog.newest_first
+      scope = Entry.published_changelog
+      # Announcements have no area: a feed filtered by area leaves them out.
+      scope = scope.or(Entry.published_announcements) if Shiplog.announcement_pages? && !@area
+      scope = scope.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

data/app/controllers/shiplog/changelogs_controller.rb

@@ -21,14 +21,24 @@ module Shiplog
       @months = records.first(PER_PAGE).group_by { |entry| entry.released_on.beginning_of_month }
       @result_count = scope.count if @query
       shown = @months.values.flatten
+      @announcements = announcements_for(@months.keys)
       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) ]
+        shiplog_image_etag_parts(shown), shiplog_translation_etag_parts(shown),
+        @announcements.values.map { |announcement| [ announcement.id, announcement.slug, announcement.updated_at ] } ]
     end
 
     private
 
+    # The approved announcements of the months shown, by the month's first day (none while announcements are off).
+    def announcements_for(months)
+      return {} unless Shiplog.announcements? && months.any?
+
+      Entry.published_announcements.where(released_on: months.map(&:end_of_month))
+        .index_by { |announcement| announcement.released_on.beginning_of_month }
+    end
+
     # 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

data/app/controllers/shiplog/frontends_controller.rb

@@ -5,7 +5,8 @@ module Shiplog
       "shiplog.css" => { path: ASSET_DIRECTORY.join("shiplog.css"), type: "text/css" },
       "admin.css" => { path: ASSET_DIRECTORY.join("admin.css"), type: "text/css" },
       "board.js" => { path: ASSET_DIRECTORY.join("board.js"), type: "text/javascript" },
-      "inbox.js" => { path: ASSET_DIRECTORY.join("inbox.js"), type: "text/javascript" }
+      "inbox.js" => { path: ASSET_DIRECTORY.join("inbox.js"), type: "text/javascript" },
+      "once.js" => { path: ASSET_DIRECTORY.join("once.js"), type: "text/javascript" }
     }.freeze
 
     # The version segment busts caches; stale versions are 404 so they are never cached as the current file.

data/app/controllers/shiplog/newsletter/confirmations_controller.rb

@@ -0,0 +1,27 @@
+module Shiplog
+  module Newsletter
+    # The double opt-in link: a page with a button (GET changes nothing, link scanners prefetch), and the POST
+    # that confirms. The token is signed and expires after 7 days (Newsletter::Tokens); an invalid one is a 404.
+    # Rendered in the subscriber's language, whatever the page's URL.
+    class ConfirmationsController < NewsletterController
+      around_action :with_subscriber
+
+      def show
+      end
+
+      def create
+        @subscriber.confirm!
+        render :create
+      end
+
+      private
+
+      def with_subscriber
+        @subscriber = Tokens.subscriber_for(params[:token])
+        return render_invalid_link unless @subscriber
+
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/preferences_controller.rb

@@ -0,0 +1,50 @@
+module Shiplog
+  module Newsletter
+    # A subscriber's preferences, reached through the token of the newsletter's footer, without an account:
+    # change the language, unsubscribe, resubscribe (the token proves the mailbox, so no new confirmation), and
+    # "delete my data", which removes the row. The token is rotated after each change (the next page uses the
+    # new one; the link in the old email stops working). Rendered in the subscriber's language, and still
+    # available while config.newsletter is off, so an old email's link keeps working.
+    class PreferencesController < NewsletterController
+      skip_before_action :require_newsletter
+      before_action :require_newsletter_tables
+      around_action :with_subscriber
+
+      def show
+      end
+
+      # locale (one of the allowed ones) and/or subscribed ("0" unsubscribes from both lists, "1" resubscribes).
+      # The notice is worded in the language just chosen, which the next page is in.
+      def update
+        notice = "saved"
+        case params[:subscribed]
+        when "0"
+          Newsletter.unsubscribe(@subscriber.email)
+          notice = "unsubscribed"
+        when "1"
+          @subscriber.resubscribe!
+          notice = "resubscribed"
+        end
+        @subscriber.update!(locale: NewsletterSubscriber.resolve_locale(params[:locale])) if params[:locale].is_a?(String)
+        @subscriber.rotate_token!
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) do
+          redirect_to newsletter_preferences_path(@subscriber.token), notice: t("shiplog.newsletter.preferences.#{notice}")
+        end
+      end
+
+      def destroy
+        @subscriber.destroy!
+        render :destroy
+      end
+
+      private
+
+      def with_subscriber
+        @subscriber = NewsletterSubscriber.find_by(token: params[:token].to_s)
+        return render_invalid_link unless @subscriber
+
+        I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/subscriptions_controller.rb

@@ -0,0 +1,70 @@
+module Shiplog
+  module Newsletter
+    # The subscribe form's target and the "check your inbox" page it leads to.
+    class SubscriptionsController < NewsletterController
+      PER_IP = 20
+      PER_EMAIL = 3
+      # All confirmation emails together, an hour: a ceiling on what a distributed bot can make Shiplog send.
+      GLOBAL = 300
+      WINDOW = 1.hour
+      # The honeypot's field name: nothing a browser autofills (no "website", "url", "phone"...).
+      HONEYPOT = :nl_extra
+
+      # The form sits on public pages that are served with ETags: a 304 revisits a cached page, whose CSRF token
+      # may belong to another session or be expired, and a host layout may cache it further. So the form sends no
+      # token and this action checks none: it changes no session state, and nothing happens until the address
+      # confirms by email (double opt-in), so a forged POST can at most send someone a confirmation email, which
+      # the rate limits bound.
+      skip_forgery_protection only: :create
+
+      # Rails.cache counts the attempts (a null store counts nothing: the limits are then off, as in tests). The
+      # per-address count is keyed by a digest of the normalised address (Newsletter.rate_limit_key), so the cache
+      # holds no address and "a+tag@gmail.com" and "a.b@gmail.com" count as one.
+      rate_limit to: PER_IP, within: WINDOW, by: -> { request.remote_ip }, with: -> { rate_limited }, name: "ip", only: :create
+      rate_limit to: PER_EMAIL, within: WINDOW, by: -> { submitted_email.present? ? Newsletter.rate_limit_key(submitted_email) : request.remote_ip }, with: -> { rate_limited }, name: "email", only: :create
+      rate_limit to: GLOBAL, within: WINDOW, by: -> { "all" }, with: -> { rate_limited }, name: "global", only: :create
+
+      # The same redirect for a new, pending, confirmed or unsubscribed address (and for a bot that filled the
+      # honeypot): the form cannot tell who is subscribed. Only an address that is not an email gets the form back.
+      def create
+        return redirect_to(newsletter_subscription_path) if params[HONEYPOT].present?
+
+        subscriber = NewsletterSubscriber.subscribe(submitted_email, locale: I18n.locale, source: submitted_source)
+        if subscriber
+          redirect_to newsletter_subscription_path
+        else
+          @error = t("shiplog.newsletter.form.invalid_email", default: "Enter a valid email address.")
+          @email = submitted_email
+          render :show, status: :unprocessable_content
+        end
+      end
+
+      # "Check your inbox to confirm."
+      def show
+      end
+
+      private
+
+      def submitted_email
+        value = params[:email]
+        value.is_a?(String) ? value.strip.downcase.first(NewsletterSubscriber::EMAIL_MAX_LENGTH + 1) : ""
+      end
+
+      # The page the visitor subscribed on: the form's `source` when it is a same-site path, else the referrer's
+      # path (NewsletterSubscriber.clean_source has the last word).
+      def submitted_source
+        value = params[:source]
+        return value if value.is_a?(String) && NewsletterSubscriber.clean_source(value)
+
+        referer = request.referer.to_s
+        URI.parse(referer).path if referer.present?
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def rate_limited
+        render "shiplog/newsletter/rate_limited", status: :too_many_requests
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter/unsubscriptions_controller.rb

@@ -0,0 +1,36 @@
+module Shiplog
+  module Newsletter
+    # The unsubscribe link of every newsletter, for the host's users and Shiplog's subscribers alike: the token is
+    # the encrypted email (Newsletter::Tokens), so Shiplog needs no row for a host user until they unsubscribe.
+    # GET shows a page with a button; POST unsubscribes the address from both lists (Newsletter.unsubscribe,
+    # which keeps a suppression row and calls config.on_newsletter_unsubscribe). The POST is also the RFC 8058
+    # one-click target the List-Unsubscribe-Post header names: the mail provider sends it with the body
+    # "List-Unsubscribe=One-Click" and no CSRF token, so the action checks none; the token in the URL is what
+    # authorises it. Still available while config.newsletter is off: an old email's link must keep working.
+    class UnsubscriptionsController < NewsletterController
+      skip_before_action :require_newsletter
+      before_action :require_newsletter_tables
+      skip_forgery_protection only: :create
+
+      around_action :with_email
+
+      def show
+      end
+
+      def create
+        Newsletter.unsubscribe(@email)
+        render :create
+      end
+
+      private
+
+      def with_email
+        @email = Tokens.email_for(params[:token])
+        return render_invalid_link unless @email
+
+        subscriber = NewsletterSubscriber.find_by_email(@email)
+        I18n.with_locale(Newsletter.i18n_locale(subscriber ? subscriber.locale : I18n.locale)) { yield }
+      end
+    end
+  end
+end

data/app/controllers/shiplog/newsletter_controller.rb

@@ -0,0 +1,34 @@
+module Shiplog
+  # Parent of the newsletter's public pages (subscribe, confirm, preferences, unsubscribe), all under /shiplog/
+  # so a host that constrains the engine's mount to its own paths lets them through. Subscribing and confirming
+  # answer 404 while the newsletter is off; the unsubscribe and preferences pages keep working as long as the
+  # tables exist (a link in an old email must still unsubscribe). None is ever cached: they are personal (a
+  # token in the URL) or carry a fresh CSRF token.
+  #
+  # None of them changes state on a GET: email link scanners prefetch links, so a link in an email opens a page
+  # with a button, and the button POSTs. The one-click unsubscribe (RFC 8058) is the exception by design: the
+  # mail provider POSTs it (see Newsletter::UnsubscriptionsController).
+  class NewsletterController < PublicController
+    helper Shiplog::NewsletterHelper
+
+    before_action :require_newsletter
+    before_action :no_store
+
+    private
+
+    def require_newsletter
+      head :not_found unless Shiplog.newsletter?
+    end
+
+    # For the pages that outlive config.newsletter: the tables must be there.
+    def require_newsletter_tables
+      head :not_found unless Newsletter.available?
+    end
+
+    # The page for a link that does not verify (tampered, expired, used, or a deleted subscriber). A 404 carries
+    # no hint of which.
+    def render_invalid_link
+      render "shiplog/newsletter/invalid", status: :not_found
+    end
+  end
+end

data/app/controllers/shiplog/public_controller.rb

@@ -11,8 +11,18 @@ module Shiplog
     helper Shiplog::PermalinkHelper
     helper Shiplog::StructuredDataHelper
     helper Shiplog::HeadHelper
+    helper Shiplog::NewsletterHelper
     layout -> { Shiplog.config.public_layout }
 
+    # Marks the controllers of the public pages, for shiplog_head_tags: checking this instead of the class keeps
+    # host pages from autoloading Shiplog::PublicController (and the host's parent controller).
+    def shiplog_public_page? = true
+
+    # The entry a permalink or announcement page shows (nil on the other pages), for config.on_changelog_seen and
+    # host layouts: `controller.shiplog_entry&.announcement?` tells an announcement visit apart.
+    def shiplog_entry = @entry
+    helper_method :shiplog_entry
+
     private
 
     # Calls config.on_changelog_seen for a visit to the changelog index or a permalink page. It runs before

data/app/frontend/shiplog/admin.css

@@ -134,7 +134,12 @@
   .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-preview { background: var(--sa-bg); border-radius: 0.5rem; overflow-wrap: anywhere; padding: 0.75rem 1rem; }
+  .shiplog-admin .shiplog-admin-export { display: inline-flex; gap: 0.5rem; margin-left: 0.75rem; }
   .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-admin-counts { margin-bottom: 1rem; width: auto; }
+  .shiplog-admin .shiplog-admin-counts__number { text-align: right; }
+  .shiplog-admin .shiplog-admin-newsletter__progress { margin: 0 0 0.5rem; }
 
   .shiplog-admin .shiplog-board { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); }
   .shiplog-admin .shiplog-board__title { font-size: 1.125rem; margin: 0 0 0.5rem; }

data/app/frontend/shiplog/once.js

@@ -0,0 +1,31 @@
+// Forms marked data-shiplog-once (the newsletter's Send, Send test and Retry) submit once: their buttons are
+// disabled and marked busy as soon as the form is submitted, so a double click sends one request. The server is
+// idempotent anyway (delivery rows are claimed atomically); this only spares the admin a confusing second request.
+// Buttons come back when the page is restored from the back/forward cache.
+const SELECTOR = "form[data-shiplog-once]"
+
+document.addEventListener("submit", (event) => {
+  const form = event.target
+  if (!(form instanceof HTMLFormElement) || !form.matches(SELECTOR)) return
+
+  if (form.dataset.shiplogSubmitted === "true") {
+    event.preventDefault()
+    return
+  }
+  form.dataset.shiplogSubmitted = "true"
+  form.setAttribute("aria-busy", "true")
+  // Disabled after the submit event, so the clicked button's name and value are still sent.
+  setTimeout(() => {
+    form.querySelectorAll("button, input[type=submit]").forEach((button) => { button.disabled = true })
+  }, 0)
+})
+
+window.addEventListener("pageshow", (event) => {
+  if (!event.persisted) return
+
+  document.querySelectorAll(SELECTOR).forEach((form) => {
+    delete form.dataset.shiplogSubmitted
+    form.removeAttribute("aria-busy")
+    form.querySelectorAll("button, input[type=submit]").forEach((button) => { button.disabled = false })
+  })
+})

data/app/frontend/shiplog/shiplog.css

@@ -285,6 +285,34 @@
   .shiplog-permalink__back:focus-visible,
   .shiplog-permalink__nav-link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
 
+  .shiplog-announcement {
+    background: var(--sl-card);
+    border: 1px solid var(--sl-border);
+    border-left: 4px solid var(--sl-accent);
+    border-radius: var(--sl-radius);
+    padding: calc(var(--sl-space) * 1.25);
+  }
+  .shiplog-announcement .shiplog-entry__category { background: var(--sl-accent); border-color: var(--sl-accent); color: #fff; }
+  .shiplog-announcement__title { font-size: 1.5rem; line-height: 1.25; margin: 0.5rem 0 var(--sl-space); }
+  .shiplog-announcement__body { line-height: 1.6; }
+  .shiplog-announcement__body h3,
+  .shiplog-announcement__body h4,
+  .shiplog-announcement__body h5 { line-height: 1.3; margin: calc(var(--sl-space) * 1.5) 0 0.5rem; }
+  .shiplog-announcement__body h3 { font-size: 1.125rem; }
+  .shiplog-announcement__body h4 { font-size: 1rem; }
+  .shiplog-announcement__body p,
+  .shiplog-announcement__body ul,
+  .shiplog-announcement__body ol,
+  .shiplog-announcement__body blockquote { margin: 0.5rem 0; }
+  .shiplog-announcement__body ul,
+  .shiplog-announcement__body ol { padding-left: 1.25rem; }
+  .shiplog-announcement__body a { color: var(--sl-accent); }
+  .shiplog-announcement__body img { border-radius: var(--sl-radius); height: auto; max-width: 100%; }
+  .shiplog-announcement__body blockquote { border-left: 3px solid var(--sl-border); color: var(--sl-muted); margin-left: 0; padding-left: var(--sl-space); }
+  .shiplog-month__announcement { margin: -0.25rem 0 0.75rem; }
+  .shiplog-month__announcement-link { color: var(--sl-accent); font-weight: 600; }
+  .shiplog-month__announcement-link:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+
   .shiplog-entry__area {
     color: var(--sl-muted);
     font-size: 0.75rem;
@@ -336,6 +364,50 @@
   .shiplog-search__clear { color: var(--sl-accent); margin-left: 0.5rem; }
   .shiplog-search__empty { color: var(--sl-muted); margin: 0; }
 
+  /* Newsletter: the subscribe form on the changelog and announcement pages, and the confirm / preferences /
+     unsubscribe pages (.shiplog-newsletter--page). */
+  .shiplog-newsletter {
+    background: var(--sl-card);
+    border: 1px solid var(--sl-border);
+    border-radius: var(--sl-radius);
+    margin: calc(var(--sl-space) * 2) 0;
+    padding: var(--sl-space) calc(var(--sl-space) * 1.25);
+  }
+  .shiplog-newsletter__title { font-size: 1.125rem; line-height: 1.3; margin: 0 0 0.25rem; }
+  .shiplog-newsletter__hint { color: var(--sl-muted); font-size: 0.875rem; margin: 0 0 0.75rem; }
+  .shiplog-newsletter__form { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; }
+  .shiplog-newsletter__label { font-weight: 500; }
+  .shiplog-newsletter__input {
+    flex: 1 1 14rem;
+    min-width: 0;
+    font: inherit;
+    color: inherit;
+    background: var(--sl-bg);
+    border: 1px solid var(--sl-border);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 0.75rem;
+  }
+  .shiplog-newsletter__button {
+    font: inherit;
+    color: #fff;
+    background: var(--sl-accent);
+    border: 1px solid var(--sl-accent);
+    border-radius: var(--sl-radius);
+    padding: 0.4rem 1rem;
+    cursor: pointer;
+  }
+  .shiplog-newsletter__button--secondary { color: var(--sl-fg); background: transparent; border-color: var(--sl-border); }
+  .shiplog-newsletter__input:focus-visible,
+  .shiplog-newsletter__button:focus-visible { outline: 2px solid var(--sl-accent); outline-offset: 2px; }
+  .shiplog-newsletter__notice { margin: 0 0 0.75rem; }
+  .shiplog-newsletter__notice--error { color: #cf222e; }
+  .shiplog-newsletter__actions { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: var(--sl-space); }
+  .shiplog-newsletter__actions form { margin: 0; }
+  /* The honeypot: out of view for people (never display:none, which some bots detect), labelled for nobody. */
+  .shiplog-newsletter__trap { height: 1px; left: -10000px; overflow: hidden; position: absolute; top: auto; width: 1px; }
+  .shiplog-newsletter--page { margin-top: 0; }
+  .shiplog-newsletter--page p { margin: 0 0 0.75rem; }
+
   @media (max-width: 40rem) {
     .shiplog-page { padding: var(--sl-space) 0.75rem; }
     .shiplog-page__title { font-size: 1.5rem; }

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

@@ -9,8 +9,10 @@ module Shiplog
         subject.is_a?(Commit) ? subject.message.lines.drop(1).join.strip : subject.body.to_s
       end
 
+      # A commit's short sha, a period's month, or "owner/name#123".
       def source_reference(subject)
         return subject.sha.first(7) if subject.is_a?(Commit)
+        return subject.title if subject.is_a?(Period)
 
         "#{subject.repository.full_name}##{subject.number}"
       end

data/app/helpers/shiplog/head_helper.rb

@@ -9,7 +9,7 @@ module Shiplog
   #   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`,
+  # Each receives the locals `head` (a Hash: :kind, :title, :entry, :canonical, :image, :description), `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

data/app/helpers/shiplog/newsletter_helper.rb

@@ -0,0 +1,28 @@
+module Shiplog
+  # The newsletter's subscribe form. The changelog and announcement pages render it while config.newsletter is
+  # on; a host renders it on any page with `helper Shiplog::NewsletterHelper` and `<%= shiplog_newsletter_form %>`
+  # (or `render "shiplog/newsletter/form"` once the helper is included). Nothing is rendered while the newsletter
+  # is off. Uses the engine's own route helpers, or the proxy of the host's mount in host views (see SwitcherHelper).
+  module NewsletterHelper
+    include Shiplog::SwitcherHelper
+
+    # The form (and the bundled stylesheet once per host page, unless config.stylesheet is false). `source` is
+    # recorded with the subscription as the page it was made on; the request's path by default.
+    def shiplog_newsletter_form(source: nil)
+      return "".html_safe unless Shiplog.newsletter?
+
+      stylesheet = if Shiplog.config.stylesheet && !@_shiplog_stylesheet_emitted
+        @_shiplog_stylesheet_emitted = true
+        tag.link(rel: "stylesheet", nonce: content_security_policy_nonce,
+          href: shiplog_routes.frontend_path(version: Shiplog::VERSION, name: "shiplog.css"))
+      end
+      safe_join([ stylesheet, render("shiplog/newsletter/form", source:) ])
+    end
+
+    # The form's action, in the engine's pages and the host's alike.
+    def shiplog_newsletter_subscription_path = shiplog_routes.newsletter_subscription_path
+
+    # The page the subscription is recorded as made on: the given source, else the request's path.
+    def shiplog_newsletter_source(source) = (source.presence || request.path).to_s.first(NewsletterSubscriber::SOURCE_MAX_LENGTH)
+  end
+end

data/app/helpers/shiplog/newsletter_mailer_helper.rb

@@ -0,0 +1,37 @@
+module Shiplog
+  # The inline styles of the newsletter templates: one place for the palette (light colours that email clients
+  # invert sanely in dark mode, no pure black) and the pieces an overriding template can reuse (buttons, cards).
+  module NewsletterMailerHelper
+    PALETTE = {
+      page: "#f3f4f6", card: "#ffffff", text: "#1f2328", muted: "#59636e", border: "#d1d9e0", soft: "#f6f8fa"
+    }.freeze
+    FONT = "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif".freeze
+    RADIUS = "10px".freeze
+
+    def shiplog_mail_palette = PALETTE
+
+    def shiplog_mail_font = FONT
+
+    # A button: a one-cell table (Outlook ignores padding on links) with the accent as background. `margin` is the
+    # table's CSS margin.
+    def shiplog_mail_button(label, url, accent, margin: "24px 0 0")
+      return if url.blank?
+
+      tag.table(role: "presentation", cellpadding: "0", cellspacing: "0", border: "0", style: "margin:#{margin};") do
+        tag.tr(tag.td(style: "background-color:#{accent};border-radius:6px;") do
+          link_to(label, url, style: "display:inline-block;padding:11px 20px;font-family:#{FONT};font-size:15px;font-weight:600;color:#ffffff;text-decoration:none;")
+        end)
+      end
+    end
+
+    # A highlight's screenshot: full width, rounded top corners, sized from the blob's metadata when known.
+    def shiplog_mail_screenshot(highlight)
+      return unless highlight.image?
+
+      options = { alt: highlight.image_alt, width: 600, border: 0,
+        style: "display:block;width:100%;max-width:600px;height:auto;border:0;border-radius:#{RADIUS} #{RADIUS} 0 0;" }
+      options[:height] = (600.0 * highlight.image_height / highlight.image_width).round if highlight.image_width.to_i.positive? && highlight.image_height.to_i.positive?
+      link_to(image_tag(highlight.image_url, **options), highlight.url, style: "display:block;text-decoration:none;")
+    end
+  end
+end