shiplog 0.3.2 → 0.4.0

data/app/jobs/shiplog/send_newsletter_job.rb

@@ -0,0 +1,64 @@
+module Shiplog
+  # Emails an approved announcement to every recipient (Newsletter::Recipients: the host's users, then the
+  # confirmed subscribers, minus the unsubscribed and the duplicates), once per recipient. For each chunk of
+  # NewsletterDelivery::CLAIM_SIZE it inserts the delivery rows first (one statement, skipping the rows that
+  # exist) and emails only the recipients it inserted, touching each row right before its send, so a retried
+  # job, a second click on Send or two workers never send twice: at most once per recipient. A failed delivery
+  # is recorded on its row (never raised: the chunk goes on) for the admin's "Retry failed", which runs the job
+  # with `retry_failed: true`: the failed and stalled rows are reclaimed in one statement, the ones reclaimed by
+  # this run are sent again, and the ones whose recipient is gone end as failed with the reason.
+  #
+  # The announcement's Markdown is rendered once per locale (Newsletter::Content); each message is then built with
+  # the recipient's own links. The job stops before anything is sent when the newsletter is off or the
+  # announcement cannot be sent (Newsletter.blockers: not approved, missing translations, no sender...).
+  class SendNewsletterJob < ApplicationJob
+    discard_on ActiveJob::DeserializationError, ActiveRecord::RecordNotFound
+
+    def perform(entry, retry_failed: false)
+      return log_skip(entry, "the newsletter is off") unless Newsletter.enabled?
+
+      blockers = Newsletter.blockers(entry)
+      return log_skip(entry, "it cannot be sent: #{blockers.join(", ")}") if blockers.any?
+
+      reclaimed = retry_failed ? NewsletterDelivery.reclaim(entry).to_set : Set.new
+      contents = Hash.new { |hash, locale| hash[locale] = Newsletter::Content.new(entry, locale) }
+      sent = 0
+      Newsletter::Recipients.new.each_batch do |batch|
+        batch.each_slice(NewsletterDelivery::CLAIM_SIZE) do |chunk|
+          claimed = NewsletterDelivery.claim(entry, chunk).to_set
+          chunk.each do |recipient|
+            next unless claimed.include?(recipient.key) || reclaimed.delete?(recipient.key)
+
+            sent += 1 if deliver(entry, recipient, contents[recipient.locale])
+          end
+        end
+      end
+      NewsletterDelivery.mark_missing(entry, reclaimed) # reclaimed, but no longer a recipient
+      Rails.logger.info("[shiplog] Newsletter of entry #{entry.id}: #{sent} emails sent in this run")
+    end
+
+    private
+
+    # Sends one email and records the outcome on the delivery row. True when it was sent.
+    def deliver(entry, recipient, content)
+      NewsletterDelivery.mark_sending(entry, recipient.key)
+      NewsletterMailer.announcement(entry, recipient.email, locale: recipient.locale, content:,
+        unsubscribe_url: Newsletter.unsubscribe_url(recipient.email), preferences_url: preferences_url(recipient)).deliver_now
+      NewsletterDelivery.mark_sent(entry, recipient.key)
+      true
+    rescue StandardError => error
+      NewsletterDelivery.mark_failed(entry, recipient.key, error)
+      Rails.logger.error("[shiplog] Newsletter of entry #{entry.id} to #{recipient.key} failed: #{error.class}: #{NewsletterDelivery.scrub(error.message)}")
+      false
+    end
+
+    # A subscriber's preferences page; a host user's own page when config.newsletter_unsubscribe_url gives one.
+    def preferences_url(recipient)
+      recipient.subscriber? ? Newsletter.preferences_url(recipient.record) : Newsletter.host_unsubscribe_url(recipient.record)
+    end
+
+    def log_skip(entry, reason)
+      Rails.logger.info("[shiplog] Newsletter of entry #{entry.id} not sent: #{reason}")
+    end
+  end
+end

data/app/jobs/shiplog/translate_entry_job.rb

@@ -17,6 +17,8 @@ module Shiplog
 
     def perform(entry, locale, force: false)
       Translator.new(entry, locale).call(force:)
+      # An approved announcement is announced once all its translations are current: this may have been the last.
+      AnnounceJob.perform_later(entry) if entry.announcement?
     rescue StandardError => error
       Rails.logger.error("[shiplog] Translating entry #{entry.id} into #{locale} failed (attempt #{executions} of #{ATTEMPTS}): #{error.class}: #{error.message}")
       raise

data/app/mailers/shiplog/newsletter_mailer.rb

@@ -0,0 +1,51 @@
+module Shiplog
+  # The newsletter's emails: an announcement to one recipient, and the confirmation of a visitor's subscription.
+  # Both have an HTML part (one 600px table column, styles inline, see app/views/shiplog/newsletter_mailer) and a
+  # text part, in the recipient's language (the chrome from Shiplog's I18n keys, the announcement's text from its
+  # translation). Hosts override the templates like any engine view. The sender is config.newsletter_from.
+  class NewsletterMailer < ActionMailer::Base
+    helper Shiplog::NewsletterMailerHelper
+
+    default from: -> { sender! }
+
+    # The announcement for `email` in `locale`. `unsubscribe_url` is the one-click target (the List-Unsubscribe
+    # headers Gmail and Yahoo require; Newsletter.unsubscribe_url for the address when not given, so a queued test
+    # send carries no token), `preferences_url` the page the footer's "Preferences" opens (a subscriber's page, or
+    # the host's own for its users; nil shows the unsubscribe page instead). `content` is the locale's rendered
+    # Content when the caller has it (SendNewsletterJob renders once per locale). config.newsletter_mailer_options
+    # are merged into the message (e.g. Postmark's message_stream); they cannot change the recipient or the subject.
+    def announcement(entry, email, locale:, unsubscribe_url: nil, preferences_url: nil, content: nil)
+      @content = content || Newsletter::Content.new(entry, locale)
+      @unsubscribe_url = unsubscribe_url || Newsletter.unsubscribe_url(email)
+      @preferences_url = preferences_url || @unsubscribe_url
+      headers["List-Unsubscribe"] = "<#{@unsubscribe_url}>"
+      headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
+      headers["Precedence"] = "bulk"
+      I18n.with_locale(Newsletter.i18n_locale(@content.locale)) do
+        mail(**Shiplog.config.newsletter_mailer_options, to: email, subject: @content.subject)
+      end
+    end
+
+    # The double opt-in email: a single-use link (valid 7 days) the subscriber must open, in the locale of the
+    # page they subscribed on. `subscriber` is a NewsletterSubscriber, or its id when queued (deliver_later): a
+    # row deleted or confirmed in the meantime sends nothing, quietly. Transactional: no mailer options, no
+    # List-Unsubscribe.
+    def confirmation(subscriber)
+      @subscriber = subscriber.is_a?(NewsletterSubscriber) ? subscriber : NewsletterSubscriber.find_by(id: subscriber)
+      @confirmation_url = @subscriber && Newsletter.confirmation_url(@subscriber)
+      return unless @confirmation_url
+
+      @product_name = Newsletter.product_name
+      I18n.with_locale(Newsletter.i18n_locale(@subscriber.locale)) do
+        mail(to: @subscriber.email, subject: t("shiplog.newsletter.mail.confirm_subject", product: Newsletter.product_name))
+      end
+    end
+
+    private
+
+    # The From address, or a clear error when none is configured (the job records it on the delivery row).
+    def sender!
+      Newsletter.from or raise ArgumentError, "[shiplog] config.newsletter_from is not set, so no newsletter email can be sent"
+    end
+  end
+end

data/app/models/shiplog/announcements.rb

@@ -0,0 +1,34 @@
+module Shiplog
+  # Monthly announcements: a short, AI-drafted summary of what shipped in a month, approved by an admin like every
+  # other entry (kind "announcement", subject a Shiplog::Period). Where it is published is config.announcements.
+  module Announcements
+    # The slug used when a feature or change approved before 0.4.0 already took the month's own ("2026-10").
+    FALLBACK_SUFFIX = "-update".freeze
+
+    # Drafts the announcement of the month containing `month` and enqueues its rewrite. Returns the new draft, or
+    # nil when announcements are off, the month has no approved feature or change (nothing to announce), or it
+    # has an announcement already (whatever its status).
+    def self.draft(month:)
+      return unless Shiplog.announcements?
+
+      starts_on = month.to_date.beginning_of_month
+      return unless Period.changelog_entries_between(starts_on..starts_on.end_of_month).exists?
+
+      period = Period.month(starts_on)
+      Drafter.draft(period, "announcement", released_on: period.ends_on, slug: slug_for(period))
+    end
+
+    # The months an admin can draft from the admin: the current one (so far) and the previous one.
+    def self.draftable_months(today = Date.current) = [ today.beginning_of_month, today.prev_month.beginning_of_month ]
+
+    # "2026-10", or when an older entry already has that slug "2026-10-update", then "2026-10-update-2", ...
+    def self.slug_for(period)
+      month = period.starts_on.strftime("%Y-%m")
+      candidates = Enumerator.new do |yielder|
+        yielder << month << "#{month}#{FALLBACK_SUFFIX}"
+        (2..).each { |suffix| yielder << "#{month}#{FALLBACK_SUFFIX}-#{suffix}" }
+      end
+      candidates.find { |slug| !Entry.where(slug:).where.not(subject: period).exists? }
+    end
+  end
+end

data/app/models/shiplog/area_detector.rb

@@ -99,9 +99,10 @@ module Shiplog
       end
 
       # Entries that may still get an area: drafts and approved ones with a title, no area, none chosen by an admin,
-      # not asked about yet.
+      # not asked about yet. Announcements cover a whole month and never get one.
       def candidates
         Entry.where(status: %w[draft approved], area_id: nil, area_set_by_admin: false, area_detected_at: nil).where.not(title: [ nil, "" ])
+          .where.not(kind: "announcement")
       end
 
       # Ignores ids outside the batch and areas that don't exist. The update re-checks the conditions, so an

data/app/models/shiplog/change_candidates.rb

@@ -17,6 +17,10 @@ module Shiplog
       repository.pull_requests.awaiting_upgrade_check.where(merged_at: since..).reorder(:merged_at).pick(:merged_at)
     end
 
+    # Node ids of the pull requests (of any repository) linked to an issue that is public or has a public ancestor:
+    # the feature entry of that issue covers them. The lookup reads no instance state.
+    def self.public_tree_pull_request_ids(pull_requests) = allocate.send(:pull_request_ids_in_public_tree, pull_requests)
+
     def initialize(repository:, since:, before:)
       @repository = repository
       @window = since...before

data/app/models/shiplog/drafter.rb

@@ -14,12 +14,14 @@ module Shiplog
     REQUEUE_AFTER = 1.hour
     REQUEUE_LIMIT = 100
 
-    # Returns the new entry, or nil when one already exists for the subject and kind.
-    def self.draft(subject, kind, released_on: nil)
+    # Returns the new entry, or nil when one already exists for the subject and kind. `attributes` are set on a new
+    # entry only (an announcement's slug).
+    def self.draft(subject, kind, released_on: nil, **attributes)
       entry = Entry.create_or_find_by!(subject:, kind:) do |new_entry|
         new_entry.title = subject.title
         new_entry.body = subject.body
         new_entry.released_on = released_on
+        new_entry.assign_attributes(attributes)
       end
       return unless entry.previously_new_record?
 

data/app/models/shiplog/entry.rb

@@ -7,20 +7,31 @@ module Shiplog
     belongs_to :subject, polymorphic: true
     belongs_to :area, class_name: "Shiplog::Area", optional: true
     has_many :translations, class_name: "Shiplog::EntryTranslation", dependent: :destroy, inverse_of: :entry
+    # The newsletter's deliveries of an announcement (see NewsletterDelivery); the database cascades the delete.
+    has_many :newsletter_deliveries, class_name: "Shiplog::NewsletterDelivery", foreign_key: :announcement_id, dependent: :delete_all, inverse_of: :announcement
 
-    enum :kind, %w[roadmap feature change].index_by(&:itself), validate: true
+    enum :kind, %w[roadmap feature change announcement].index_by(&:itself), validate: true
     enum :status, %w[draft approved discarded].index_by(&:itself), default: "draft", validate: true
 
     CHANGELOG_KINDS = %w[feature change].freeze
+    # The slug of a month's announcement ("2026-10"). Features and changes never get one of this shape, so an
+    # announcement's page URL is known before it is drafted.
+    ANNOUNCEMENT_SLUG = /\A\d{4}-\d{2}\z/
 
     validates :released_on, presence: true, if: -> { approved? && !roadmap? }
     validate :area_exists
     validate :kind_change_allowed, on: :update
     validate :kind_free_for_subject, on: :update
 
+    # An announcement that leaves "approved" may be announced again once it is approved again.
+    before_save :clear_announced_at, if: -> { announcement? && will_save_change_to_status? && !approved? }
+
     # Approving an entry, or changing the English text of an approved one, translates it into every configured
     # locale (see TranslateEntryJob). After the commit, so the job reads what was saved.
     after_commit :enqueue_translations, on: :update, if: :translation_due?
+    # Approving an announcement calls config.on_announcement_approved once its translations are current (see
+    # AnnounceJob, which TranslateEntryJob enqueues too).
+    after_commit :enqueue_announcement, on: :update, if: -> { announcement? && approved? && saved_change_to_status? }
 
     SEARCH_MAX_LENGTH = 100
     SEARCH_MAX_WORDS = 5
@@ -84,11 +95,20 @@ module Shiplog
     # at 99. One COUNT over the (status, approved_at) index. It filters on approved_at, not on released_on (the
     # list's order): "new since you last looked" is about when an entry appeared, so an entry approved today
     # with an earlier release date still counts as new.
-    def self.unseen_count(since: nil)
-      scope = approved.where(kind: CHANGELOG_KINDS)
+    def self.unseen_count(since: nil) = count_approved_since(CHANGELOG_KINDS, since)
+
+    # The number of approved announcements approved after `since` (all of them while it is nil), capped at 99.
+    def self.unseen_announcements_count(since: nil) = count_approved_since("announcement", since)
+
+    def self.count_approved_since(kinds, since)
+      scope = approved.where(kind: kinds)
       scope = scope.where("#{table_name}.approved_at > ?", since) if since
       scope.limit(UNSEEN_COUNT_CAP).count
     end
+    private_class_method :count_approved_since
+
+    # Approved announcements: the ones with a public page (config.announcements = :page) or a host link.
+    scope :published_announcements, -> { approved.where(kind: "announcement").where.not(released_on: nil) }
 
     # Gives every published changelog entry that has no slug one (oldest first, so the oldest keeps the plain
     # slug on duplicate titles). Returns how many it filled.
@@ -134,7 +154,11 @@ module Shiplog
       self.kind = value if CHANGELOG_KINDS.include?(kind) && CHANGELOG_KINDS.include?(value)
     end
 
+    # The digest of what a draft was written from: the GitHub title and body, or for an announcement the month's
+    # entries (Period#content_digest). A draft whose stored digest differs is flagged in the admin.
     def self.digest_for(subject)
+      return subject.content_digest if subject.is_a?(Period)
+
       Digest::SHA256.hexdigest([ subject.title, subject.body ].join("\n"))
     end
 
@@ -200,6 +224,40 @@ module Shiplog
       translated.blank? && body.present? ? body : (translated || body)
     end
 
+    # Whether every configured locale has a current translation (always true without config.locales).
+    def translations_current? = Shiplog.config.locales.all? { |locale| translation(locale) }
+
+    # The title, Markdown body, HTML and plain text of an announcement in a locale (the default one when omitted):
+    # the current translation when there is one, else the English text. For config.on_announcement_approved and the
+    # admin's export.
+    def to_markdown(locale = I18n.default_locale) = display_body(locale).to_s
+    def to_html(locale = I18n.default_locale) = Markdown.to_html(display_body(locale))
+    def to_text(locale = I18n.default_locale) = Markdown.to_text(display_body(locale))
+
+    # The absolute URL of the entry's public page (see PublicLinks), or nil without a slug. For an announcement
+    # with config.announcements = :external, the host's own page is elsewhere (config.announcement_url).
+    def public_url = PublicLinks.entry_url(self)
+
+    # Whether the translations an announcement waits for are there: all current, or none can be made because there
+    # is no rewriter (then hosts get the English text, or an admin's hand-made translations).
+    def translations_ready? = Shiplog.config.rewriter.nil? || translations_current?
+
+    # Runs the block (the host's hook, see AnnounceJob) once for this approval, when this is an approved announcement
+    # not announced yet whose translations are ready (`force: true` skips that last check: the admin's "Notify
+    # now"). The block runs under the row lock and announced_at is stored in the same transaction, so two jobs
+    # never both run it, and a block that raises (or a worker that dies) stores nothing and is run again by the
+    # retry. Returns whether the block ran.
+    def announce!(force: false)
+      with_lock do
+        reload
+        next false unless announcement? && approved? && announced_at.nil? && (force || translations_ready?)
+
+        yield
+        update_columns(announced_at: Time.current)
+        true
+      end
+    end
+
     def source_changed?
       source_digest.present? && source_digest != self.class.digest_for(subject)
     end
@@ -214,16 +272,28 @@ module Shiplog
       Shiplog.config.locales.each { |locale| TranslateEntryJob.perform_later(self, locale) }
     end
 
+    # Features and changes get a slug when approved; an announcement gets its month's slug when drafted.
     def permalinked? = CHANGELOG_KINDS.include?(kind)
 
+    # Written whatever this instance holds: AnnounceJob sets the column with update_columns, so an instance loaded
+    # before it may still hold nil and would otherwise see no change to save.
+    def clear_announced_at
+      self.announced_at = nil
+      attribute_will_change!("announced_at")
+    end
+
+    def enqueue_announcement
+      AnnounceJob.perform_later(self)
+    end
+
     # The title parameterized and cut at 80 characters, made unique with -2, -3, ...; entry-<id> when the title
-    # has nothing left. The uniqueness check can lose a race, which the unique index catches (see
-    # retrying_on_slug_conflict).
+    # has nothing left. A month's shape ("2026-10") is kept for announcements and gets a suffix too. The
+    # uniqueness check can lose a race, which the unique index catches (see retrying_on_slug_conflict).
     def generate_slug
       base = dashed_title.first(SLUG_MAX_LENGTH).gsub(/\A-+|-+\z/, "").presence || "entry-#{id}"
       candidate = base
       suffix = 2
-      while self.class.where(slug: candidate).where.not(id:).exists?
+      while ANNOUNCEMENT_SLUG.match?(candidate) || self.class.where(slug: candidate).where.not(id:).exists?
         tail = "-#{suffix}"
         candidate = "#{base.first(SLUG_MAX_LENGTH - tail.length).delete_suffix("-")}#{tail}"
         suffix += 1

data/app/models/shiplog/markdown.rb

@@ -0,0 +1,233 @@
+module Shiplog
+  # A small, dependency-free Markdown subset for announcement bodies (written by an LLM, edited by an admin, shown
+  # on public pages, in the feed and in emails). XSS-safe by construction: every piece of source text is escaped
+  # before it is placed in a tag we build ourselves, and raw HTML is never passed through.
+  module Markdown
+    HEADING = /\A {0,3}(\#{1,6})[ \t]+(.*?)(?:[ \t]+\#+)?[ \t]*\z/
+    RULE = /\A {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*\z/
+    ITEM = /\A([ \t]*)([-*+]|\d+[.)])[ \t]+(.*)\z/
+    QUOTE = /\A {0,3}>[ \t]?(.*)\z/
+    LINK = /\G\[((?:\\.|[^\]\\])*)\]\(((?:[^()\\]|\\.|\([^()]*\))*)\)/
+    IMAGE = /\G!\[((?:\\.|[^\]\\])*)\]\(((?:[^()\\]|\\.|\([^()]*\))*)\)/
+    ESCAPABLE = %w[* _ [ ] ( ) ` \\ # ! -].freeze
+    LINK_URL = %r{\A(?:https?://|mailto:|#|/(?![/\\]))}i
+    IMAGE_URL = %r{\A(?:https?://|/(?![/\\]))}i
+    CONTROL_CHARS = /[[:cntrl:]]/
+
+    # Block-level HTML for +text+. Heading levels are shifted by +heading_offset+ (clamped to h1..h6). +styles+
+    # maps tag names to inline styles ({ "p" => "margin:0 0 12px;" }) for emails, where stylesheets are ignored.
+    def self.to_html(text, heading_offset: 0, styles: {})
+      html = blocks(text).map { |block| render_block_html(block, heading_offset, styles) }.join("\n")
+      html.html_safe # every fragment was escaped or built by us
+    end
+
+    # Plain text (no HTML escaping) for emails and meta descriptions; blocks are separated by a blank line.
+    def self.to_text(text)
+      blocks(text).filter_map { |block| render_block_text(block) }.join("\n\n")
+    end
+
+    # Splits the source into [:heading, level, text], [:paragraph, text], [:quote, text], [:list, ordered, items]
+    # and [:rule] blocks.
+    def self.blocks(text)
+      lines = text.to_s.gsub(/\r\n?/, "\n").split("\n")
+      result = []
+      until lines.empty?
+        line = lines.first
+        if line.strip.empty?
+          lines.shift
+        elsif (match = line.match(HEADING))
+          lines.shift
+          result << [ :heading, match[1].length, match[2] ]
+        elsif line.match?(RULE)
+          lines.shift
+          result << [ :rule ]
+        elsif line.match?(ITEM)
+          result << take_list(lines)
+        elsif line.match?(QUOTE)
+          result << [ :quote, take_while(lines) { |l| l.match(QUOTE)&.[](1) }.join("\n") ]
+        else
+          result << [ :paragraph, take_paragraph(lines).join("\n").strip ]
+        end
+      end
+      result
+    end
+    private_class_method :blocks
+
+    def self.block_start?(line)
+      line.match?(HEADING) || line.match?(RULE) || line.match?(ITEM) || line.match?(QUOTE)
+    end
+    private_class_method :block_start?
+
+    # Shifts consecutive lines for which the block returns a (non-nil) value, and returns those values.
+    def self.take_while(lines)
+      taken = []
+      while lines.any? && (value = yield(lines.first))
+        taken << value
+        lines.shift
+      end
+      taken
+    end
+    private_class_method :take_while
+
+    def self.take_paragraph(lines)
+      [ lines.shift ] + take_while(lines) { |l| l unless l.strip.empty? || block_start?(l) }
+    end
+    private_class_method :take_paragraph
+
+    # Items of one list kind. Indented items continue the list, indented non-item lines continue the last item, and
+    # blank lines are skipped only when the next non-blank line is another item of the same kind.
+    def self.take_list(lines)
+      ordered = ordered_item?(lines.first)
+      items = []
+      until lines.empty?
+        line = lines.first
+        if line.strip.empty?
+          following = lines.find { |l| !l.strip.empty? }
+          break unless following&.match?(ITEM) && !following.match?(RULE) && ordered_item?(following) == ordered
+          lines.shift
+        elsif line.match?(RULE) || (line.match?(ITEM) && ordered_item?(line) != ordered)
+          break
+        elsif (match = line.match(ITEM))
+          items << match[3].strip
+          lines.shift
+        elsif line.match?(/\A[ \t]+\S/) && !line.match?(HEADING) && !line.match?(QUOTE)
+          items[-1] = "#{items.last}\n#{line.strip}"
+          lines.shift
+        else
+          break
+        end
+      end
+      [ :list, ordered, items ]
+    end
+    private_class_method :take_list
+
+    def self.ordered_item?(line) = line.match(ITEM)[2].match?(/\d/)
+    private_class_method :ordered_item?
+
+    # In HTML mode, +styles+ (a Hash, maybe empty) stands for the html flag of the inline renderers.
+    def self.render_block_html(block, heading_offset, styles)
+      case block.first
+      when :heading
+        level = (block[1] + heading_offset).clamp(1, 6)
+        "#{open("h#{level}", styles)}#{inline(block[2], styles)}</h#{level}>"
+      when :paragraph then "#{open("p", styles)}#{inline(block[1], styles)}</p>"
+      when :quote then "#{open("blockquote", styles)}#{open("p", styles)}#{inline(block[1], styles)}</p></blockquote>"
+      when :rule then open("hr", styles)
+      when :list
+        tag = block[1] ? "ol" : "ul"
+        items = block[2].map { |item| "#{open("li", styles)}#{inline(item, styles)}</li>" }.join("\n")
+        "#{open(tag, styles)}\n#{items}\n</#{tag}>"
+      end
+    end
+    private_class_method :render_block_html
+
+    # "<p>" or, with an inline style for the tag, "<p style="...">" (the style escaped like any attribute).
+    def self.open(tag, styles) = "<#{tag}#{style(tag, styles)}>"
+    private_class_method :open
+
+    def self.style(tag, styles)
+      value = styles[tag] if styles.is_a?(Hash)
+      value.present? ? %( style="#{escape(value, true)}") : ""
+    end
+    private_class_method :style
+
+    def self.render_block_text(block)
+      case block.first
+      when :heading then inline(block[2], false)
+      when :paragraph, :quote then inline(block[1], false)
+      when :list
+        block[2].each_with_index.map { |item, i| "#{block[1] ? "#{i + 1}." : "-"} #{inline(item, false)}" }.join("\n")
+      end
+    end
+    private_class_method :render_block_text
+
+    # Scans left to right; whatever is not a recognised construct is literal (and escaped in HTML mode).
+    def self.inline(source, html)
+      out = +""
+      i = 0
+      while i < source.length
+        output, i = inline_token(source, i, html)
+        out << output
+      end
+      out
+    end
+    private_class_method :inline
+
+    # Consumes one construct (or one literal character) at index +i+; returns its output and the next index.
+    def self.inline_token(source, i, html)
+      char = source[i]
+      if char == "\\" && ESCAPABLE.include?(source[i + 1])
+        [ escape(source[i + 1], html), i + 2 ]
+      elsif char == "`" && source[i + 1] == "`"
+        run = source[i..][/\A`+/]
+        [ run, i + run.length ] # a run of backticks (such as a ``` fence) is literal text
+      elsif char == "`" && (close = source.index("`", i + 1))
+        code = source[(i + 1)...close]
+        [ html ? "#{open("code", html)}#{escape(code, true)}</code>" : code, close + 1 ]
+      elsif char == "!" && (match = source.match(IMAGE, i))
+        [ image(match[1], match[2], html), i + match[0].length ]
+      elsif char == "[" && (match = source.match(LINK, i))
+        [ link(match[1], match[2], html), i + match[0].length ]
+      elsif char == "*" && (emphasis = emphasis(source, i, html))
+        emphasis
+      else
+        [ escape(char, html), i + 1 ]
+      end
+    end
+    private_class_method :inline_token
+
+    # **strong** or *em* when a closing marker exists and the content does not start with a space.
+    def self.emphasis(source, i, html)
+      marker = source[i, 2] == "**" ? "**" : "*"
+      start = i + marker.length
+      close = closing_marker(source, start, marker)
+      return if close.nil? || close == start || source[start].match?(/\s/)
+
+      inner = inline(source[start...close], html)
+      tag = marker == "**" ? "strong" : "em"
+      [ html ? "#{open(tag, html)}#{inner}</#{tag}>" : inner, close + marker.length ]
+    end
+    private_class_method :emphasis
+
+    # Index of the next unescaped +marker+ at or after +from+.
+    def self.closing_marker(source, from, marker)
+      i = from
+      while i < source.length
+        if source[i] == "\\"
+          i += 2
+        elsif source[i, marker.length] == marker
+          return source[i + marker.length] == "*" && marker == "**" ? i + 1 : i # "***": the last two close
+        else
+          i += 1
+        end
+      end
+      nil
+    end
+    private_class_method :closing_marker
+
+    # An anchor for allowed URLs, otherwise just the (escaped) text. Plain text shows "text (url)".
+    def self.link(label, url, html)
+      text = inline(label, html)
+      return text unless allowed_url?(url, LINK_URL)
+      return (text == url ? text : "#{text} (#{url})") unless html
+
+      %(<a href="#{escape(url, true)}"#{style("a", html)}>#{text}</a>)
+    end
+    private_class_method :link
+
+    # An img tag for allowed URLs, otherwise just the escaped alt text.
+    def self.image(alt, url, html)
+      text = inline(alt, false)
+      return escape(text, html) unless html && allowed_url?(url, IMAGE_URL)
+
+      %(<img src="#{escape(url, true)}" alt="#{escape(text, true)}" loading="lazy"#{style("img", html)}>)
+    end
+    private_class_method :image
+
+    def self.allowed_url?(url, pattern) = url.match?(pattern) && !url.match?(CONTROL_CHARS)
+    private_class_method :allowed_url?
+
+    def self.escape(text, html) = html ? ERB::Util.html_escape(text).to_str : text
+    private_class_method :escape
+  end
+end