@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/site-config.mjs

@@ -42,6 +42,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { stringify as stringifyToml } from "smol-toml";
 
 import { checkHomepage, fail } from "../config.mjs";
@@ -61,10 +62,15 @@ export const HUGO_CONTENT = `${HUGO_SOURCE}/content`;
  */
 export const DEPLOY_ROOT = "build/site";
 
-/** The npm package the shared theme arrives as. */
-export const THEME_PACKAGE = "@heroiclands/hugo-theme";
+/**
+ * This package's own root, which is the directory Hugo reads themes from.
+ *
+ * The theme ships inside this package, so the directory holding it is found
+ * from this module's own location rather than searched for.
+ */
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-/** The theme's name under `themesDir`, which is the package's unscoped name. */
+/** The theme's directory name under `themesDir`. */
 export const THEME = "hugo-theme";
 
 /** The locale every site renders in. */
@@ -308,33 +314,22 @@ export async function fetchNavigation(
 
 /**
  * The `themesDir` for a repository, as the path from `build/hugo/` to the
- * directory holding the installed theme.
+ * directory holding the theme.
+ *
+ * The theme ships inside this package at `hugo-theme/`, so the directory Hugo
+ * reads themes from is {@link PACKAGE_ROOT}. `theme` stays {@link THEME}, so
+ * Hugo opens `<themesDir>/hugo-theme/layouts`.
  *
- * Resolved the way Node resolves a package — `node_modules/` in the
- * repository root, then in each parent — and written as a path rather than
- * assumed, so a worktree that resolves its parent's install says so in the
- * generated file.
+ * Written as a path rather than assumed: `build/hugo/` and the installed
+ * package sit at whatever distance the install put them, and a worktree
+ * resolving its parent's install says so in the generated file.
  *
  * @param {string} rootDir - The repository root.
  * @returns {string} The relative path, POSIX-separated.
- * @throws {Error} When the theme is installed nowhere above the root.
  */
 export function resolveThemesDir(rootDir) {
-    let dir = path.resolve(rootDir);
-    for (;;) {
-        const scope = path.join(dir, "node_modules", path.dirname(THEME_PACKAGE));
-        if (fs.existsSync(path.join(scope, path.basename(THEME_PACKAGE), "theme.toml"))) {
-            const rel = path.relative(path.resolve(rootDir, HUGO_SOURCE), scope);
-            return rel.split(path.sep).join("/");
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-    }
-    throw new Error(
-        `${THEME_PACKAGE} is not installed anywhere above ${rootDir} — add it to ` +
-            "`devDependencies` and run `npm ci`",
-    );
+    const from = path.resolve(rootDir, HUGO_SOURCE);
+    return path.relative(from, PACKAGE_ROOT).split(path.sep).join("/");
 }
 
 /**

package/engine/site-index.mjs

@@ -66,10 +66,12 @@ import {
     renderAddress,
     isAddressTuple,
     ownDocumentSystem,
+    expandAddress,
 } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
 import { contentPackage } from "./content-package.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
+import { presentAmongRecords } from "./being-age.mjs";
 // The declared tag vocabulary, which is where `draft` is stated.
 import { isDraftNote } from "./note-vocabulary.mjs";
 
@@ -277,7 +279,12 @@ export function buildSiteIndex(
 
     return {
         contentPackage: ownPackage,
-        dateContext: reckoningContext({ notes: records }),
+        // Carried on the same context `resolvedDateFields` reads: a recurring
+        // event's `next` is computed against this present.
+        dateContext: {
+            ...reckoningContext({ notes: records }),
+            present: presentAmongRecords(records),
+        },
         referenceTargets: buildReferenceTargets(records, new Map([...foreignReferences, ...index])),
         index,
         ambiguous,
@@ -288,6 +295,70 @@ export function buildSiteIndex(
     };
 }
 
+/**
+ * The address keys one page's figures are reachable by — the same two forms
+ * {@link buildSiteIndex} assigns the page itself, so a `ref` crossing into it
+ * resolves by exactly the address a wikilink would use.
+ *
+ * @param {string} pkg - The page's own content package.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {Set<string>} The short `type/shortcode` key and the canonical
+ *   `package-system-type-shortcode` one.
+ */
+export function figureIndexKeys(pkg, type, shortcode) {
+    const system = ownDocumentSystem(type);
+    const keys = new Set([
+        `${type}/${shortcode}`.toLowerCase(),
+        canonicalKey(pkg, system, type, shortcode),
+    ]);
+    if (system !== NOTE_SYSTEM) keys.add(canonicalKey(pkg, NOTE_SYSTEM, type, shortcode));
+    return keys;
+}
+
+/**
+ * Resolve a `ref` call's cross-note address to the target's own figures and
+ * its own address — the `figures.note` a `ref` helper's render context reads,
+ * built once and threaded into every page.
+ *
+ * Reads the written address exactly as a wikilink does
+ * ({@link readQualifier}, {@link expandAddress}), so a `ref` crossing into
+ * another note and a `[[…]]` link to the same note agree on what resolves and
+ * what does not: a target naming no known type or no fetched package's index
+ * is unresolved for both, and one address names one note for both.
+ *
+ * @param {string} target - The address as written, anchor already removed —
+ *   {@link module:engine/wikilink-syntax.ParsedWikilink.target}.
+ * @param {object} options
+ * @param {Set<string>} options.contentTypes - Every type this build reads as
+ *   an address qualifier.
+ * @param {Set<string>} options.packages - Every package an address may name.
+ * @param {Set<string>} options.noIndexPackages - Packages declared
+ *   `contentIndex: false`.
+ * @param {string} options.contentPackage - The package a target with no
+ *   package segment defaults to.
+ * @param {Map<string, {url: string}>} options.siteIndexMap - {@link SiteIndex}'s
+ *   own `index`, read for the target's existence and its URL.
+ * @param {Map<string, Map<string, object>>} options.figuresByAddress - Every
+ *   note's figures, by id, keyed as {@link figureIndexKeys} keys the note.
+ * @returns {{url: string, figures: Map<string, object>}|undefined} The
+ *   target's own address and figures, or `undefined` when the address names
+ *   no note this build resolves.
+ */
+export function resolveCrossNoteFigures(
+    target,
+    { contentTypes, packages, noIndexPackages, contentPackage, siteIndexMap, figuresByAddress },
+) {
+    const read = readQualifier(target, contentTypes, packages, noIndexPackages);
+    if (!read || read.reason) return undefined;
+    const key = expandAddress(read, { package: contentPackage, system: NOTE_SYSTEM });
+    const shortKey = `${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase();
+    const entry = siteIndexMap.get(key) ?? siteIndexMap.get(shortKey);
+    if (!entry) return undefined;
+    const figures = figuresByAddress.get(key) ?? figuresByAddress.get(shortKey) ?? new Map();
+    return { url: entry.url, figures };
+}
+
 /**
  * The per-page context a wikilink resolver takes.
  *

package/engine/site-preview.mjs

@@ -270,6 +270,8 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                     const pos = positionOfLiteral(text, error.src, error.occurrence);
                     findings.push({ ...error, ...pos, severity: "error" });
                 }
+                for (const error of result.embedErrors)
+                    findings.push({ ...error, severity: "error" });
                 if (findings.length) return { ok: false, findings };
                 const edges = snapshot.rendered.edges.filter(([source]) => source !== original.url);
                 for (const hit of result.resolved) if (hit.url) edges.push([page.url, hit.url]);

package/engine/system-block.mjs

@@ -104,21 +104,24 @@
  *
  * A field's `name` is both its identity and the shared property it draws from,
  * and those coincide only while the two vocabularies agree about what the
- * spelling means. They do not always. An `affiliation` item's `system.title` is
- * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
- * `title` is the note's own heading, which the site emitter publishes. Two
- * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ * spelling means — or while the top-level vocabulary admits the spelling at
+ * all. They do not always. An `affiliation` item's `system.title` is the style
+ * of address an office carries — "Ajaw", "Warden"; a note's top-level `title`
+ * is refused outright by the closed top-level vocabulary, which has no `title`
+ * entry. Nothing relates them, and step 3 fed the first from the second anyway.
  *
  * It was not a harmless coincidence either, because step 3 answers **without**
  * applying `field.default` — only step 2 does — so an authored `title: null`
  * reached the field's coercion unguarded and shipped as the literal string
  * `"null"` in fifteen documents.
  *
- * So a field may declare `topLevelMeans`: what the top-level key of that name
- * means *instead*. Declaring it removes the whole shared level — step 3 and the
- * retiring 3b alike, since both read the note's top level and the objection is
- * to that level, not to a spelling — leaving the two positions that describe
- * the document rather than the note. It is deliberately
+ * So a field may declare `topLevelMeans`: why the note's top-level key of this
+ * name is not this field's source — declared wherever that key's spelling
+ * means something else at the note level, or the closed top-level vocabulary
+ * refuses it outright. Declaring it removes the whole shared level — step 3
+ * and the retiring 3b alike, since both read the note's top level and the
+ * objection is to that level, not to a spelling — leaving the two positions
+ * that describe the document rather than the note. It is deliberately
  * a per-field opt-out rather than a change to the order — step 3 is right
  * wherever the two levels state the same quantity, which is nearly everywhere —
  * and its value is the reason rather than a bare flag, so the collision is
@@ -362,22 +365,47 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
 }
 
 /**
- * A system override followed by a shared `data:` value. The top-level value
- * remains readable while content repositories move their authored fields.
+ * A system override followed by a shared `data:` value followed by the
+ * retiring top-level spelling `data:` gathered it off, reporting which one
+ * answered.
+ *
+ * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
+ * universal `data:` key — `pack` and `packFolder`, declared for every note
+ * type rather than per type, so neither is a `FieldSpec` that resolver takes.
+ * The order is the same shape: a system's own override, then the shared
+ * `data:` position, then the bare top-level key a tree authored before
+ * `data:` existed. The top-level value stays readable while a tree still on
+ * it moves its authored fields.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
  * @param {string} key - The shared property.
  * @param {any} [defaultValue] - Returned when no position declares it.
- * @returns {any} The selected value.
+ * @returns {{value: any, from: FieldSource}} The value, and where it came
+ *   from.
  */
-export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+export function resolveDataProperty(fm, block, key, defaultValue = undefined) {
     const declared = systemBlock(fm, block)?.[key];
-    if (declared !== undefined && declared !== null) return declared;
+    if (declared !== undefined && declared !== null) return { value: declared, from: "block" };
     const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
-    if (shared !== undefined && shared !== null) return shared;
+    if (shared !== undefined && shared !== null) return { value: shared, from: "shared" };
     const legacy = isMapping(fm) ? fm[key] : undefined;
-    return legacy === undefined || legacy === null ? defaultValue : legacy;
+    if (legacy !== undefined && legacy !== null) return { value: legacy, from: "topLevel" };
+    return { value: defaultValue, from: "default" };
+}
+
+/**
+ * {@link resolveDataProperty}'s value alone, for a caller that only compiles
+ * a document and has no use for which position answered.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+    return resolveDataProperty(fm, block, key, defaultValue).value;
 }
 
 /**

package/hm3/actors.mjs

@@ -78,7 +78,7 @@ import {
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
-const ACTOR_FIELDS = Object.freeze([
+export const ACTOR_FIELDS = Object.freeze([
     {
         name: "species",
         to: "species",
@@ -97,7 +97,7 @@ const ACTOR_FIELDS = Object.freeze([
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
-const CHARACTER_FIELDS = Object.freeze([
+export const CHARACTER_FIELDS = Object.freeze([
     {
         name: "data.gender",
         legacyKey: "gender",

package/hugo-theme/data/banners.yaml

@@ -0,0 +1,69 @@
+# Which banner images exist in the shared artwork set.
+#
+# `partials/hero-banner.html` resolves a page's hero image to a path under
+# `images/banners/`, and that path is emitted into a `background-image` with no
+# way to test it: the artwork is served from the consuming site's
+# `params.cdnBaseURL`, and Hugo cannot ask a remote host whether a URL exists.
+# So a banner that was never drawn used to 404 in silence — the band rendered
+# with its title, palette and gradient intact and a dead image URL behind it,
+# and nothing failed: not the build, not Hugo, not the deploy guard
+# (issue #36).
+#
+# This file is the declaration that replaces that missing test. A name listed
+# here is asserted to exist; a resolved banner whose name is absent falls back
+# to `default.webp` and Hugo warns once for it during the consumer's build.
+#
+# It speaks for the names this theme resolves itself — a hand-authored
+# `banner:` and the subtype defaults below. A note's own `data.banner` arrives
+# already resolved from an asset Address, against a real asset record, so it is
+# used as given and never looked for here.
+#
+# Keeping it in step is not left to hope: `npm run lint:banners`
+# (`utils/check-banners.mjs`, part of `npm run lint`) fetches every name below
+# from a real asset host and fails on any non-200. Add a name here only after
+# the file is published, or the check will say so.
+#
+# A consumer publishing its own artwork set overrides the whole list by
+# shipping its own `data/banners.yaml` — Hugo reads the site's data directory
+# in preference to the theme's.
+
+# The asset root every name below is resolved under, and the name used when a
+# resolved banner is not in `available`. Both are relative to the consuming
+# site's `params.cdnBaseURL`, like every other image path in this theme.
+dir: images/banners
+fallback: default.webp
+
+# Verified against https://cdn.heroiclands.org on 2026-08-29.
+available:
+    - affliction
+    - armor-clothing
+    - character
+    - company
+    - containers
+    - continent
+    - creature
+    - default
+    - dev-docs
+    - faith
+    - fvtt-add-on-modules
+    - fvtt-cc-anvil
+    - misc-gear
+    - module-dnload
+    - mystical-abilities
+    - orators-chance
+    - organization
+    - pantheon
+    - people
+    - projectiles
+    - region
+    - rules
+    - settlement
+    - site
+    - skills-attributes
+    - sohl-icon-3d-1920x1080
+    - ta-kheperu-banner
+    - tamzir-banner
+    - tapestry-of-dreams
+    - trauma
+    - user-guide
+    - weapons

package/hugo-theme/layouts/404.html

@@ -0,0 +1,85 @@
+{{- /*
+  "Page not found" page.
+
+  Hugo renders this template to `public/404.html`, and a static host such as
+  Cloudflare Pages serves that file — with a genuine HTTP 404 — for any path
+  the deployment does not publish. Without it, Pages falls back to the site
+  root, so an unknown path answers 200 with the landing page: a soft-404 that
+  makes every "does this URL resolve?" check report success, and lets search
+  engines index retired content as live (issue #1416).
+
+  Every consumer needs exactly this, so it lives here rather than being copied
+  into each one (issue #1454). The theme carries layout, not addresses, so the
+  wording and the routes back are supplied by the consuming site:
+
+    [params.notfound]
+      heroimage = "images/banner.webp"   # CDN-relative or absolute
+      tagline   = "This site has no page at"
+      sitenoun  = "site"                 # used in the body prose
+      [[params.notfound.links]]
+        title = "Home"
+        url   = "/"                      # relURL'd unless already absolute
+        text  = "Everything, from the top."
+
+  Each is guarded: a consumer supplying none still builds, and simply gets the
+  generic wording with no list of routes back.
+*/ -}}
+{{ define "main" }}
+{{- $nf := .Site.Params.notfound | default dict -}}
+{{- $img := $nf.heroimage | default "images/banners/default.webp" -}}
+{{- $heroURL := partial "cdn-url.html" (dict "site" .Site "path" $img) -}}
+{{- $tagline := $nf.tagline | default "This site has no page at" -}}
+{{- $noun := $nf.sitenoun | default "site" -}}
+<section class="hero hero-with-image" style="background-image: url('{{ $heroURL }}');">
+  <div class="hero-inner" data-pagefind-ignore>
+    <h1>Page not found</h1>
+    <p class="hero-tagline">{{ $tagline }} <code id="missing-path">the address you followed</code>.</p>
+  </div>
+</section>
+
+<article class="single">
+  <div class="single-content">
+    <div class="single-body">
+      <p>
+        The page may have been renamed, moved to another part of the
+        {{ $noun }}, or retired along with the concept it described. Links
+        from older discussions, issues, and search results can outlive the
+        pages they point at.
+      </p>
+      {{- with $nf.links }}
+      <p>Start again from one of these:</p>
+      <ul class="page-list">
+        {{- range . }}
+        {{- $url := .url -}}
+        {{- if not (or (hasPrefix $url "http://") (hasPrefix $url "https://") (hasPrefix $url "//")) -}}
+          {{- /* relURL only mounts a path under the site's base when it is
+                 given relative: a leading slash means "from the origin", and
+                 the base path is left off. Trim it, so a consumer writing the
+                 obvious "/section/" gets a link inside its own site even when
+                 that site is served under a prefix. */ -}}
+          {{- $url = strings.TrimPrefix "/" $url | relURL -}}
+        {{- end }}
+        <li class="page-list-item">
+          <a class="page-list-title" href="{{ $url }}">{{ .title }}</a>
+          {{- with .text }}
+          <span class="page-list-desc">{{ . }}</span>
+          {{- end }}
+        </li>
+        {{- end }}
+      </ul>
+      {{- end }}
+    </div>
+  </div>
+</article>
+
+{{/* Name the address that failed, so a reader can see what they followed and
+     quote it in a bug report. Static hosting cannot template it — Pages serves
+     this one file for every unmatched path — so it is filled in client-side,
+     and the markup above reads sensibly without scripting. */}}
+<script>
+  (function () {
+    var el = document.getElementById("missing-path");
+    if (el) el.textContent = window.location.pathname;
+  })();
+</script>
+{{ end }}

package/hugo-theme/layouts/_default/baseof.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{ if not .IsHome }}{{ .Title }} — {{ end }}{{ .Site.Title }}</title>
+  <meta name="description" content="{{ with .Params.description }}{{ . }}{{ else }}{{ .Site.Params.description }}{{ end }}">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Lora:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="{{ "css/style.css" | relURL }}">
+  {{/* Icon glyphs. SoHL documentation writes icons as <i class="fa-solid …">
+       or <i class="ginf-…">, the same markup the Foundry client renders, so a
+       page reads identically in a journal and here. Font Awesome's FREE set is
+       enough — the system deliberately uses no Pro-only icons — and the
+       game-icons webfont is subset to just the glyphs the docs reference
+       (~3 KB), generated by the SoHL repo. */}}
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
+  <link rel="stylesheet" href="{{ "css/sohl-icons.css" | relURL }}">
+</head>
+<body>
+  {{ partial "header.html" . }}
+  <main>
+    {{ block "main" . }}{{ end }}
+  </main>
+  {{ partial "footer.html" . }}
+  <script>
+  // Auto-enhance <span data-copy="URL"> elements with a clipboard copy button
+  document.querySelectorAll('[data-copy]').forEach(function(el) {
+    var url = el.getAttribute('data-copy');
+    el.classList.add('exturl');
+
+    // Wrap existing text in a code element if not already
+    if (!el.querySelector('.exturl-text')) {
+      var code = document.createElement('code');
+      code.className = 'exturl-text';
+      code.textContent = el.textContent;
+      el.textContent = '';
+      el.appendChild(code);
+    }
+
+    var btn = document.createElement('button');
+    btn.className = 'exturl-copy';
+    btn.title = 'Copy URL to clipboard';
+    btn.setAttribute('aria-label', 'Copy URL to clipboard');
+    btn.innerHTML =
+      '<svg class="exturl-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+        '<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>' +
+        '<path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1"/>' +
+      '</svg>' +
+      '<svg class="exturl-check" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">' +
+        '<polyline points="20 6 9 17 4 12"/>' +
+      '</svg>';
+    btn.addEventListener('click', function() {
+      navigator.clipboard.writeText(url).then(function() {
+        btn.classList.add('copied');
+        setTimeout(function() { btn.classList.remove('copied'); }, 1500);
+      });
+    });
+    el.appendChild(btn);
+  });
+  </script>
+</body>
+</html>

package/hugo-theme/layouts/_default/list.html

@@ -0,0 +1,139 @@
+{{- /*
+  Default list layout: hero, the authored body when there is one,
+  and an auto-list of the section's members.
+
+  Minimal by design: a package-build consumer disables Hugo's `section`,
+  `taxonomy` and `term` kinds, so this layout never runs for one — the home
+  page and its pages are all it renders through `index.html` and
+  `_default/single.html`. A site that keeps those kinds enabled — one that
+  is not a package-build consumer, publishing a hand-curated section of its
+  own — still needs a landing for them, which is what this file is for.
+
+  Content rows render "Name + description", inline rather than through a
+  shared partial: this is the only caller left, and a description is emitted
+  only when present, so a page carrying none renders a plain title row.
+*/ -}}
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+<article class="single">
+  <div class="single-content">
+    {{ if .Content }}
+    <div class="single-body" data-pagefind-body>
+      {{ .Content }}
+    </div>
+    {{ end }}
+
+    {{- /*
+      A curated landing is the best navigation — a rules section groups its
+      pages under editorial headings like "Key Concepts", which no hierarchy
+      can infer. But gating the auto-list on "has no body" meant authoring an
+      intro silently replaced the section's ONLY navigation, and hand-curated
+      lists drift: one guide reached 41 pages linking 1, and another had
+      quietly orphaned a page.
+
+      So the auto-list is a GAP-FILLER: a section with a body lists only the
+      pages that are not reachable from that body by following links. A landing
+      whose hierarchy covers everything shows nothing extra, and a page can
+      never become unreachable — a newly added page appears under "Orphaned
+      Pages" until someone files it into the curated index.
+
+      Taxonomy and term pages keep their own listing shapes below.
+    */ -}}
+    {{- $showAutoList :=
+      or (eq .Kind "taxonomy")
+         (eq .Kind "term")
+         (eq .Kind "section")
+    -}}
+    {{- $members := .Pages -}}
+    {{- /*
+      Pages reachable from the authored body, matched on RelPermalink so the
+      comparison survives aliases and wikilink resolution.
+
+      The needle deliberately stops after the URL rather than closing the quote,
+      so a link that carries a fragment counts. A rules landing reaches its
+      Characters chapter as `…/characters-introduction/#body-structure`, and
+      demanding the closing quote made that chapter read as unlinked. A trailing
+      slash ends every RelPermalink, so the open-ended match cannot bleed into a
+      sibling (`/rules/fate/` never prefixes `/rules/fate-points/`).
+
+      Reachability is TRANSITIVE, because a curated corpus is a hierarchy rather
+      than a flat index: a rules landing links ten chapter introductions, and
+      each of those links its own pages — up to four hops deep (root → Trauma →
+      Body → Injury → Bleeding). Testing only what the landing links DIRECTLY
+      counted every page below the first hop as a leftover. So a page counts as
+      listed when the body links it, or when any page already counted as listed
+      links it.
+
+      The walk runs to a fixed point: each pass appends the newly reached pages'
+      content to the haystack, and the first pass that reaches nothing new stops
+      it. Twelve passes is far past the depth of any corpus here (the rules need
+      four), and the `$growing` guard makes the surplus passes free.
+    */ -}}
+    {{- $unlisted := $members -}}
+    {{- if and (eq .Kind "section") .Content -}}
+      {{- $haystack := .Content -}}
+      {{- $reached := slice -}}
+      {{- $growing := true -}}
+      {{- range seq 12 -}}
+        {{- if $growing -}}
+          {{- $growing = false -}}
+          {{- range $members -}}
+            {{- if not (in $reached .RelPermalink) -}}
+              {{- if in $haystack (printf "href=\"%s" .RelPermalink) -}}
+                {{- $reached = $reached | append .RelPermalink -}}
+                {{- $haystack = print $haystack .Content -}}
+                {{- $growing = true -}}
+              {{- end -}}
+            {{- end -}}
+          {{- end -}}
+        {{- end -}}
+      {{- end -}}
+      {{- $unlisted = where $members "RelPermalink" "not in" $reached -}}
+    {{- end -}}
+    {{- /*
+      Label the leftovers only when a curated body precedes them. With
+      reachability transitive, anything still here is genuinely unreachable
+      by reading — an orphan — so the heading says so rather than claiming to be
+      the section's full contents.
+    */ -}}
+    {{- $labelList := and (eq .Kind "section") .Content -}}
+    {{- if $showAutoList -}}
+      {{- with $unlisted -}}
+        {{- if eq $.Kind "taxonomy" -}}
+        <ul class="page-list">
+          {{- range . }}
+          <li class="page-list-item">
+            <a class="page-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+            <span class="page-list-count">{{ len .Pages }}</span>
+          </li>
+          {{- end }}
+        </ul>
+        {{- else -}}
+          {{- if $labelList }}
+          <h2 class="page-list-heading">Orphaned Pages</h2>
+          {{- end }}
+          <ul class="page-list">
+            {{- range . }}
+            <li class="page-list-item">
+              <a class="page-list-title" href="{{ .RelPermalink }}">{{ .Title }}</a>
+              {{- with .Description }}
+              <span class="page-list-desc">{{ . }}</span>
+              {{- end }}
+            </li>
+            {{- end }}
+          </ul>
+        {{- end -}}
+      {{- else -}}
+      {{- /*
+        "Nothing here yet" is the right answer for an empty auto-listed section,
+        and the wrong one for a curated landing — there a leftover list of zero
+        means the hierarchy covers everything, so nothing should be said at all.
+      */ -}}
+        {{- if not $labelList -}}
+        <p class="page-list-empty">Nothing here yet.</p>
+        {{- end -}}
+      {{- end -}}
+    {{- end }}
+  </div>
+</article>
+{{ end }}

package/hugo-theme/layouts/_default/single.html

@@ -0,0 +1,4 @@
+{{ define "main" }}
+{{ partial "hero-banner.html" . }}
+{{ partial "page-body.html" . }}
+{{ end }}