abqari 1.1.2 → 1.3.0

data/lib/abqari/cli/headers.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+
+module Abqari
+  module CLI
+    # `abqari headers` — print the built `_site/_headers` as rules for
+    # hosts that don't read that file.
+    #
+    # Render static sites ignore `_headers`: the CSP, the security
+    # headers and the year-long `immutable` cache on `/assets/*` all
+    # have to be entered in the dashboard or `render.yaml`. Without the
+    # cache rule Render serves assets with `max-age=0`, so fonts are
+    # revalidated on every page and text flashes in the fallback font.
+    #
+    # It reads the BUILT file rather than computing headers itself, so
+    # the CSP hashes are the ones the site's own bundled engine and
+    # config produced. The global `abqari` on PATH may be a different
+    # version, and one hash (speculation rules) depends on config.
+    #
+    #   bin/build && bundle exec abqari headers
+    #   bundle exec abqari headers path/to/_site
+    class Headers
+      DEFAULT_PATH = File.join('_site', '_headers')
+
+      def self.run(argv)
+        new.run(argv)
+      end
+
+      def run(argv)
+        rest = build_parser.parse(argv)
+        path = resolve(rest.first || DEFAULT_PATH)
+
+        unless File.file?(path)
+          warn "No headers file at #{path}. Run `bin/build` first (it writes _site/_headers)."
+          return false
+        end
+
+        rules = parse(File.read(path, encoding: 'UTF-8'))
+        if rules.empty?
+          warn "#{path} has no header rules."
+          return false
+        end
+
+        puts render_yaml(rules)
+        true
+      end
+
+      def parse(text)
+        HeadersFile.parse(text)
+      end
+
+      private
+
+      def resolve(path)
+        File.directory?(path) ? File.join(path, '_headers') : path
+      end
+
+      # JSON strings are valid YAML double-quoted scalars, so the CSP's
+      # quotes, colons and semicolons survive a paste untouched.
+      def render_yaml(rules)
+        lines = rules.flat_map do |rule|
+          ["  - path: #{rule['path'].to_json}",
+           "    name: #{rule['name']}",
+           "    value: #{rule['value'].to_json}"]
+        end
+        <<~YAML
+          # Render doesn't read _site/_headers. Paste this block under your static
+          # site in render.yaml, or add each rule (Path, Name, Value) in the
+          # dashboard under Settings → Headers.
+          #
+          # The Content-Security-Policy pins SHA-256 hashes of Abqari's inline
+          # scripts, and one depends on config. After upgrading abqari or changing
+          # config/site.yml, rebuild, re-run this, and re-copy any rule that changed.
+          headers:
+          #{lines.join("\n")}
+        YAML
+      end
+
+      def build_parser
+        OptionParser.new do |opts|
+          opts.banner = <<~BANNER
+            Usage: abqari headers [path]
+
+            Prints the built _site/_headers (or the _headers file / output
+            directory at [path]) as Render header rules, ready for render.yaml
+            or the dashboard's Settings → Headers. Run bin/build first.
+          BANNER
+          opts.on('-h', '--help', 'Show this message') { puts opts; exit }
+        end
+      end
+    end
+  end
+end

data/lib/abqari/cli.rb

@@ -5,6 +5,7 @@
 require_relative '../abqari'
 require_relative 'cli/new'
 require_relative 'cli/theme'
+require_relative 'cli/headers'
 
 module Abqari
   # Tiny subcommand dispatcher for the `abqari` global executable.
@@ -29,6 +30,7 @@ module Abqari
     COMMANDS = {
       'new'     => 'Abqari::CLI::New',
       'theme'   => 'Abqari::CLI::Theme',
+      'headers' => 'Abqari::CLI::Headers',
       'version' => :builtin_version,
       '-v'      => :builtin_version,
       '--version' => :builtin_version,
@@ -43,6 +45,7 @@ module Abqari
       Commands:
         new <projectname>    Scaffold a new Abqari site in ./<projectname>/
         theme eject <name>   Copy an engine theme into this site for editing
+        headers [path]       Print the built _site/_headers as Render header rules
         version              Print the engine version
         help                 Show this message
 

data/lib/abqari/headers_file.rb

@@ -4,6 +4,7 @@ require 'uri'
 
 require_relative 'theme_bootstrap'
 require_relative 'plausible_script'
+require_relative 'speculation_rules'
 
 module Abqari
   class HeadersFile
@@ -26,10 +27,28 @@ module Abqari
     BASE_HEADERS = {
       'X-Content-Type-Options'    => 'nosniff',
       'Referrer-Policy'           => 'strict-origin-when-cross-origin',
-      'Permissions-Policy'        => 'camera=(), microphone=(), geolocation=(), interest-cohort=()',
+      'Permissions-Policy'        => 'camera=(), microphone=(), geolocation=()',
       'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains'
     }.freeze
 
+    # A `_headers` file as `{ 'path', 'name', 'value' }` rules: an
+    # unindented path line, then indented `Name: value` lines. The shape
+    # `build` writes, for both the generated policy and a `headers:`
+    # override. Read back by `abqari headers` and the CSP audit.
+    def self.parse(text)
+      path = nil
+      text.each_line.with_object([]) do |line, rules|
+        next if line.strip.empty? || line.lstrip.start_with?('#')
+
+        if line.match?(/\A\S/)
+          path = line.strip
+        elsif path
+          name, value = line.strip.split(/:\s*/, 2)
+          rules << { 'path' => path, 'name' => name, 'value' => value.to_s } unless name.to_s.empty?
+        end
+      end
+    end
+
     def initialize(site)
       @site = site
     end
@@ -208,21 +227,19 @@ module Abqari
     end
 
     # The `<script type="speculationrules">` block the head emits is an
-    # inline script as far as CSP is concerned, so `script-src` must
-    # carry `'inline-speculation-rules'` (Chrome's keyword for exactly
-    # this) or the block is rejected — no prerender, plus a console
-    # error on every page. Its content is config-dependent (posts slug,
-    # eagerness), so a static hash can't cover it. On by default; the
-    # head gates on `speculation_rules.enabled` not being false.
+    # inline script as far as CSP is concerned. `'inline-speculation-rules'`
+    # is Chrome's keyword for exactly this, but Chrome stops honouring
+    # it once script-src lists a hash — and the base policy always does
+    # — so the block is pinned by its own SHA-256 as well. The body is
+    # config-dependent, so the hash is computed per build from the same
+    # SpeculationRules.script the head emits.
     def apply_speculation_rules(policy)
+      policy['script-src'] << "'#{SpeculationRules.sha256(@site)}'"
       policy['script-src'] << "'inline-speculation-rules'"
     end
 
     def speculation_rules_enabled?
-      cfg = @site.config['speculation_rules']
-      return true unless cfg.is_a?(Hash)
-
-      cfg['enabled'] != false
+      SpeculationRules.enabled?(@site)
     end
 
     # Plausible: external tracker + inline init script. Both need explicit

data/lib/abqari/hooks.rb

@@ -102,10 +102,15 @@ module Abqari
   # `Abqari::Hooks.register` to wire themselves into the lifecycle.
   #
   # Why `load` instead of `require`: `require` caches by path, so a
-  # plugin edit isn't reloaded on subsequent Site.new calls. `load`
-  # re-executes every time — important for the dev-server case where
-  # editing a plugin file should re-register its hooks on the next
-  # incremental rebuild.
+  # second Site.new in the same process (the test suite, an embedder)
+  # would silently skip a plugin it had already seen. `load` re-executes
+  # every time.
+  #
+  # The dev server constructs its Site once, so a plugin edited while
+  # `bin/serve` runs is never re-loaded — and neither is anything the
+  # plugin `require`d. `snapshot` and `changed_since` exist so the
+  # server can say so instead of failing with an unexplained
+  # NoMethodError on the next render.
   #
   # The hook table is NOT cleared between reloads. A plugin that
   # registers in its top-level body will accumulate duplicate
@@ -132,5 +137,55 @@ module Abqari
         raise
       end
     end
+
+    # The site's Ruby as this process has it loaded: every plugin file,
+    # plus every file under the site's `lib/` in `$LOADED_FEATURES` —
+    # in practice, what the plugins required. Maps path → mtime.
+    #
+    # Paths are realpaths because `require_relative` records realpaths
+    # in `$LOADED_FEATURES`; on macOS the temp dir alone (/var →
+    # /private/var) is enough to make a naive prefix match miss.
+    def snapshot(site_root)
+      root = realpath(site_root)
+      return {} unless root
+
+      (plugin_paths(root) | loaded_lib_paths(site_root, root)).each_with_object({}) do |path, mtimes|
+        mtime = mtime_of(path)
+        mtimes[path] = mtime if mtime
+      end
+    end
+
+    # Site-relative paths of Ruby that differs on disk from `snapshot`:
+    # edited, deleted, or a plugin file added after it was taken.
+    def changed_since(snapshot, site_root)
+      root = realpath(site_root)
+      return [] unless root
+
+      edited = snapshot.reject { |path, mtime| mtime_of(path) == mtime }.keys
+      added  = plugin_paths(root) - snapshot.keys
+      (edited + added).map { |path| path.delete_prefix("#{root}/") }.sort
+    end
+
+    def plugin_paths(root)
+      Dir.glob(File.join(root, PLUGIN_GLOB))
+    end
+
+    def loaded_lib_paths(site_root, root)
+      prefixes = [File.expand_path(site_root), root].uniq.map { |r| File.join(r, 'lib', '') }
+      $LOADED_FEATURES.select { |f| prefixes.any? { |p| f.start_with?(p) } }
+                      .filter_map { |f| realpath(f) }
+    end
+
+    def realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    end
+
+    def mtime_of(path)
+      File.mtime(path)
+    rescue SystemCallError
+      nil
+    end
   end
 end

data/lib/abqari/renderer.rb

@@ -18,21 +18,84 @@ module Abqari
     # Below this many pages, parallelism hurts more than it helps.
     PARALLEL_THRESHOLD = 16
 
+    # Render threads can only overlap file I/O: ERB, markdown and the
+    # post-processors are Ruby and hold the GVL. Past a handful they
+    # add contention, not throughput — a 270-page site built in ~1.07s
+    # on 1, 2, 4 or 8 threads, and 1.18s on 14.
+    MAX_RENDER_THREADS = 4
+
+    # Where a container's CPU quota is exposed. `Etc.nprocessors` reports
+    # the host's CPUs (or the cpuset), not the quota, so a build
+    # container on a large host would otherwise start dozens of threads
+    # to share a fraction of one CPU.
+    CGROUP_ROOT = '/sys/fs/cgroup'
+
     # Default page-size for `paginate: true`. Overridable per-site via
     # `pagination.per_page` config.
     PAGINATION_DEFAULT = 10
 
     # Slow-page detection. When a single page's `write` (render +
-    # post-process + file write) takes longer than this, the renderer
-    # logs a warning with the URL, elapsed time, and a short list of
+    # post-process + file write) uses more CPU than this, the renderer
+    # logs a warning with the URL, the time, and a short list of
     # heuristic causes (output size, image count, code-block count,
-    # TOC presence). End-of-build summary surfaces the slowest few.
+    # TOC presence, a measured plugin filter). End-of-build summary
+    # surfaces the slowest few.
     #
     # Default 500ms — high enough to ignore the normal per-page
     # baseline (~5–50ms), low enough to catch real outliers. Override
     # with `ABQARI_SLOW_PAGE_MS=N` (set to 0 to disable detection).
     SLOW_PAGE_THRESHOLD_MS = (ENV['ABQARI_SLOW_PAGE_MS'] || '500').to_i
 
+    # Pages are timed by the CPU their own thread used, not wall-clock.
+    # Wall-clock includes every other render thread's turn on the GVL
+    # and any CPU throttling, so on a container with a small quota a
+    # 5ms page read as 500ms+ and dozens of pages were reported slow.
+    # The trade: time spent blocked on I/O no longer counts, which
+    # suits a warning whose every listed cause is CPU work.
+    PAGE_CLOCK = defined?(Process::CLOCK_THREAD_CPUTIME_ID) ? Process::CLOCK_THREAD_CPUTIME_ID : Process::CLOCK_MONOTONIC
+
+    # A plugin filter is named as a cause only when it accounts for at
+    # least this share of the slow page's time. It used to be named on
+    # every slow page whenever any `:post_process` hook was registered.
+    PLUGIN_FILTER_SHARE = 0.25
+    PLUGIN_FILTER_MS = :abqari_plugin_filter_ms
+
+    class << self
+      def render_threads
+        [available_cpus, MAX_RENDER_THREADS].min
+      end
+
+      def available_cpus(cgroup_root: CGROUP_ROOT)
+        [Etc.nprocessors, cgroup_cpu_limit(cgroup_root)].compact.min
+      end
+
+      # CPUs granted by the cgroup quota, rounded up, or nil when there
+      # is no quota (or no cgroup to read). v2 first, then v1.
+      def cgroup_cpu_limit(root)
+        v2 = read_cgroup(File.join(root, 'cpu.max'))
+        quota, period = v2 ? v2.split : v1_quota(root)
+        return nil if quota.nil? || quota == 'max' || quota.to_i <= 0 || period.to_i <= 0
+
+        [(quota.to_f / period.to_i).ceil, 1].max
+      end
+
+      private
+
+      def v1_quota(root)
+        %w[cpu cpu,cpuacct].each do |dir|
+          quota = read_cgroup(File.join(root, dir, 'cpu.cfs_quota_us'))
+          return [quota, read_cgroup(File.join(root, dir, 'cpu.cfs_period_us'))] if quota
+        end
+        nil
+      end
+
+      def read_cgroup(path)
+        File.read(path).strip
+      rescue SystemCallError
+        nil
+      end
+    end
+
     # Files whose mtime invalidates every cached page render.
     # `app/views/layouts/` is NOT here — layout files are handled
     # per-layout via `layout_deps_mtime(name)` so editing one layout
@@ -296,7 +359,7 @@ module Abqari
       queue = Thread::Queue.new
       pages.each { |page| queue << page }
 
-      thread_count = [Etc.nprocessors, pages.size].min
+      thread_count = [self.class.render_threads, pages.size].min
       threads = Array.new(thread_count) do
         Thread.new do
           loop do
@@ -335,7 +398,7 @@ module Abqari
       # so plugin output sees the same shape browsers will. Runs BEFORE
       # livereload injection + minification so plugin transformations
       # are minified along with the rest of the page.
-      html = Hooks.run_filter(:post_process, html, @site, page)
+      html = run_plugin_filters(html, page)
       html = inject_livereload(html) if @site.env == :development
       html = Minifier.minify(html) if minify_html?
       html
@@ -352,6 +415,17 @@ module Abqari
 
     private
 
+    # Plugin filters, timed on the page clock so the slow-page report
+    # can say whether they mattered. Read back by `render_one`, which
+    # zeroes the counter before each page.
+    def run_plugin_filters(html, page)
+      t0 = Process.clock_gettime(PAGE_CLOCK, :millisecond)
+      Hooks.run_filter(:post_process, html, @site, page)
+    ensure
+      spent = Process.clock_gettime(PAGE_CLOCK, :millisecond) - t0
+      Thread.current[PLUGIN_FILTER_MS] = (Thread.current[PLUGIN_FILTER_MS] || 0) + spent
+    end
+
     # Fail the build when two pages resolve to the same output file.
     # Without this, whichever page the (parallel) render loop writes
     # last silently wins — nondeterministically build-to-build — and
@@ -400,13 +474,14 @@ module Abqari
     # `SLOW_PAGE_THRESHOLD_MS`. Slow pages are collected for the
     # end-of-build summary.
     def render_one(page, errors, mutex, slow_pages = nil, slow_mutex = nil)
-      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      Thread.current[PLUGIN_FILTER_MS] = 0
+      t0 = Process.clock_gettime(PAGE_CLOCK, :millisecond)
       page.write
-      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+      elapsed_ms = Process.clock_gettime(PAGE_CLOCK, :millisecond) - t0
 
       return unless slow_page?(elapsed_ms) && slow_pages && slow_mutex
 
-      causes = infer_slow_causes(page)
+      causes = infer_slow_causes(page, elapsed_ms: elapsed_ms, plugin_ms: Thread.current[PLUGIN_FILTER_MS])
       Log.warn(slow_page_note(page, elapsed_ms, causes))
       slow_mutex.synchronize { slow_pages << { page: page, ms: elapsed_ms, causes: causes } }
     rescue StandardError, PathSafe::Error => e
@@ -466,7 +541,7 @@ module Abqari
         advice: 'Set `toc: false` in the page\'s frontmatter to skip the TOC for one page, or raise `posts.show.toc.min_headings` to skip shorter pages globally.'
       },
       plugin_filter: {
-        label:  ->(_)    { 'plugin filter' },
+        label:  ->(meta) { "plugin filter #{meta[:ms]}ms" },
         impact: 'A plugin registered against the `:post_process` hook transforms the rendered HTML — the engine can\'t see inside the plugin code.',
         advice: 'Profile the offending plugin in `plugins/*.rb`, or temporarily disable it (rename to `*.rb.off`) to confirm it\'s the bottleneck.'
       }
@@ -478,7 +553,7 @@ module Abqari
     def slow_page_note(page, elapsed_ms, causes)
       url       = page.respond_to?(:url) && page.url ? page.url : page.source_path.to_s
       cause_str = causes.empty? ? '' : " — #{causes.map { |c| c[:label] }.join(' · ')}"
-      "Slow page: #{url} took #{format_ms(elapsed_ms)}#{cause_str}"
+      "Slow page: #{url} took #{format_ms(elapsed_ms)} of CPU#{cause_str}"
     end
 
     # Sample cheap heuristics that often correlate with slow renders.
@@ -490,7 +565,15 @@ module Abqari
     # cause-catalogue key, `label` is the populated short string for
     # the inline warning. The summary uses `type` to look up the
     # full impact + advice from `SLOW_PAGE_CAUSES`.
-    def infer_slow_causes(page)
+    def infer_slow_causes(page, elapsed_ms: 0, plugin_ms: 0)
+      causes = content_causes(page)
+      if plugin_ms.to_i.positive? && plugin_ms >= elapsed_ms * PLUGIN_FILTER_SHARE
+        causes << build_cause(:plugin_filter, ms: plugin_ms)
+      end
+      causes
+    end
+
+    def content_causes(page)
       causes = []
       return causes unless page.respond_to?(:output_path)
       path = page.output_path
@@ -505,7 +588,6 @@ module Abqari
       code_count = html.scan(/<pre\b/i).size
       causes << build_cause(:many_code_blocks, count: code_count) if code_count >= 10
       causes << build_cause(:toc) if html.include?('class="toc"') || html.include?("class='toc'")
-      causes << build_cause(:plugin_filter) if Hooks.registered_events.include?(:post_process)
       causes
     rescue StandardError
       # Cause inference is best-effort — never let a probe failure
@@ -532,7 +614,7 @@ module Abqari
       return if slow_pages.empty?
 
       slow_pages.sort_by! { |sp| -sp[:ms] }
-      Log.info("Slow pages (>#{SLOW_PAGE_THRESHOLD_MS}ms): #{slow_pages.size}")
+      Log.info("Slow pages (>#{SLOW_PAGE_THRESHOLD_MS}ms CPU): #{slow_pages.size}")
       slow_pages.first(5).each do |sp|
         url       = sp[:page].respond_to?(:url) && sp[:page].url ? sp[:page].url : sp[:page].source_path
         cause_str = sp[:causes].empty? ? '' : "  (#{sp[:causes].map { |c| c[:label] }.join(' · ')})"

data/lib/abqari/server.rb

@@ -22,7 +22,13 @@ module Abqari
     PORT_RANGE = (1..65_535).freeze
     POLL_INTERVAL = 0.5
     DEBOUNCE = 0.1
-    WATCH_GLOBS = ['content/**/*', 'app/**/*', 'themes/**/*', 'config/**/*', 'lib/**/*', 'data/**/*'].freeze
+    # `plugins/` is here so a plugin edit is noticed at all. Plugins
+    # load once at Site.new, so the change can only be reported (see
+    # #warn_stale_ruby), not picked up.
+    WATCH_GLOBS = ['content/**/*', 'app/**/*', 'themes/**/*', 'config/**/*', 'lib/**/*', 'data/**/*',
+                   'plugins/**/*'].freeze
+    # More than this and the stale-Ruby warning stops being one line.
+    STALE_RUBY_LISTED = 3
     CSS_PATTERN = /\.css\z/.freeze
 
     # How long to hold an SSE connection open before sending a no-op
@@ -377,6 +383,7 @@ module Abqari
       @mutex.synchronize do
         count = changed_paths.size
         Log.info "Change detected (#{count} file#{'s' unless count == 1}). Rebuilding…"
+        warn_stale_ruby if changed_paths.any? { |p| p.end_with?('.rb') }
         @site.build(incremental: true)
         @scope = changed_paths.all? { |p| p =~ CSS_PATTERN } ? 'css' : 'all'
         @version = Time.now.to_f
@@ -392,6 +399,26 @@ module Abqari
     rescue StandardError => e
       Log.error "Build failed: #{e.class}: #{e.message}"
       e.backtrace&.first(5)&.each { |line| Log.debug "  #{line}" }
+      warn_stale_ruby(after_failure: true)
+    end
+
+    # The change warning alone isn't enough: the usual sequence is
+    # edit the plugin, then edit the layout that calls the new helper,
+    # and by the time every page fails with `undefined method ... for
+    # an instance of Abqari::RenderContext` the warning has scrolled
+    # away. So a failed build repeats it, as an error, last.
+    def warn_stale_ruby(after_failure: false)
+      stale = @site.stale_ruby_sources
+      return if stale.empty?
+
+      files = stale.first(STALE_RUBY_LISTED).join(', ')
+      files += " and #{stale.size - STALE_RUBY_LISTED} more" if stale.size > STALE_RUBY_LISTED
+      if after_failure
+        Log.error "Restart bin/serve: #{files} changed after it started, and it is still running " \
+                  'the old Ruby, so helpers added since are undefined.'
+      else
+        Log.warn "#{files} changed, but bin/serve loads Ruby once at startup — restart it to pick that up."
+      end
     end
 
     # ----------------------------------------------------------------

data/lib/abqari/site.rb

@@ -102,6 +102,15 @@ module Abqari
       # the registrations land in the global hook table and fire on
       # subsequent `Hooks.run` / `run_filter` calls during build.
       PluginLoader.load_from(site_root)
+      # Taken after loading so it covers what the plugins required.
+      @ruby_snapshot = PluginLoader.snapshot(site_root)
+    end
+
+    # Site Ruby (plugins/, and lib/ files they required) that changed on
+    # disk after this Site loaded it. Ruby loads once per process, so a
+    # long-lived Site — the dev server's — keeps running the old code.
+    def stale_ruby_sources
+      PluginLoader.changed_since(@ruby_snapshot, site_root)
     end
 
     # ------------------------------------------------------------------

data/lib/abqari/speculation_rules.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'base64'
+
+module Abqari
+  # The `<script type="speculationrules">` block in the head, built here
+  # rather than in `_head.html.erb` so HeadersFile hashes the exact bytes
+  # the page carries and the two can't drift.
+  #
+  # The hash is what lets the block run. Chrome stops honouring the
+  # `'inline-speculation-rules'` keyword once script-src lists any hash,
+  # and ours always does (ThemeBootstrap, SpeculationRulesGuard), so on
+  # its own the keyword left every page logging a CSP violation with
+  # nothing prerendered. The keyword stays in the policy for browsers
+  # that do honour it.
+  #
+  # Unlike the other inline scripts, the body depends on config (the
+  # URL patterns and eagerness), so its hash is per-site, not a constant.
+  module SpeculationRules
+    EAGERNESS         = %w[conservative moderate eager].freeze
+    DEFAULT_EAGERNESS = 'moderate'
+
+    module_function
+
+    def enabled?(site)
+      cfg = site.config['speculation_rules']
+      !cfg.is_a?(Hash) || cfg['enabled'] != false
+    end
+
+    # The surrounding whitespace is what the inline template produced
+    # before the body moved here. Keeping it byte-identical means a hash
+    # already copied into a host that ignores `_headers` (Render) stays
+    # valid across the upgrade for any site that doesn't change config.
+    def script(site)
+      "\n  { \"prerender\": [{ \"source\": \"document\",\n    \"where\": #{where(href_matches(site))},\n    " \
+        "\"eagerness\": #{json(eagerness(site))} }] }\n  "
+    end
+
+    def sha256(site)
+      "sha256-#{Base64.strict_encode64(Digest::SHA256.digest(script(site)))}"
+    end
+
+    # `speculation_rules.href_matches:` — one URL pattern or a list.
+    # Defaults to the posts collection, which is all the engine knows is
+    # article-shaped; a site whose main content is a custom collection
+    # (`/news/*`) names it here.
+    def href_matches(site)
+      patterns = Array(settings(site)['href_matches']).map { |p| p.to_s.strip }.reject(&:empty?)
+      patterns.empty? ? ["/#{posts_path(site)}/*"] : patterns
+    end
+
+    def eagerness(site)
+      value = settings(site)['eagerness'].to_s
+      EAGERNESS.include?(value) ? value : DEFAULT_EAGERNESS
+    end
+
+    def where(patterns)
+      clauses = patterns.map { |p| "{ \"href_matches\": #{json(p)} }" }
+      clauses.one? ? clauses.first : "{ \"or\": [#{clauses.join(', ')}] }"
+    end
+
+    # Same slug the posts collection resolves to (Site#collection_config
+    # takes it straight from config; the defaults carry none).
+    def posts_path(site)
+      collections = site.config['collections']
+      posts = collections.is_a?(Hash) ? collections['posts'] : nil
+      slug = posts.is_a?(Hash) ? posts['slug'].to_s : ''
+      slug.empty? ? 'posts' : slug
+    end
+
+    def settings(site)
+      cfg = site.config['speculation_rules']
+      cfg.is_a?(Hash) ? cfg : {}
+    end
+
+    # Patterns come from site config, but this lands raw inside a
+    # <script>, so a stray `</script>` must not be able to close it.
+    def json(value)
+      Helpers.script_safe_json(value)
+    end
+  end
+end

data/lib/abqari/templates/site_skeleton/.github/workflows/deploy-cloudflare.yml

@@ -19,6 +19,7 @@
 # What this does:
 #   - Installs Ruby + libvips, restores bundle cache
 #   - Installs Pagefind (used only if `search: true` in site.yml)
+#   - Fetches the self-hosted fonts (vendor/fonts/ is git-ignored)
 #   - Builds the site in production mode
 #   - Runs the audit, uploads report as artifact (audit failures don't block deploy)
 #   - Deploys _site/ to Cloudflare Pages via Wrangler
@@ -67,6 +68,14 @@ jobs:
         # Skips silently if pagefind is unused; bin/build only runs it when
         # `search: true` is set in config/site.yml.
 
+      - name: Fetch fonts
+        # vendor/fonts/ is git-ignored, so a fresh checkout has no font
+        # files and the build would ship the site in fallback fonts.
+        # No-op when config/site.yml has no `fonts:`.
+        env:
+          ABQARI_ENV: production
+        run: bundle exec bin/fetch-fonts
+
       - name: Build site
         env:
           ABQARI_ENV: production

data/lib/abqari/templates/site_skeleton/.github/workflows/deploy-github-pages.yml

@@ -69,6 +69,14 @@ jobs:
           curl -LSf https://pagefind.app/install.sh | bash
           echo "$HOME/.local/bin" >> $GITHUB_PATH
 
+      - name: Fetch fonts
+        # vendor/fonts/ is git-ignored, so a fresh checkout has no font
+        # files and the build would ship the site in fallback fonts.
+        # No-op when config/site.yml has no `fonts:`.
+        env:
+          ABQARI_ENV: production
+        run: bundle exec bin/fetch-fonts
+
       - name: Build site
         env:
           ABQARI_ENV: production