abqari 1.1.0

data/lib/abqari/render_context/cover_helpers.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Abqari
+  class RenderContext
+    # Decorative cover-image generation for posts and other collections
+    # that opt in via the `cover:` enum in config/site.yml. Produces
+    # inline SVG title cards — the page title (word-wrapped to 1-3
+    # lines) on a slug-hashed two-tone gradient, with a small cluster
+    # of decorative squares at the corners (echoing the hand-authored
+    # hero.svg pattern). No file output; the SVG embeds directly in
+    # the partial's HTML.
+    #
+    # The four modes:
+    #
+    #   photo          — use the page's `image:` frontmatter if set;
+    #                    otherwise the basic flat-tint placeholder
+    #                    (`.post-list__cover-placeholder` etc.). The
+    #                    historical default.
+    #   photo_or_svg   — use the page's `image:` if set; otherwise
+    #                    render a decorative initial-tile SVG. Gives
+    #                    text-first authors a polished card without
+    #                    sourcing imagery.
+    #   svg            — always render the decorative SVG, even when
+    #                    `image:` is set. Useful when you want every
+    #                    card to read as a tile (uniform listing look)
+    #                    rather than a mix of photos and tiles.
+    #   none           — no cover slot at all (text-only cards). Same
+    #                    effect as the legacy `show_image: false`.
+    #
+    # Frontmatter `cover:` on a single page overrides the collection
+    # default — `cover: false` is a shortcut for `cover: none`.
+    module CoverHelpers
+      # Muted two-tone gradients. Slug-hashed so each post consistently
+      # gets the same tile across builds, but adjacent posts in a
+      # listing tend to draw different tones (palette entries × hash
+      # distribution = reasonably even spread on any one page).
+      #
+      # The default set is hue-neutral, tuned for `minimal` (and any
+      # custom theme). The warm themes get their own sets in
+      # `THEME_COVER_PALETTES` below — a slug-hashed teal or violet
+      # tile on magazine's cream or notebook's paper page injects a
+      # saturated hue the theme never uses anywhere else, so each
+      # warm theme constrains its tiles to its own colour world.
+      COVER_PALETTES = [
+        ['#1e3a5f', '#4a78a8'].freeze,  # deep blue → mid blue
+        ['#5b3a8a', '#8a6abf'].freeze,  # violet
+        ['#2d4a3d', '#5a8a6a'].freeze,  # forest
+        ['#8a4a2a', '#bf7a4a'].freeze,  # rust
+        ['#3a3a4a', '#6a6a8a'].freeze,  # slate
+        ['#2a5a6a', '#5a8aa0'].freeze,  # teal
+        ['#6a2a3a', '#a05a6a'].freeze,  # burgundy
+        ['#5a5a3a', '#8a8a6a'].freeze   # olive
+      ].freeze
+
+      # Theme-keyed tile palettes for the shipped warm themes. Every
+      # pair keeps the tile dark enough that the near-white title
+      # text stays legible. Themes not listed (minimal, custom,
+      # bootstrap, none) fall back to the neutral COVER_PALETTES.
+      THEME_COVER_PALETTES = {
+        # Cream, rust, editorial — warm browns and rusts, one muted
+        # navy (the theme's info hue) so grids don't go monochrome.
+        'magazine' => [
+          ['#8a4a2a', '#bf7a4a'].freeze,  # rust
+          ['#6a2a3a', '#a05a6a'].freeze,  # burgundy
+          ['#4a3226', '#7a5a42'].freeze,  # deep umber
+          ['#5a5a3a', '#8a8a6a'].freeze,  # olive
+          ['#3a4a5f', '#68809a'].freeze,  # muted navy
+          ['#9a5230', '#c07a50'].freeze   # terracotta
+        ].freeze,
+        # Paper + ochre + graphite — the ochre family carries the
+        # signature, dusty navy echoes `--color-info`.
+        'notebook' => [
+          ['#8a5c14', '#c4811f'].freeze,  # ochre
+          ['#33353a', '#5c6066'].freeze,  # graphite
+          ['#2a5d8f', '#5580ab'].freeze,  # dusty navy
+          ['#565046', '#847c6e'].freeze,  # warm grey
+          ['#6e4a12', '#a06419'].freeze,  # deep ochre
+          ['#4a5a3a', '#75866a'].freeze   # moss
+        ].freeze,
+        # Sun-bleached earth — brick, clay, olive; dusty blue echoes
+        # `--color-info`.
+        'sand' => [
+          ['#7a2018', '#a84438'].freeze,  # brick
+          ['#8a5138', '#b57952'].freeze,  # clay
+          ['#4f5233', '#7a7d55'].freeze,  # olive
+          ['#6e5a3a', '#9a825c'].freeze,  # sand brown
+          ['#4a342a', '#755446'].freeze,  # deep umber
+          ['#3f5a80', '#6d88a8'].freeze   # dusty blue
+        ].freeze
+      }.freeze
+
+      COVER_MODES = %w[photo photo_or_svg svg none].freeze
+      DEFAULT_COVER_MODE = 'photo'
+
+      # Resolve the effective cover mode for a page. Three layers,
+      # frontmatter wins:
+      #   1. Frontmatter `cover:` — explicit string value (one of
+      #      `COVER_MODES`) is honoured directly. Boolean `false` is
+      #      sugar for `'none'`.
+      #   2. Collection config `<collection>.<context>.cover`.
+      #   3. Default `'photo'` (the historical behaviour).
+      #
+      # `context:` is `:index` for listing partials, `:show` for the
+      # detail page. Same enum on both sides, independent config.
+      def cover_mode_for(page, context: :index)
+        fm = page.respond_to?(:frontmatter) ? page.frontmatter['cover'] : nil
+        return 'none'  if fm == false
+        return fm.to_s if COVER_MODES.include?(fm.to_s)
+
+        col = page.respond_to?(:collection) ? page.collection : nil
+        return DEFAULT_COVER_MODE unless col
+
+        (site.collection_config(col).dig(context.to_s, 'cover') || DEFAULT_COVER_MODE).to_s
+      end
+
+      # `cover:` is overloaded: it's usually a MODE enum (`svg`, `none`,
+      # …) but a site can also point it at an image path. This returns
+      # the value ONLY when it's an actual image path — a non-mode,
+      # non-boolean string — so the head partial doesn't turn
+      # `cover: svg` into an `og:image` of `/posts/foo/svg`. Returns nil
+      # for modes, booleans, and blanks.
+      def cover_image_path(page)
+        fm = page.respond_to?(:frontmatter) ? page.frontmatter['cover'] : nil
+        return nil unless fm.is_a?(String)
+        return nil if fm.strip.empty? || COVER_MODES.include?(fm)
+
+        fm
+      end
+
+      # What to actually render for the cover slot, given the resolved
+      # mode and whether the page has an `image:` set. Returns one of:
+      #
+      #   :photo       — render the page's `image:` as an <img>
+      #   :placeholder — render the basic flat-tint SVG rect (the
+      #                  existing `.post-list__cover-placeholder` shape)
+      #   :svg         — render the decorative initial-tile SVG
+      #                  (call `cover_svg_for(page)`)
+      #   :none        — render nothing; caller skips the cover slot
+      #
+      # Centralising the branching here keeps the partials a flat
+      # `case` over the four outcomes instead of repeating the
+      # mode/image cross-product.
+      def cover_choice_for(page, context: :index)
+        mode = cover_mode_for(page, context: context)
+        return :none if mode == 'none'
+
+        has_image = page.respond_to?(:frontmatter) && page.frontmatter['image']
+        case mode
+        when 'photo'        then has_image ? :photo : :placeholder
+        when 'photo_or_svg' then has_image ? :photo : :svg
+        when 'svg'          then :svg
+        end
+      end
+
+      # Inline SVG markup for the decorative title-card cover. Designed
+      # for the 4:3 cover slot but `preserveAspectRatio="xMidYMid slice"`
+      # makes it scale gracefully to wider/taller containers too —
+      # safe to use for the larger show-view hero as well.
+      #
+      # Layout:
+      #   * Slug-hashed two-tone gradient background.
+      #   * Two clusters of three faint white squares (top-left + bottom-
+      #     right) — same motif as the hand-authored hero.svg shipped
+      #     with the fixture's "Building with Abqari" post.
+      #   * Page title, centred, word-wrapped to 1-3 lines. Font size
+      #     auto-scales based on the longest wrapped line so long titles
+      #     stay inside the viewBox.
+      #
+      # The `<linearGradient>` id is suffixed with a slug-hash so
+      # multiple cover SVGs on one page (a posts index card grid, the
+      # home modules, etc.) don't collide on a shared id.
+      def cover_svg_for(page)
+        title         = page.respond_to?(:title) ? page.title.to_s.strip : ''
+        display_title = title.empty? ? '?' : title
+
+        # Slug-keyed where possible (deterministic per page across
+        # builds); falls back to the title. `Zlib.crc32` is stable
+        # across processes — `String#hash` is salted and would change
+        # between builds, scrambling the tile colours each time.
+        key      = page.respond_to?(:slug) && page.slug ? page.slug.to_s : title
+        crc      = Zlib.crc32(key)
+        palette  = cover_palette
+        bg_a, bg_b = palette[crc % palette.size]
+        grad_id  = "cover-grad-#{crc.to_s(36)}"
+
+        lines       = svg_wrap_title(display_title)
+        font_size   = svg_title_font_size(lines)
+        line_height = (font_size * 1.15).round
+        block_h     = line_height * lines.size
+        # First baseline = top of text block + ~0.78 * font_size
+        # (typical cap-height ratio for sans-serif).
+        first_y     = (150 - block_h / 2.0 + font_size * 0.78).round
+
+        text_block = lines.each_with_index.map do |line, i|
+          y = first_y + (line_height * i)
+          %(<text x="200" y="#{y}" text-anchor="middle" font-size="#{font_size}" font-weight="600" letter-spacing="-0.5" fill="rgba(255,255,255,0.96)">#{h(line)}</text>)
+        end.join
+
+        <<~SVG.gsub(/\n\s+/, ' ').strip
+          <svg class="cover-svg" viewBox="0 0 400 300" preserveAspectRatio="xMidYMid slice" aria-hidden="true">
+            <defs>
+              <linearGradient id="#{grad_id}" x1="0" y1="0" x2="1" y2="1">
+                <stop offset="0%" stop-color="#{bg_a}"/>
+                <stop offset="100%" stop-color="#{bg_b}"/>
+              </linearGradient>
+            </defs>
+            <rect width="400" height="300" fill="url(##{grad_id})"/>
+            <g fill="#fff" opacity="0.10">
+              <rect x="20"  y="20"  width="30" height="30" rx="3"/>
+              <rect x="56"  y="20"  width="30" height="30" rx="3"/>
+              <rect x="20"  y="56"  width="30" height="30" rx="3"/>
+              <rect x="314" y="250" width="30" height="30" rx="3"/>
+              <rect x="350" y="250" width="30" height="30" rx="3"/>
+              <rect x="350" y="214" width="30" height="30" rx="3"/>
+            </g>
+            <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif">
+              #{text_block}
+            </g>
+          </svg>
+        SVG
+      end
+
+      # The tile palette for the active theme — theme-keyed when the
+      # theme ships one, the neutral default set otherwise.
+      def cover_palette
+        THEME_COVER_PALETTES.fetch(site.config['theme'].to_s, COVER_PALETTES)
+      end
+
+      # Word-wrap a title into 1-3 lines for the SVG title-card. SVG
+      # `<text>` has no flow, so the layout has to be precomputed.
+      # We pick a line count from the total title length, then pick
+      # the most balanced partition of the words across those lines
+      # — minimising the longest line so the font-size step
+      # (`svg_title_font_size`) gets the best chance of staying
+      # large. Greedy packing would orphan trailing long words onto
+      # a short final line (e.g. "Crisis / Response Foundations");
+      # the balanced search picks "Crisis Response / Foundations"
+      # instead.
+      #
+      # Single-word titles return as-is — long single words just
+      # shrink via the font-size fallback.
+      #
+      # Thresholds are tuned so the rendered text block sits well
+      # inside the 400-wide viewBox — roughly 16% horizontal padding
+      # at the largest font tier, more at smaller tiers. Tighter
+      # thresholds than these and the text crowds the decorative
+      # corner squares; looser and the title looks small in a
+      # mostly-blank tile.
+      def svg_wrap_title(title)
+        words = title.split(/\s+/).reject(&:empty?)
+        return [title] if words.size <= 1
+
+        max_lines = if title.length <= 11
+                      1
+                    elsif title.length <= 26
+                      2
+                    else
+                      3
+                    end
+        return [title] if max_lines == 1
+
+        line_count = [max_lines, words.size].min
+        balanced_word_partition(words, line_count)
+      end
+
+      # Try every contiguous partition of `words` into `line_count`
+      # non-empty groups; return the one whose longest joined line is
+      # shortest (ties broken by smallest length spread). 2-3 lines
+      # over a typical title (<10 words) is a handful of splits —
+      # cheap to enumerate.
+      def balanced_word_partition(words, line_count)
+        return [words.join(' ')] if line_count <= 1
+        return words.dup          if words.size == line_count
+
+        best        = nil
+        best_score  = nil
+        enumerate_splits(words.size, line_count).each do |sizes|
+          lines   = partition_by_sizes(words, sizes)
+          lengths = lines.map(&:length)
+          score   = [lengths.max, lengths.max - lengths.min]
+          # Arrays don't define `<`, only `<=>`. Lexicographic compare
+          # gives the behaviour we want: first the smaller max-line
+          # wins, then the smaller spread breaks ties.
+          if best_score.nil? || (score <=> best_score) < 0
+            best       = lines
+            best_score = score
+          end
+        end
+        best
+      end
+
+      # All compositions of `total` into `parts` positive integers,
+      # e.g. enumerate_splits(3, 2) → [[1,2], [2,1]].
+      def enumerate_splits(total, parts)
+        return [[total]] if parts == 1
+
+        out = []
+        (1..(total - parts + 1)).each do |head|
+          enumerate_splits(total - head, parts - 1).each do |rest|
+            out << [head, *rest]
+          end
+        end
+        out
+      end
+
+      # Split `words` into consecutive groups of the given `sizes`
+      # and join each group with a single space.
+      def partition_by_sizes(words, sizes)
+        out = []
+        i   = 0
+        sizes.each do |sz|
+          out << words[i, sz].join(' ')
+          i += sz
+        end
+        out
+      end
+
+      # Pick a font size that fits the longest wrapped line into the
+      # 400-wide viewBox with margins. Calibrated against the
+      # sans-serif stack declared in `cover_svg_for`. The largest
+      # tier is deliberately modest (36pt) so short titles like
+      # "Upgrading Abqari" or "Quickstart" read as a comfortable
+      # label rather than dominating the tile — title-card SVGs
+      # are decoration, not a billboard.
+      def svg_title_font_size(lines)
+        longest = lines.map(&:length).max.to_i
+        case longest
+        when 0..10  then 36
+        when 11..15 then 32
+        when 16..22 then 28
+        else             24
+        end
+      end
+    end
+  end
+end

data/lib/abqari/render_context/picture_helpers.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Abqari
+  class RenderContext
+    # Image / icon / asset-path helpers. Lifted out of RenderContext so
+    # the main class can stay focused on templating; the behaviour is
+    # unchanged. Every method that emits markup returns already-safe
+    # HTML — templates interpolate via `<%==`.
+    module PictureHelpers
+      HEROICON_VARIANTS = {
+        outline: '24/outline',
+        solid:   '24/solid',
+        mini:    '20/solid',
+        micro:   '16/solid'
+      }.freeze
+
+      def asset_path(name)
+        site.assets.path_for(name)
+      end
+
+      # Like `asset_path`, but returns nil instead of raising when the
+      # asset doesn't exist. Used to conditionally include opt-in site-
+      # local assets like `app/assets/css/site.css` — sites declare one
+      # when they want to add overrides on top of theme + _common.css;
+      # most sites don't, so the link should silently disappear.
+      def optional_asset_path(name)
+        site.assets.path_for(name)
+      rescue ArgumentError
+        nil
+      end
+
+      def picture_tag(source, alt: '', sizes: nil, widths: nil)
+        site.images.picture_tag(source, alt: alt, sizes: sizes, widths: widths)
+      end
+
+      # Site-local SVG icon. Hybrid path — a site can drop
+      # `app/icons/<name>.svg` to override an engine-bundled icon or
+      # add its own.
+      def icon(name, **attrs)
+        path = site.find_in_paths(File.join('app', 'icons', "#{name}.svg"))
+        return '' unless File.exist?(path)
+
+        svg = File.read(path, encoding: 'UTF-8')
+        return svg if attrs.empty?
+
+        attrs_str = attrs.map { |k, v| %(#{h(k.to_s)}="#{h(v.to_s)}") }.join(' ')
+        svg.sub(/<svg([^>]*)>/) { "<svg#{::Regexp.last_match(1)} #{attrs_str}>" }
+      end
+
+      # Inline a Heroicon SVG. Reads from vendor/heroicons/<variant>/
+      # <name>.svg at render time and inlines it directly — no extra
+      # HTTP request, no webfont, no CSP changes (everything is same-
+      # origin static markup). Color and size flow through CSS.
+      #
+      # Variants map to the Heroicons folder layout:
+      #   :outline → 24/outline (24×24 stroke, default)
+      #   :solid   → 24/solid   (24×24 filled)
+      #   :mini    → 20/solid   (20×20 filled, smaller UI)
+      #   :micro   → 16/solid   (16×16 filled, very small UI)
+      #
+      # Returns '' (renders nothing) when the icon name isn't found, so
+      # a typo doesn't fail the build — just an empty span. List of
+      # icon names: https://heroicons.com/
+      def heroicon(name, variant: :outline, **attrs)
+        subdir = HEROICON_VARIANTS[variant.to_sym] or return ''
+        # Heroicons are engine-bundled — they ship in the gem.
+        path = File.join(site.engine_root, 'vendor', 'heroicons', subdir, "#{name}.svg")
+        return '' unless File.exist?(path)
+
+        svg = File.read(path, encoding: 'UTF-8')
+        return svg if attrs.empty?
+
+        attrs_str = attrs.map { |k, v| %(#{h(k.to_s)}="#{h(v.to_s)}") }.join(' ')
+        svg.sub(/<svg([^>]*)>/) { "<svg#{::Regexp.last_match(1)} #{attrs_str}>" }
+      end
+
+      # Resolve a relative bundle-asset filename to an absolute URL by
+      # prepending the current page's URL. Passes through absolute
+      # paths (`/foo`), full URLs (`https://…`), and anchors (`#foo`)
+      # unchanged.
+      #
+      # Used in layouts to render frontmatter image fields that point
+      # at colocated assets — e.g. `image: hero.jpg` in a post or
+      # workshop frontmatter. Markdown body images get auto-rewritten
+      # by the build's post-processor, but frontmatter values bypass
+      # that pass; this helper closes the gap.
+      #
+      # Pair with `sanitized_url` for safe HTML output:
+      #     <img src="<%= sanitized_url(bundle_asset_url(hero)) %>" …>
+      def bundle_asset_url(path)
+        bundle_asset_url_for(page, path)
+      end
+
+      # Like `bundle_asset_url`, but resolves relative paths against
+      # the given `item`'s URL rather than the current `page`. Used by
+      # listing partials (post list, related items, etc.) that render
+      # image fields for many items while the active `page` is the
+      # index.
+      def bundle_asset_url_for(item, path)
+        s = path.to_s
+        return s if s.empty? || s.start_with?('/', 'http://', 'https://', '#')
+
+        base = item.respond_to?(:url) ? item.url : item.to_s
+        "#{base}#{s}"
+      end
+
+      # Bundle-aware <picture> renderer. Three paths, tried in order:
+      #
+      #   1. **Pipeline path (preferred).** When `images.optimise` is
+      #      on AND the bundle image is registered with `ImagePipeline`
+      #      (i.e. it's a raster format the pipeline handles), this
+      #      delegates to the pipeline's `picture_tag_for_url`, which
+      #      emits the same `<picture>` shape as auto-rewritten
+      #      markdown `<img>` tags get. Widths/quality/format come
+      #      from `images:` config — no per-call configuration
+      #      needed.
+      #
+      #   2. **Hand-rolled sibling fallback.** SVGs and any raster
+      #      image whose author manually pre-generated `<basename>.avif`
+      #      and `<basename>.webp` next to the source. Useful for
+      #      sites that haven't migrated to the pipeline yet, or for
+      #      cases where you want explicit control over a specific
+      #      hero image.
+      #
+      #   3. **Plain `<img>`.** Last resort when neither of the above
+      #      applies (e.g. SVGs, which don't benefit from format
+      #      negotiation).
+      def bundle_picture_tag(page, image, alt:, class_: nil, loading: 'eager', fetchpriority: 'high')
+        img_url = sanitized_url(bundle_asset_url_for(page, image))
+
+        # Path 1 — pipeline. Skip for SVGs (vector, nothing to thumbnail).
+        unless image.to_s.end_with?('.svg')
+          extra = { class: class_, loading: loading }
+          extra[:fetchpriority] = fetchpriority if fetchpriority
+          pipeline_html = site.images.picture_tag_for_url(
+            bundle_asset_url_for(page, image),
+            alt: alt,
+            attrs: extra.compact
+          )
+          return pipeline_html if pipeline_html
+        end
+
+        # Path 2 + 3 — hand-rolled siblings or plain <img>.
+        attrs = []
+        attrs << %(class="#{h(class_)}")            if class_
+        attrs << %(src="#{h(img_url)}")
+        attrs << %(alt="#{h(alt)}")
+        attrs << %(loading="#{loading}")
+        attrs << %(fetchpriority="#{fetchpriority}") if fetchpriority
+        attrs << 'decoding="async"'
+        plain_img = "<img #{attrs.join(' ')}>"
+
+        return plain_img if image.to_s.end_with?('.svg')
+        return plain_img unless page.respond_to?(:bundle_dir) && page.bundle_dir
+
+        basename = File.basename(image.to_s, File.extname(image.to_s))
+        avif_path = File.join(page.bundle_dir, "#{basename}.avif")
+        webp_path = File.join(page.bundle_dir, "#{basename}.webp")
+        avif_exists = File.exist?(avif_path)
+        webp_exists = File.exist?(webp_path)
+
+        return plain_img unless avif_exists || webp_exists
+
+        sources = []
+        if avif_exists
+          avif_url = sanitized_url(bundle_asset_url_for(page, "#{basename}.avif"))
+          sources << %(<source type="image/avif" srcset="#{h(avif_url)}">)
+        end
+        if webp_exists
+          webp_url = sanitized_url(bundle_asset_url_for(page, "#{basename}.webp"))
+          sources << %(<source type="image/webp" srcset="#{h(webp_url)}">)
+        end
+
+        "<picture>#{sources.join}#{plain_img}</picture>"
+      end
+    end
+  end
+end

data/lib/abqari/render_context/publication_helpers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Abqari
+  class RenderContext
+    # Publication / bundle / series helpers. Publisher-agnostic — every
+    # method reads canonical fields from a publication, bundle, or
+    # series (manual or externally-sourced) per the schema documented
+    # in docs/publications.md.
+    #
+    # All methods return nil / '' on missing data rather than raising,
+    # so a missing slug or a failed publisher fetch doesn't break a
+    # build. URLs flow through `sanitized_url` before being interpolated
+    # into HTML to defend against `javascript:` and similar scheme
+    # attacks in a hostile or compromised data source.
+    module PublicationHelpers
+      # Resolve a publication slug to a card-ready hash. Every
+      # publication — manual or externally-sourced — lives in
+      # `site.collection('publications')` with frontmatter in canonical
+      # shape, so this is a single lookup against the collection
+      # followed by a small field-mapping into the `_publication_card`
+      # partial's expected key names.
+      #
+      # Returns `{slug:, title: slug}` if the slug isn't in the
+      # collection — keeps the partial renderable without raising.
+      def publication_card_data(slug)
+        slug = slug.to_s
+        pub = site.collection('publications').find do |p|
+          p.respond_to?(:slug) && p.slug == slug
+        end
+        return { slug: slug, title: slug } unless pub
+
+        fm = pub.frontmatter
+        {
+          slug:        slug,
+          title:       pub.title,
+          cover:       fm['cover_url'],
+          description: fm['excerpt'] || fm['tagline'],
+          tagline:     fm['tagline'],
+          price:       fm.dig('price', 'formatted'),
+          isbn:        fm['isbn'],
+          pages:       fm['pages'],
+          published:   fm['published_at']
+        }
+      end
+
+      # Lookups against the merged collections (manual + externally-
+      # sourced). Each returns the canonical-shape frontmatter Hash for
+      # the matching slug, or nil. Useful when a partial needs metadata
+      # about a publication / bundle / series it didn't receive
+      # directly.
+      def publication_for(slug)
+        site.collection('publications').find { |p| p.respond_to?(:slug) && p.slug == slug }&.frontmatter
+      end
+
+      def bundle_for(slug)
+        site.collection('bundles').find { |b| b.respond_to?(:slug) && b.slug == slug }&.frontmatter
+      end
+
+      def series_for(slug)
+        site.collection('series').find { |s| s.respond_to?(:slug) && s.slug == slug }&.frontmatter
+      end
+
+      # Generic buy / cart buttons. Render whenever the corresponding
+      # canonical URL field (`buy_now_url` / `add_to_cart_url`) is set
+      # on the given publication / bundle / series frontmatter — works
+      # equally for native authors who set the URL in frontmatter and
+      # for external publisher integrations (Folio, Payhip, Gumroad,
+      # Lulu Direct, etc.) that supply it via API.
+      #
+      # `subject` can be a frontmatter Hash, a Page-like object (with
+      # `.frontmatter`), or a slug string (looked up in the
+      # publication / bundle / series collections).
+      #
+      # Markup uses the `.folio-button .folio-button--buy` / `--cart`
+      # class family — the visual treatment is kept for continuity with
+      # Folio's storefront so sites mixing engine output with
+      # Folio-embedded HTML get a consistent look. The class names are
+      # a CSS convention, not an indication that the data must come
+      # from Folio.
+      def buy_button(subject, label: 'Buy now', class_: 'folio-button folio-button--buy')
+        fm = resolve_frontmatter(subject)
+        return '' unless fm
+
+        url = sanitized_url(fm['buy_now_url'])
+        return '' unless url
+
+        %(<a class="#{h(class_)}" href="#{h(url)}" rel="noopener noreferrer">#{h(label)}</a>)
+      end
+
+      def cart_button(subject, label: 'Add to cart', class_: 'folio-button folio-button--cart')
+        fm = resolve_frontmatter(subject)
+        return '' unless fm
+
+        url = sanitized_url(fm['add_to_cart_url'])
+        return '' unless url
+
+        %(<a class="#{h(class_)}" href="#{h(url)}" rel="noopener noreferrer">#{h(label)}</a>)
+      end
+
+      private
+
+      # Accept Hash, Page-like, or String (slug). Returns the
+      # frontmatter Hash for the publication / bundle / series, or nil
+      # if the input doesn't resolve. Used by `buy_button` /
+      # `cart_button` so templates can pass `page.frontmatter`, a `pub`
+      # Hash, or a bare slug interchangeably.
+      def resolve_frontmatter(subject)
+        case subject
+        when Hash then subject
+        when String, Symbol
+          slug = subject.to_s
+          publication_for(slug) || bundle_for(slug) || series_for(slug)
+        else
+          subject.respond_to?(:frontmatter) ? subject.frontmatter : nil
+        end
+      end
+
+    end
+  end
+end