@heroiclands/package-build 23.12.8 → 24.0.0

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;
@@ -1378,33 +1385,109 @@ a.tag:hover {
 }
 
 /* Verse lines are hard breaks in the markup; paragraphs mark stanzas. */
-.single-content .poetry {
+.single-content .verse {
   margin: 1.5rem 0;
   line-height: 1.7;
 }
 
-.single-content .poetry p {
+.single-content .verse p {
   margin: 0;
 }
 
-.single-content .poetry p + p {
+.single-content .verse p + p {
   margin-top: 1em;
 }
 
-.single-content .poetry .poetry-line {
+.single-content .verse .verse-line {
   display: inline-block;
-  margin-inline-start: var(--poetry-indent, 0em);
+  margin-inline-start: var(--verse-indent, 0em);
   white-space: pre-wrap;
 }
 
-.single-content .poetry .poetry-line.i1 { --poetry-indent: 1.25em; }
-.single-content .poetry .poetry-line.i2 { --poetry-indent: 2.5em; }
-.single-content .poetry .poetry-line.i3 { --poetry-indent: 3.75em; }
-.single-content .poetry .poetry-line.i4 { --poetry-indent: 5em; }
-.single-content .poetry .poetry-line.i5 { --poetry-indent: 6.25em; }
-.single-content .poetry .poetry-line.i6 { --poetry-indent: 7.5em; }
-.single-content .poetry .poetry-line.i7 { --poetry-indent: 8.75em; }
-.single-content .poetry .poetry-line.i8 { --poetry-indent: 10em; }
+.single-content .verse .verse-line.i1 { --verse-indent: 1.25em; }
+.single-content .verse .verse-line.i2 { --verse-indent: 2.5em; }
+.single-content .verse .verse-line.i3 { --verse-indent: 3.75em; }
+.single-content .verse .verse-line.i4 { --verse-indent: 5em; }
+.single-content .verse .verse-line.i5 { --verse-indent: 6.25em; }
+.single-content .verse .verse-line.i6 { --verse-indent: 7.5em; }
+.single-content .verse .verse-line.i7 { --verse-indent: 8.75em; }
+.single-content .verse .verse-line.i8 { --verse-indent: 10em; }
+
+/* Numbered verse carries its numbers in a margin. A verse in columns is one
+   grid per verse line: its number, then each column's parts stacked, the
+   first in the normal tone and the rest muted, every part in the body serif
+   unless its face sets it. A narrow verse stacks the columns of each line. */
+.single-content .verse.verse-numbered {
+  position: relative;
+  padding-inline-start: 3em;
+}
+
+.single-content .verse .verse-number {
+  color: var(--text-muted);
+  font-size: 0.8em;
+}
+
+.single-content .verse-numbered .verse-line .verse-number {
+  position: absolute;
+  inset-inline-start: 0;
+  width: 2.2em;
+  text-align: end;
+}
+
+.single-content .verse.verse-columns {
+  container-type: inline-size;
+}
+
+.single-content .verse-numbered.verse-columns {
+  padding-inline-start: 0;
+}
+
+.single-content .verse-columns .verse-row {
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  column-gap: 1.5rem;
+  margin-bottom: 0.5em;
+}
+
+.single-content .verse-numbered.verse-columns .verse-row {
+  grid-template-columns: 2.5em;
+}
+
+.single-content .verse-columns .verse-number {
+  text-align: end;
+  padding-top: 0.2em;
+}
+
+.single-content .verse-columns :is(.verse-column, .verse-part) {
+  display: block;
+  white-space: pre-wrap;
+}
+
+.single-content .verse-columns .verse-part {
+  font-family: var(--font-body);
+}
+
+.single-content .verse-columns .verse-secondary {
+  color: var(--text-muted);
+}
+
+.single-content .verse-columns .verse-part[dir="rtl"] {
+  text-align: start;
+}
+
+@container (max-width: 32rem) {
+  .single-content .verse-columns .verse-row {
+    grid-auto-flow: row;
+    grid-template-columns: 1fr;
+  }
+  .single-content .verse-numbered.verse-columns .verse-row {
+    grid-template-columns: 2.5em 1fr;
+  }
+  .single-content .verse-numbered.verse-columns .verse-column {
+    grid-column: 2;
+  }
+}
 
 /* Ornamental horizontal rule: thin line flanking a centered gold
    diamond. Uses gradients on ::before/::after to keep the markup
@@ -3021,6 +3104,8 @@ summary.info-sidebar-title::after {
 .single-body .dictionary > div > dd { display:inline; margin:0; font-weight:normal; }
 .single-body .dictionary > div > dd > :is(p, ul, ol, dl, blockquote, pre, table, div) { text-indent:0; }
 .single-body .dictionary > div > dd > p:first-child { display:inline; }
+.single-body .dictionary > div > dd + dd { display:block; text-indent:0; }
+.single-body .dictionary > div > dd + dd > p:first-child { display:block; }
 @media (max-width:600px) { .single-body .dictionary { --indent:100px; } }
 
 /* ---- Text in one of the faces ----
@@ -3028,7 +3113,14 @@ summary.info-sidebar-title::after {
    right-to-left block or verse reads from the right. `font=serif`, `sans`
    and `mono` set the site's own serif and mono, and the reader's sans. */
 .script-block { margin:1rem 0; line-height:1.7; }
-.script-block[dir="rtl"], .poetry[dir="rtl"] { text-align:start; }
+.script-block[dir="rtl"], .verse[dir="rtl"] { text-align:start; }
 .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/code-fences.d.mts

@@ -17,13 +17,13 @@ export function parseHeaderArgs(info: string): {
  * @param {object} [options]
  * @param {boolean} [options.spans=true] - Include inline code spans. Set false
  *   to consider only block-level code.
- * @param {boolean} [options.poetryAsProse=true] - Treat verse bodies as inline prose.
+ * @param {boolean} [options.verseAsProse=true] - Treat verse bodies as inline prose.
  * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
  *   source order. `end` is exclusive.
  */
-export function codeRegions(markdown: string | null | undefined, { spans, poetryAsProse }?: {
+export function codeRegions(markdown: string | null | undefined, { spans, verseAsProse }?: {
     spans?: boolean | undefined;
-    poetryAsProse?: boolean | undefined;
+    verseAsProse?: boolean | undefined;
 }): Array<{
     start: number;
     end: number;

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