pandorga 1.6.3 → 1.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 107838b82bee49181ddb10435ed0ab5726579fda06fe0bc0e5399ce0f17f86ad
-  data.tar.gz: f8e893a43d87ed1b846a522cef98b2314c56efdfd304804354458d6c5ae9e0be
+  metadata.gz: c10e8353c0760ae19918f1a54deacb0b6d408975f11b83a0a8162c359d08a9bc
+  data.tar.gz: b5e4968d6049c318c1cd9cdde355e2ca1099e55f1aa5b85889622a3f31943f1d
 SHA512:
-  metadata.gz: df29223d7d858b285e1b1e9cf991cd3362e192895fdbcbded93c3f2cc7991f7594779b45ee5a04d7c840ac7279cf26eb23bb704b25b55f17ab7b95d4a483743d
-  data.tar.gz: 1e1ac9acc5c296025106b85da0bc4535ca67a3bf72061932dbffc1273f027f66d69666dc17f265eb40d9298b37b99cdf23cef2476c510a9cd1e4862a5b965bd0
+  metadata.gz: 43ea5a53a28f44d966d7a87b8bc9f6734e4e1fb029319f278e4ca2a3d0ee4c53bb1338486ab3c777eebfe9a0efb08262b757c8b1e4f17d0c5b44db50fb51fad2
+  data.tar.gz: 308655d3e64b7821d54a77ee4b203a60d15353f7464e5de772f2a11efb901b2e977bead7112ebb212cc5542a14668eb27886cfe9949cda388a2626ad8c50ddb7

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.6.4] — 2026-10-10
+
+### Fixed
+
+- The Material Symbols stylesheet no longer blocks first paint. It loads
+  as print media and is applied on load. The icon box stays 1em, and its
+  size stays inherited, so the Google sheet cannot restyle it after paint.
+- The content runtime, including marked, comes after the page so the
+  hero is in the document before that script. A home band's kicker, title,
+  and note from `content/pages/headers.yml` are in the HTML.
+- The hero subtitle from `content/pages/headers.yml` is in the HTML.
+  Leaving that line empty until script runs moved the portrait.
+- On a phone the hero band is shorter, so the first section title stays in
+  the first viewport. That title was the late LCP element.
+
+### Added
+
+- Lighthouse mobile is a release rule. A stable release scores 90 or above.
+  A score from 75 to 89 is acceptable only to ship a bug fix, and an urgent
+  performance campaign must then bring the score back to 90 or above.
+  Below 75 is never acceptable. CI runs one mobile pass on the example home.
+
+No `pandorga:` config keys were added or renamed.
+
 ## [1.6.3] — 2026-10-10
 
 ### Fixed

data/README.md

@@ -75,6 +75,15 @@ bundle exec pandorga serve
 | [docs/deploy/cloudflare.md](docs/deploy/cloudflare.md) | Pages + object store |
 | [docs/spec.md](docs/spec.md) | Migration plan and acceptance criteria |
 | [docs/decisions.md](docs/decisions.md) | Frozen decisions |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Gates, and the Lighthouse mobile release rule |
+
+## Releases
+
+Lighthouse mobile on the home page is mandatory. A stable release scores
+90 or above. A score from 75 to 89 is acceptable only to ship a bug fix,
+and an urgent performance campaign must then bring it back to 90 or above.
+Below 75 is never acceptable. The checklist is in
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

data/_includes/content-runtime/60-fragments.html

@@ -329,8 +329,9 @@
         return;
       }
       if (inline) {
-        el.innerHTML = stripSingleParagraph(parseInlineMarkdown(text));
-      } else {
+        var next = stripSingleParagraph(parseInlineMarkdown(text));
+        if (el.innerHTML.trim() !== next.trim()) el.innerHTML = next;
+      } else if (el.textContent.trim() !== text) {
         el.textContent = text;
       }
       el.hidden = false;

data/_includes/home/band-listing.html

@@ -23,11 +23,18 @@
   data-home-language="{{ _lang }}"
 >
   <div class="home-band-inner">
+    {%- assign _section = site.data.page_headers[band.section_key] -%}
+    {%- assign _title = band.title -%}
+    {%- if _section.title != blank -%}{%- assign _title = _section.title -%}{%- endif -%}
     <div class="ledger-section-banner" data-content-home-section="{{ band.section_key }}">
       <div class="ledger-section-lead">
-        <span class="ledger-kicker" data-content-section-kicker></span>
-        <h2 class="section-title" data-content-section-title></h2>
-        <p class="home-section-note font-body" data-content-section-note></p>
+        {%- if _section.kicker != blank -%}
+        <span class="ledger-kicker" data-content-section-kicker>{{ _section.kicker }}</span>
+        {%- endif -%}
+        <h2 class="section-title" data-content-section-title>{{ _title }}</h2>
+        {%- if _section.note != blank -%}
+        <p class="home-section-note font-body" data-content-section-note>{{ _section.note }}</p>
+        {%- endif -%}
       </div>
       <div class="home-section-aside">
         <a class="ledger-cta" href="{{ _path }}">

data/_layouts/home.html

@@ -9,9 +9,9 @@ layout: shell
   plus content fragments. Decorative art is a slot
   (`pandorga.home.hero_art`, default page/hero-default.html). Listing and
   index bands come from site.data.pandorga_home_bands in registry order.
-  Band copy (kicker, title, note) arrives from content/pages/headers.yml
-  via hydrateHomeSections(). No Portuguese or owner-specific strings live
-  in this layout.
+  Band copy (kicker, title, note) and the hero subtitle come from
+  content/pages/headers.yml at build time. No Portuguese or owner-specific
+  strings live in this layout.
 {%- endcomment -%}
 
 {%- assign _hero_name = site.pandorga.identity | pandorga_hero_name: site.author, site.title -%}
@@ -28,8 +28,13 @@ layout: shell
     <div class="home-band-inner">
       <div class="home-hero">
         <div class="home-hero-copy">
+          {%- assign _home_header = site.data.page_headers.home -%}
+          {%- if _home_header.subtitle != blank -%}
+          <div id="home-subtitle-content" class="home-hero-tagline font-label" data-content-static>{{ _home_header.subtitle }}</div>
+          {%- else -%}
           <div id="home-subtitle-content" class="home-hero-tagline font-label"
             data-content-fragment="home/subtitle" data-content-quiet></div>
+          {%- endif -%}
           <h1 class="home-hero-title">
             <span class="home-hero-given">{{ _hero_name.given }}</span>{%- if _hero_name.family != "" %} <span class="home-hero-family">{{ _hero_name.family }}</span>{%- endif %}
           </h1>

data/_layouts/shell.html

@@ -116,8 +116,15 @@
   <link rel="stylesheet" href="/assets/css/ledger/{{ _sheet }}.css" />
   {%- endfor -%}
   {% include theme/font-loader.html %}
-  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap"
-    rel="stylesheet" />
+  {%- comment -%}
+    Icons are not first paint. A stylesheet link here blocks rendering for
+    a round trip to fonts.googleapis.com. Print media keeps that sheet off
+    the critical path, and onload applies it for screen.
+  {%- endcomment -%}
+  {%- assign _symbols_href = "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" -%}
+  <link rel="preload" as="style" href="{{ _symbols_href }}" />
+  <link rel="stylesheet" href="{{ _symbols_href }}" media="print" onload="this.media='all'" />
+  <noscript><link rel="stylesheet" href="{{ _symbols_href }}" /></noscript>
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/lipis/flag-icons@7.2.3/css/flag-icons.min.css" />
   <style>
     :root { --drop-cap-lines: {{ site.drop_cap_lines | default: 2 }}; }
@@ -233,8 +240,6 @@
     })();
   </script>
 
-  {% include page/content-runtime.html %}
-
   <div id="page-content" tabindex="-1">
   {{ content }}
   </div>
@@ -244,6 +249,8 @@
   <!-- Footer -->
   {% include page/site-footer.html nav_active=nav_active %}
 
+  {% include page/content-runtime.html %}
+
 </body>
 
 </html>

data/_plugins/content_headers.rb

@@ -25,6 +25,7 @@ module Jekyll
       site.data["content_fragments"] ||= {}
 
       load_page_content(site, content_path)
+      load_page_headers(site, content_path)
       load_structured_data(site, content_path)
     end
 
@@ -40,6 +41,17 @@ module Jekyll
       end
     end
 
+    # content/pages/headers.yml is also exported as pages/headers.json.
+    # The home bands read it here so a section title and note are in the
+    # HTML. A heading painted later by the runtime becomes the LCP element.
+    def load_page_headers(site, content_path)
+      path = File.join(content_path, "pages", "headers.yml")
+      return unless File.file?(path)
+
+      loaded = load_yaml(path)
+      site.data["page_headers"] = loaded.is_a?(Hash) ? loaded : {}
+    end
+
     def load_structured_data(site, content_path)
       data_path = File.join(content_path, "collections", "data")
       return unless Dir.exist?(data_path)

data/assets/css/base.css

@@ -1,12 +1,40 @@
 /* ── Material Symbols ── */
-.material-symbols-outlined {
+/* Doubled class so this beats the Google stylesheet, which arrives later
+   and sets font-size: 24px. That late size change moves the hero. */
+.material-symbols-outlined.material-symbols-outlined {
   font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
+  font-weight: normal;
+  font-style: normal;
+  font-size: inherit;
+  letter-spacing: normal;
   display: inline-flex;
   align-items: center;
   justify-content: center;
   vertical-align: middle;
   line-height: 1;
   text-transform: none;
+  white-space: nowrap;
+  /* One em square. Until the icon face arrives the ligature is a word,
+     and an unsized word widens the control. */
+  width: 1em;
+  height: 1em;
+  min-width: 1em;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+.material-symbols-outlined.text-sm { font-size: 0.875rem; }
+.material-symbols-outlined.text-lg { font-size: 1.125rem; }
+.material-symbols-outlined.text-xl { font-size: 1.25rem; }
+.material-symbols-outlined.text-5xl { font-size: 3rem; }
+
+@media (min-width: 768px) {
+  .material-symbols-outlined.text-6xl { font-size: 3.75rem; }
+}
+
+.ledger-cta-arrow.material-symbols-outlined,
+.ledger-cta-icon.material-symbols-outlined {
+  font-size: 1.35em;
 }
 
 /* Cubist triad — ~+25% over the 1.25rem theme-toggle box (rounded to 1.5rem). */
@@ -22,6 +50,8 @@
   font-size: var(--type-card);
   width: 1.25rem;
   height: 1.25rem;
+  min-width: 1.25rem;
+  max-width: 1.25rem;
   line-height: 1;
 }
 

data/assets/css/ledger/home.css

@@ -74,6 +74,19 @@
   overflow: hidden;
 }
 
+/* The first band title is the LCP text. On a phone the hero padding and the
+   gap under the copy were pushing that title just past the first viewport,
+   so the paint waited on a later frame. */
+@media (max-width: 767px) {
+  .home-band--hero {
+    padding-block: 1.75rem 1.25rem;
+  }
+
+  .home-hero {
+    gap: var(--space-md);
+  }
+}
+
 .home-band--hero .home-band-inner {
   position: relative;
   z-index: 1;

data/lib/pandorga/jekyll/plugins/content_headers.rb

@@ -25,6 +25,7 @@ module Jekyll
       site.data["content_fragments"] ||= {}
 
       load_page_content(site, content_path)
+      load_page_headers(site, content_path)
       load_structured_data(site, content_path)
     end
 
@@ -40,6 +41,17 @@ module Jekyll
       end
     end
 
+    # content/pages/headers.yml is also exported as pages/headers.json.
+    # The home bands read it here so a section title and note are in the
+    # HTML. A heading painted later by the runtime becomes the LCP element.
+    def load_page_headers(site, content_path)
+      path = File.join(content_path, "pages", "headers.yml")
+      return unless File.file?(path)
+
+      loaded = load_yaml(path)
+      site.data["page_headers"] = loaded.is_a?(Hash) ? loaded : {}
+    end
+
     def load_structured_data(site, content_path)
       data_path = File.join(content_path, "collections", "data")
       return unless Dir.exist?(data_path)

data/lib/pandorga/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pandorga
-  VERSION = "1.6.3"
+  VERSION = "1.6.4"
 end

data/scripts/lighthouse-home.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# One Lighthouse mobile run against the built example home.
+# Fails below 75. Warns below 90. PLT-AC-24.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SITE="${ROOT}/examples/minimal/_site"
+PORT="${LIGHTHOUSE_PORT:-4173}"
+OUT="${LIGHTHOUSE_REPORT:-/tmp/lighthouse-home.json}"
+FAIL_BELOW=75
+WARN_BELOW=90
+
+fail() {
+  echo "ERROR: $1" >&2
+  exit 1
+}
+
+step() { echo "==> $1"; }
+
+[[ -f "${SITE}/index.html" ]] || fail "missing ${SITE}/index.html (run scripts/validate.sh first)"
+
+if [[ -n "${CHROME_PATH:-}" && -x "${CHROME_PATH}" ]]; then
+  CHROME="${CHROME_PATH}"
+elif command -v google-chrome >/dev/null 2>&1; then
+  CHROME="$(command -v google-chrome)"
+elif command -v google-chrome-stable >/dev/null 2>&1; then
+  CHROME="$(command -v google-chrome-stable)"
+else
+  fail "Chrome is not installed"
+fi
+
+step "Serving ${SITE}"
+python3 -m http.server "${PORT}" --bind 127.0.0.1 --directory "${SITE}" >/tmp/lighthouse-home-server.log 2>&1 &
+SERVER_PID=$!
+cleanup() {
+  kill "${SERVER_PID}" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+ready=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+  if curl -sf "http://127.0.0.1:${PORT}/" >/dev/null; then
+    ready=1
+    break
+  fi
+  sleep 0.25
+done
+[[ "${ready}" == "1" ]] || fail "example server did not answer on port ${PORT}"
+
+step "Lighthouse mobile (one run)"
+rm -f "${OUT}"
+npx --yes lighthouse@13.5.0 "http://127.0.0.1:${PORT}/" \
+  --only-categories=performance \
+  --form-factor=mobile \
+  --output=json \
+  --output-path="${OUT}" \
+  --quiet \
+  --no-enable-error-reporting \
+  --chrome-path="${CHROME}" \
+  --chrome-flags="--headless=new --no-sandbox --disable-gpu"
+
+python3 - "${OUT}" "${FAIL_BELOW}" "${WARN_BELOW}" <<'PY'
+import json
+import sys
+
+path, fail_below, warn_below = sys.argv[1:]
+fail_below = int(fail_below)
+warn_below = int(warn_below)
+report = json.load(open(path, encoding="utf-8"))
+raw = report.get("categories", {}).get("performance", {}).get("score")
+if raw is None:
+    print("ERROR: Lighthouse returned no performance score", file=sys.stderr)
+    sys.exit(1)
+score = int(round(float(raw) * 100))
+print(f"Lighthouse mobile performance: {score}")
+if score < fail_below:
+    print(f"::error::Lighthouse mobile performance {score} is below {fail_below}")
+    sys.exit(1)
+if score < warn_below:
+    print(
+        f"::warning::Lighthouse mobile performance {score} is below {warn_below}. "
+        "A score from 75 to 89 is acceptable only to ship a bug fix. "
+        "An urgent performance campaign must bring it back to 90 or above."
+    )
+PY

data/scripts/test/test-lighthouse-policy.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Lighthouse mobile release rule and the non-blocking icon sheet.
+# PLT-AC-24, PLT-AC-25.
+
+require "pathname"
+
+ROOT = Pathname.new(__dir__).join("..", "..").expand_path
+
+def fail!(message)
+  warn "FAIL test-lighthouse-policy: #{message}"
+  exit 1
+end
+
+docs = {
+  "spec" => ROOT.join("docs/spec.md").read,
+  "contributing" => ROOT.join("CONTRIBUTING.md").read,
+  "readme" => ROOT.join("README.md").read
+}
+shell = ROOT.join("_layouts/shell.html").read
+base = ROOT.join("assets/css/base.css").read
+script = ROOT.join("scripts/lighthouse-home.sh").read
+workflow = ROOT.join(".github/workflows/validate.yml").read
+
+docs.each do |name, text|
+  fail!("#{name} does not require 90 or above") unless text.include?("90 or above")
+  fail!("#{name} does not limit 75 to 89 to a bug fix") unless text.include?("only to ship a bug fix")
+  fail!("#{name} does not require the performance campaign") unless text.include?("urgent performance campaign")
+  fail!("#{name} does not forbid a score below 75") unless text.include?("Below 75 is never acceptable")
+end
+
+spec = docs.fetch("spec")
+contributing = docs.fetch("contributing")
+
+fail!("spec dropped the slower-release reason") unless spec.include?("slower release is better than a broken one")
+fail!("contributing dropped the slower-release reason") unless contributing.include?("slower release is better than a broken one")
+
+fail!("lighthouse script is not the CI check") unless workflow.include?("./scripts/lighthouse-home.sh")
+fail!("lighthouse script lost the fail floor") unless script.include?("FAIL_BELOW=75")
+fail!("lighthouse script lost the warn floor") unless script.include?("WARN_BELOW=90")
+fail!("lighthouse script is not a single mobile run") unless script.include?("--form-factor=mobile")
+fail!("lighthouse script repeats runs") if script.include?("--repeat")
+
+screen = shell.sub(%r{<noscript>.*?</noscript>}m, "")
+fail!("Material Symbols sheet is missing") unless shell.include?("Material+Symbols+Outlined")
+fail!("Material Symbols sheet still blocks first paint") unless screen.include?('media="print" onload="this.media=\'all\'"')
+fail!("screen still has a blocking Material Symbols stylesheet") if screen.match?(/rel="stylesheet"[^>]*Material\+Symbols|Material\+Symbols[^>]*rel="stylesheet"/m)
+
+icon = base[/\.material-symbols-outlined\.material-symbols-outlined \{.*?\n\}/m]
+fail!("icon rule missing") unless icon
+fail!("icon box is not 1em") unless icon.include?("width: 1em;") && icon.include?("height: 1em;")
+fail!("icon size can still jump when the Google sheet arrives") unless icon.include?("font-size: inherit;")
+fail!("icon box does not clip the fallback word") unless icon.include?("overflow: hidden;")
+fail!("content runtime still precedes the page") unless shell.index("{{ content }}") && shell.index("page/content-runtime.html") > shell.index("{{ content }}")
+band = File.read(File.expand_path("../../_includes/home/band-listing.html", __dir__))
+fail!("band title is still painted by script") unless band.include?('data-content-section-title>{{ _title }}')
+fail!("band note is still painted by script") unless band.include?("page_headers")
+headers = File.read(File.expand_path("../../_plugins/content_headers.rb", __dir__))
+fail!("page headers are not loaded at build time") unless headers.include?('site.data["page_headers"]')
+home = File.read(File.expand_path("../../_layouts/home.html", __dir__))
+fail!("hero subtitle is still painted by script") unless home.include?("page_headers.home") && home.include?("data-content-static")
+
+puts "PASS test-lighthouse-policy"

data/scripts/validate.sh

@@ -59,6 +59,7 @@ TESTS=(
   scripts/test/test-shell-a11y.rb
   scripts/test/test-hydrate-reserve.rb
   scripts/test/test-hero-summary.rb
+  scripts/test/test-lighthouse-policy.rb
   scripts/test/test-css-delivery.rb
   scripts/test/test-discovery.rb
 )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pandorga
 version: !ruby/object:Gem::Version
-  version: 1.6.3
+  version: 1.6.4
 platform: ruby
 authors:
 - The Pandorga contributors
@@ -322,6 +322,7 @@ files:
 - scripts/lib/r2_json_sync.rb
 - scripts/lib/withdrawn_public_objects.rb
 - scripts/lib/writing_index_contract.rb
+- scripts/lighthouse-home.sh
 - scripts/pdf/md-to-pdf.mjs
 - scripts/pdf/md-to-pdf.sh
 - scripts/tailwind/build.sh
@@ -412,6 +413,7 @@ files:
 - scripts/test/test-install-functions.rb
 - scripts/test/test-language-export.rb
 - scripts/test/test-ledger-blocks.rb
+- scripts/test/test-lighthouse-policy.rb
 - scripts/test/test-listing-filter-contract.rb
 - scripts/test/test-math-row-breaks.mjs
 - scripts/test/test-math-row-breaks.rb