@heroiclands/package-build 23.13.0 → 24.0.1

package/site-theme/partials/hero-banner.hbs

@@ -0,0 +1,11 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<section class="hero hero-with-image"{{#if bannerUrl}} style="background-image: url('{{cssUrl bannerUrl}}');"{{/if}}>
+  <div class="hero-inner" data-pagefind-ignore>
+    {{#if title}}
+    <h1>{{title}}</h1>
+    {{/if}}
+    {{#if tagline}}
+    <p class="hero-tagline">{{tagline}}</p>
+    {{/if}}
+  </div>
+</section>

package/site-theme/partials/infobox-entry.hbs

@@ -0,0 +1,2 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if entry.lead}}{{entry.lead}}{{/if}}{{#if entry.url}}<a class="{{class}}" href="{{entry.url}}">{{entry.text}}</a>{{else}}<span class="{{class}}">{{entry.text}}</span>{{/if}}

package/site-theme/partials/infobox-section.hbs

@@ -0,0 +1,31 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if rows}}
+<dl class="info-profile-grid">
+  {{#each rows}}
+  <dt>{{label}}</dt>
+  <dd>{{> infobox-value}}</dd>
+  {{/each}}
+</dl>
+{{else if grid}}
+<div class="info-attrs-grid">
+  {{#each cells}}
+  <div class="info-attr">
+    <span class="attr-label">{{label}}</span>
+    <span class="attr-value">{{value}}</span>
+  </div>
+  {{/each}}
+</div>
+{{else if runin}}
+  {{#each groups}}
+<p class="info-skill-line">
+  {{#if label}}<span class="skill-cat">{{label}}:</span>{{/if}}
+  <span class="skill-entries">{{#each entries}}{{#unless @first}}, {{/unless}}{{> infobox-entry entry=this class="skill-entry"}}{{/each}}</span>
+</p>
+  {{/each}}
+{{else if list}}
+<ul class="info-mystical-list">
+  {{#each entries}}
+  <li class="info-mystical-item">{{> infobox-entry entry=this class="mystical-name"}}</li>
+  {{/each}}
+</ul>
+{{/if}}

package/site-theme/partials/infobox-value.hbs

@@ -0,0 +1,2 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if isLink}}{{> infobox-entry entry=entry class="info-link"}}{{else if isLinks}}{{#each entries}}{{#unless @first}}, {{/unless}}{{> infobox-entry entry=this class="info-link"}}{{/each}}{{else}}{{text}}{{/if}}

package/site-theme/partials/infobox.hbs

@@ -0,0 +1,18 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#each boxes}}
+<details class="info-sidebar info-box{{#if id}} info-box-{{id}}{{/if}}" open data-pagefind-ignore>
+  <summary class="info-sidebar-title"><h2>{{title}}</h2></summary>
+  {{#if statement}}
+  <p class="info-statement">{{statement}}</p>
+  {{else}}
+    {{#each sections}}
+  <section class="info-section{{#if id}} info-section-{{id}}{{/if}}">
+    {{#if label}}
+    <h3 class="info-section-title">{{label}}</h3>
+    {{/if}}
+    {{> infobox-section}}
+  </section>
+    {{/each}}
+  {{/if}}
+</details>
+{{/each}}

package/site-theme/partials/list-members.hbs

@@ -0,0 +1,9 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if listing}}
+  {{#if heading}}
+<h2 class="page-list-heading">{{heading}}</h2>
+  {{/if}}
+{{> page-list listing}}
+{{else if empty}}
+<p class="page-list-empty">Nothing here yet.</p>
+{{/if}}

package/site-theme/partials/nav-links.hbs

@@ -0,0 +1,5 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<nav class="single-nav" data-pagefind-ignore>
+  {{#if prev}}<a href="{{prev.url}}" class="nav-prev">&larr; {{prev.title}}</a>{{/if}}
+  {{#if next}}<a href="{{next.url}}" class="nav-next">{{next.title}} &rarr;</a>{{/if}}
+</nav>

package/site-theme/partials/page-body.hbs

@@ -0,0 +1,48 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<article class="{{articleClass}}"{{#unless hasBody}} data-pagefind-body{{/unless}}>
+  {{#if isDraft}}
+  {{> draft-notice}}
+  {{/if}}
+  {{> search-meta search}}
+  {{#unless hasBody}}{{> search-names search}}{{/unless}}
+  {{#if hasSidebar}}
+  <aside class="info-rail">
+    {{> infobox}}
+    {{#if tocBeside}}
+    {{> toc}}
+    {{/if}}
+  </aside>
+  {{/if}}
+  {{#if hasMain}}
+  <div class="single-content">
+    {{#if meta}}
+    <div class="single-meta">
+      {{#if meta.date}}
+      <time class="single-date" datetime="{{meta.date.iso}}">{{meta.date.text}}</time>
+      {{/if}}
+      {{#if meta.subtype}}<span class="single-subtype">{{meta.subtype}}</span>{{/if}}
+      {{#if meta.tags}}
+      {{> tags meta.tags}}
+      {{/if}}
+    </div>
+    {{/if}}
+
+    {{#if hasBody}}
+    <div class="single-body" data-pagefind-body>
+      {{> search-names search}}
+      {{{content}}}
+    </div>
+    {{/if}}
+
+    {{#if related}}
+    {{> related related}}
+    {{/if}}
+    {{#if nav}}
+    {{> nav-links nav}}
+    {{/if}}
+  </div>
+  {{/if}}
+  {{#if tocBelow}}
+  {{> toc}}
+  {{/if}}
+</article>

package/site-theme/partials/page-list.hbs

@@ -0,0 +1,14 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<ul class="page-list">
+  {{#each items}}
+  <li class="page-list-item">
+    <a class="page-list-title" href="{{url}}">{{title}}</a>
+    {{#if count}}
+    <span class="page-list-count">{{count}}</span>
+    {{/if}}
+    {{#if text}}
+    <span class="page-list-desc">{{text}}</span>
+    {{/if}}
+  </li>
+  {{/each}}
+</ul>

package/site-theme/partials/related.hbs

@@ -0,0 +1,24 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<section class="related" aria-labelledby="related-heading" data-pagefind-ignore>
+  <h2 id="related-heading" class="related-heading">Related</h2>
+  {{#if seeAlso}}
+  <div class="related-group">
+    <h3 class="related-group-label">See also</h3>
+    <ul class="related-group-grid">
+      {{#each seeAlso}}
+      <li><a href="{{url}}">{{title}}</a>{{#if gloss}} — {{gloss}}{{/if}}</li>
+      {{/each}}
+    </ul>
+  </div>
+  {{/if}}
+  {{#each groups}}
+  <div class="related-group">
+    <h3 class="related-group-label">{{label}}</h3>
+    <ul class="related-group-grid">
+      {{#each refs}}
+      <li><a href="{{url}}">{{title}}</a></li>
+      {{/each}}
+    </ul>
+  </div>
+  {{/each}}
+</section>

package/site-theme/partials/search-meta.hbs

@@ -0,0 +1,6 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if title}}<span data-pagefind-meta="title" hidden>{{title}}</span>{{/if}}
+{{#each filters}}{{#each values}}<span data-pagefind-filter="{{../name}}" hidden>{{this}}</span>{{/each}}{{/each}}
+{{#if aliases}}<span data-pagefind-meta="aliases" hidden>{{aliases}}</span>{{/if}}
+{{#if image}}<span data-pagefind-meta="image" hidden>{{image}}</span>{{/if}}
+{{#if date}}<span data-pagefind-sort="date" hidden>{{date}}</span>{{/if}}

package/site-theme/partials/search-names.hbs

@@ -0,0 +1,2 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+{{#if names}}<span data-pagefind-weight="{{weight}}" hidden>{{names}}</span>{{/if}}

package/site-theme/partials/search.hbs

@@ -0,0 +1,52 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<div class="site-search" data-pagefind-ignore>
+  <button
+    type="button"
+    class="search-toggle"
+    aria-label="Search"
+    aria-expanded="false"
+    aria-controls="site-search-panel"
+  ><i class="fa-solid fa-magnifying-glass" aria-hidden="true"></i></button>
+  <div id="site-search-panel" class="search-panel" hidden>
+    <div class="search-panel-inner" id="search"></div>
+  </div>
+</div>
+<link rel="stylesheet" href="{{urls.pagefindCss}}">
+<script src="{{urls.pagefindJs}}" defer></script>
+<script>
+(function () {
+  var toggle = document.querySelector(".search-toggle");
+  var panel = document.getElementById("site-search-panel");
+  if (!toggle || !panel) return;
+  var ui = null;
+
+  function open() {
+    panel.hidden = false;
+    toggle.setAttribute("aria-expanded", "true");
+    if (!ui && typeof PagefindUI !== "undefined") {
+      ui = new PagefindUI({{{json searchOptions}}});
+    }
+    var input = panel.querySelector("input");
+    if (input) input.focus();
+  }
+
+  function close() {
+    panel.hidden = true;
+    toggle.setAttribute("aria-expanded", "false");
+  }
+
+  toggle.addEventListener("click", function () {
+    if (panel.hidden) { open(); } else { close(); }
+  });
+
+  document.addEventListener("keydown", function (e) {
+    if (e.key === "Escape" && !panel.hidden) close();
+  });
+
+  document.addEventListener("click", function (e) {
+    if (panel.hidden) return;
+    if (panel.contains(e.target) || toggle.contains(e.target)) return;
+    close();
+  });
+})();
+</script>

package/site-theme/partials/tags.hbs

@@ -0,0 +1,4 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<div class="single-tags">
+  {{#each items}}{{#if url}}<a href="{{url}}" class="tag">{{name}}</a>{{else}}<span class="tag">{{name}}</span>{{/if}}{{/each}}
+</div>

package/site-theme/partials/toc.hbs

@@ -0,0 +1,7 @@
+{{!-- SPDX-License-Identifier: GPL-3.0-or-later --}}
+<aside class="toc" aria-label="Table of contents" data-pagefind-ignore>
+  <div class="toc-inner">
+    <p class="toc-label">On this page</p>
+    {{{toc}}}
+  </div>
+</aside>

package/{hugo-theme → site-theme}/static/css/style.css

@@ -53,6 +53,13 @@
      a footnote may be called from inside a blockquote or a named block. */
   --footnote-marker: var(--accent-hover);
 
+  /* A rubric script's emphasis, which is carried by colour alone. Checked
+     against every surface text sits on, and against --text so the emphasis
+     survives without its hue: 5.62:1 on --bg, 5.21:1 on --bg-card, 4.57:1 on
+     --surface, and 2.13:1 against --text. A consuming site that overrides it
+     re-checks both. */
+  --rubric: #e0705f;
+
   --font-display:  'Cinzel', 'Georgia', serif;
   --font-body:     'Lora', 'Georgia', serif;
   --font-mono:     'JetBrains Mono', monospace;
@@ -3110,3 +3117,10 @@ summary.info-sidebar-title::after {
 .font-serif { font-family:var(--font-body); }
 .font-sans { font-family:sans-serif; }
 .font-mono { font-family:var(--font-mono); }
+
+/* Emphasis in a script follows the script's convention, never a weight or a
+   slant the face does not have: the element keeps the face's Regular, and
+   its class sets the convention. */
+.script :is(em, strong) { font-style:normal; font-weight:inherit; font-synthesis:none; }
+.emph-rubric { color:var(--rubric); }
+.emph-overline { text-decoration-line:overline; text-decoration-skip-ink:none; }

package/stage.mjs

@@ -44,8 +44,7 @@ import path from "node:path";
  *
  * A repository adds its own through `packageBuild.clean.extra`, but these four
  * are common to all of them because they come from the shared toolchain rather
- * than from any one package's layout. Everything the site build writes — the
- * Hugo source tree, Hugo's cache and the rendered site — is under `build/`.
+ * than from any one package's layout. Everything the site build writes is under `build/`.
  */
 export const BUILD_ARTIFACT_DIRS = Object.freeze(["build", ".vite", ".vitepress", ".rollup.cache"]);
 

package/types/config.d.mts

@@ -7,7 +7,7 @@
  *
  * Exported so a sibling module composing a configuration value this module
  * does not itself validate — {@link module:engine/site-config}'s
- * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * `siteSettings`, checking `site.assets` — reports through the one helper
  * rather than a second copy.
  *
  * @param {string} where - Dotted path of the offending key.
@@ -32,8 +32,7 @@ export function resolveAssetTransform(declared: string, rootDir: string): string
  *
  * A package's Foundry manifest already derives its own `url` from
  * `contentPackage` (`packageHomepage` in `manifest.mjs`); `homepage` states
- * the same address a second time, in `package.json`, for the generated Hugo
- * configuration to read a `baseURL` from without knowing where each
+ * the same address a second time, in `package.json`, for the site build to read a base URL from without knowing where each
  * repository keeps its own site configuration.
  *
  * Required unconditionally: every package publishes a site, so there is no
@@ -45,12 +44,17 @@ export function resolveAssetTransform(declared: string, rootDir: string): string
  * `packageHomepage(contentPackage)`, independent of it. The right caller is
  * whatever reads `homepage` to write a site's `baseURL`.
  *
+ * A site that states `site.base` is served at that path instead, and its
+ * `homepage` is that path on its origin: `/` makes it the origin's root.
+ *
  * @param {string|null} homepage - The resolved `package.json` `homepage`, or
  *   `null` when none is declared.
  * @param {string} contentPackage - The resolved `contentPackage`.
+ * @param {string} [base] - The resolved `site.base`; `""` or absent for a
+ *   package site, served at `/<contentPackage>/`.
  * @returns {void}
  */
-export function checkHomepage(homepage: string | null, contentPackage: string): void;
+export function checkHomepage(homepage: string | null, contentPackage: string, base?: string): void;
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
  *

package/types/content-config.d.mts

@@ -11,6 +11,20 @@
 export function compilesFoundryDocuments(config: {
     packageKind: string;
 }): boolean;
+/**
+ * The path a package's site is served at: `site.base` where it states one,
+ * `/<contentPackage>/` otherwise.
+ *
+ * @param {{contentPackage: string, site: {base: string}}} config - The resolved
+ *   configuration.
+ * @returns {string} The path, beginning and ending with `/`.
+ */
+export function siteBase(config: {
+    contentPackage: string;
+    site: {
+        base: string;
+    };
+}): string;
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
@@ -136,20 +150,6 @@ export const AUTHOR_ROLES: readonly string[];
  * @type {symbol}
  */
 export const DERIVED_SYSTEM_VERSION: symbol;
-/**
- * Hugo keys a repository may **not** declare under `site.hugo`, because the
- * site build generates them and would only overwrite what was written.
- *
- * The same rule `DERIVED_MANIFEST_KEYS` states for the manifest, for the same
- * reason: an authored `baseURL` would look authoritative, sit there unread,
- * and disagree with the site forever. Each key names where its value comes
- * from. A dotted key names a nested one, and covers everything beneath it —
- * `params.brand` refuses `params.brand.logo` too — so `site.hugo` reaches only
- * what the generator does not write.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
 /**
  * One declared book, resolved.
  */
@@ -328,7 +328,7 @@ export type PathsInput = {
     metadataCache?: string | undefined;
     /**
      * Where the site navigation is fetched
-     *   to, for the generated Hugo menu.
+     *   to, for the site's menu.
      */
     navigationCache?: string | undefined;
 };

package/types/engine/asset-shipping.d.mts

@@ -112,8 +112,11 @@ export function assetsManifest(staged: readonly object[], stageDir: string): Ass
  *
  * The pictures are written beside whatever a `packageBuild.assets` row already
  * put under `icons/` and `images/`; nothing there is removed. A picture whose
- * deployed path is already a file in the stage is a finding, and no picture is
- * written. Clearing an earlier run's pictures is the stage reset's work.
+ * deployed path already holds a file with the bytes it would stage — after the
+ * transform, when there is one — is its own earlier output and is skipped, so
+ * staging twice into one directory is quiet. A file there with other bytes is a
+ * finding, and no picture is written. Clearing an earlier run's pictures is the
+ * stage reset's work.
  *
  * @param {object} opts - Options.
  * @param {string} opts.assetsBase - The package's asset directory, the roots'

package/types/engine/base-compiler.d.mts

@@ -1,3 +1,20 @@
+/**
+ * The tallies one pass accumulates while walking the tree.
+ *
+ * `declined` and `skippedOther` are deliberately separate numbers. A declined
+ * note is one this build **refused** — it declares `package:` — and it is an
+ * error; a skipped one legitimately belongs to another pass, and
+ * there are thousands of those. Folding the first into the second is what let a
+ * whole tree be filtered out in silence.
+ *
+ * @typedef {object} PassStats
+ * @property {number} compiled - Notes that became a document.
+ * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
+ * @property {number} skippedOther - Notes this pass does not claim.
+ * @property {number} declined - Notes this pack **refused** — one declaring
+ *   `package:`, or one routed to a system pack whose system it says nothing
+ *   about. Counted as errors, never as skips.
+ */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
  *
@@ -381,8 +398,9 @@ export class BasePackCompiler {
     /**
      * The body {@link BasePackCompiler#buildEntry} receives.
      *
-     * Generated tables expand before wikilinks are converted, so a cell a
-     * table emits is resolved along with the authored links.
+     * The body is expanded by {@link module:engine/content-expand.expandContent}
+     * for Foundry: generated tables expand before wikilinks are converted, so
+     * a cell a table emits is resolved along with the authored links.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} body - The note body, as authored.

package/types/engine/content-address.d.mts

@@ -41,7 +41,7 @@ export function addressSlug(fm: object): string;
  * composing a URL prepends where the package is served (`/<package>/`); a
  * consumer composing a manifest entry measures against that same base. Nothing
  * else is prepended: `prefix` says where the content tree *mounts inside the
- * package* — the Hugo directory its pages are written under — and an address is
+ * package* — where its pages sit in the source tree — and an address is
  * `(type, shortcode)`, a package-wide identity that takes no mount, so `sohl`
  * publishes `/sohl/affliction-aconite/` from a file written under `kb/`. The
  * `type-` half is what keeps that flat namespace clear of the package's fixed

package/types/engine/content-alerts.d.mts

@@ -23,9 +23,15 @@ export function scanAlerts(source: string): {
 };
 /** Render alert wrappers while preserving ordinary Markdown and note footnotes.
  * @param {string} source - Authored Markdown.
- * @param {"web"|"foundry"} [target="web"] - Publishing surface.
+ * @param {"web"|"foundry"|"preview"} [target="web"] - Publishing surface: the
+ *   preview draws the icon as an inline drawing, since a buffer has no icon font.
+ * @param {object} [options]
+ * @param {(markdown: string) => string} [options.renderInline] - How a title
+ *   is rendered; omitted, a title is plain inline Markdown.
  */
-export function renderAlerts(source: string, target?: "web" | "foundry"): {
+export function renderAlerts(source: string, target?: "web" | "foundry" | "preview", { renderInline }?: {
+    renderInline?: ((markdown: string) => string) | undefined;
+}): {
     markdown: string;
     errors: {
         line: number;

package/types/engine/content-blocks.d.mts

@@ -28,7 +28,8 @@ export function scanBlocks(source: string): {
  * Render named blocks for one publishing surface.
  *
  * `foundry` emits a `<section>` whose heading is its first line; `web` emits a
- * `<details>` the reader opens. Neither carries an inline `style`.
+ * `<details>` the reader opens, and `preview` the same without the search
+ * marker. None carries an inline `style`.
  *
  * The body is left as Markdown between the wrapper's tags, each separated from
  * its tag by a blank line — see the module docs for why that is what lets the
@@ -38,10 +39,15 @@ export function scanBlocks(source: string): {
  * A finding does not stop the well-formed blocks around it from rendering.
  *
  * @param {string} source - Markdown containing named blocks.
- * @param {"foundry"|"web"} target - Publishing surface.
+ * @param {"foundry"|"web"|"preview"} target - Publishing surface.
+ * @param {object} [options]
+ * @param {(markdown: string) => string} [options.renderInline] - How a title
+ *   is rendered; omitted, a title is plain inline Markdown.
  * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
  */
-export function renderBlocks(source: string, target: "foundry" | "web"): {
+export function renderBlocks(source: string, target: "foundry" | "web" | "preview", { renderInline }?: {
+    renderInline?: ((markdown: string) => string) | undefined;
+}): {
     markdown: string;
     errors: Array<{
         line: number;
@@ -58,7 +64,8 @@ export function renderBlocks(source: string, target: "foundry" | "web"): {
  *
  * **A spoiler, not access control.** The section is in the published page, so a
  * reader who opens the element or reads the source reads it. Foundry is the one
- * surface that withholds anything.
+ * surface that withholds anything. The disclosure is kept out of the site's
+ * search index, as a `secret` block is, so no result quotes it.
  *
  * @param {string} source - A page's Markdown, headings intact.
  * @returns {string} The same Markdown, each withheld section inside a