@heroiclands/package-build 21.2.0 → 22.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @heroiclands/package-build
 
+## 22.0.0
+
+### Major Changes
+
+- a278438: **A manifest's `url` is the package's homepage.** It is the Project Homepage link
+  a reader follows from the Foundry package listing _before_ installing anything,
+  so it answers "what is this?" — which the authored page at
+  `https://www.heroiclands.org/<contentPackage>/` does and a source tree does not.
+  `bugs`, `manifest` and `download` address release artefacts and stay on the
+  repository holding them. The address is derived from the content package rather
+  than declared, because the shared site-deploy workflow already publishes there; a
+  declared copy would be a second spelling of a settled fact, and the one free to
+  drift, since nothing fetches `url` the way Foundry fetches `manifest`.
+  
+  **Breaking — `releaseUrls` takes `homeUrl`.** A call without it produced a
+  manifest advertising `undefined`, so the parameter is required rather than
+  defaulted. `packageHomepage` and `HOMEPAGE_ORIGIN` are exported beside it, and
+  `packageHomepage` refuses an empty name for the same reason.
+  
+  **A configuration always names a content package**, so the manifest no longer
+  carries the branch that handled one that did not: the content index is advertised
+  unconditionally, which is what the comment above it already claimed.
+
+### Patch Changes
+
+- dec6ef4: **A full-page picture prints where it was written** — In the book, an image
+  marked as full width now opens the page that follows the prose introducing it,
+  with the rest of that prose running below it. It can no longer appear above the
+  sentence that points at it, or a page later than the text that follows it.
+  
+  - _A picture that asks for a float still floats_, which is what a float is for.
+  - _A picture taller than the page takes a page of its own._
+- 32322bd: **Dependency bumps** — `package-build bump` is described by what it is for: npm
+  performs the resolution, so a version whose dependency set differs from the one
+  it replaces is taken as correctly as one that moves three lines, while patching
+  the lockfile by hand is right only while the two dependency sets match. npm
+  writes `package-lock.json` with the indentation `package.json` uses, so a
+  formatted manifest yields a formatted lockfile; the bump holds each file to the
+  indent it already carries, which is what covers a lockfile indented unlike its
+  manifest.
+
 ## 21.2.0
 
 ### Minor Changes

package/bin/package-build.mjs

@@ -1137,10 +1137,11 @@ function e2eCommand() {
  * `bump [packages..]` — take a newer version of a dependency.
  *
  * npm does the resolving, so a bump whose dependency set changed is as correct
- * as one that moves three lines. What this adds is the indentation: every
- * repository here writes `package-lock.json` with four spaces and
- * prettier-ignores it, and npm rewrites it with two, so the version change
- * arrives buried in a whole-file reformat.
+ * as one that moves three lines; patching the lockfile by hand is right only
+ * while the two dependency sets match, and nothing says when they stop
+ * matching. npm writes the lockfile with `package.json`'s indentation, and
+ * this holds each file to the indent it already carried, so a lockfile indented
+ * unlike its manifest keeps its own.
  *
  * Named nothing, it takes the first-party packages — the ones a person bumps
  * by hand, the moment a release publishes, usually to unblock the change that
@@ -1151,7 +1152,7 @@ function e2eCommand() {
 function bumpCommand() {
     return {
         command: "bump [packages..]",
-        describe: "Take a newer version of a dependency, keeping the lockfile's formatting",
+        describe: "Take a newer published version of a declared dependency",
         builder: (y) =>
             y
                 .positional("packages", {

package/docs/api.md

@@ -1487,7 +1487,9 @@ console.log(normalizeRepoUrl("git@github.com:HeroicLands/sohl.git"));
 | ------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ARTIFACTS`                    | `const ARTIFACTS`                                                                   | —                                                                                                                       | reading the two Foundry package kinds (`"system"`, `"module"`) as the artifact name their manifest and release archive are called                                                  |
 | `normalizeRepoUrl`             | `normalizeRepoUrl(repository)`                                                      | `string` — normalised `https://` URL, no trailing slash                                                                 | normalising `package.json`'s `repository` field (object or shorthand string, `git+…git` or plain) to the exact URL Foundry fetches release assets from                             |
-| `releaseUrls`                  | `releaseUrls({ repoUrl, version, artifact })`                                       | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's release addresses — `manifest` points at `releases/latest` so an installed package can discover updates, `download` is pinned to this version              |
+| `HOMEPAGE_ORIGIN`              | `HOMEPAGE_ORIGIN`                                                                   | `string` — the origin every package's homepage is served from                                                           | stating the site origin once, so the address a manifest advertises and the address the configuration documents cannot disagree                                                     |
+| `packageHomepage`              | `packageHomepage(contentPackage)`                                                   | `string` — `<origin>/<contentPackage>/`                                                                                 | deriving the homepage a manifest's `url` points at; throws when given no name rather than advertising `<origin>/undefined/`                                                        |
+| `releaseUrls`                  | `releaseUrls({ repoUrl, homeUrl, version, artifact })`                              | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's addresses — `url` is the homepage a reader follows before installing, while `bugs`, `manifest` and `download` stay on the repository holding the artefacts |
 | `metadataUrl`                  | `metadataUrl({ repoUrl, version, contentPackage })`                                 | `string` — the version-pinned asset URL                                                                                 | computing where this release publishes its content index, pinned to this version like `download` so a dependency's manifest and its fetched index always describe the same release |
 | `manifestPacks`                | `manifestPacks(config)`                                                             | `object[]`                                                                                                              | deriving the manifest's `packs` array from the one pack list the build already has, in build order, companions flattened in                                                        |
 | `packFolderFindings`           | `packFolderFindings({ packFolders, packs = [] })`                                   | `Array<{severity: "error"\|"warning", message: string, pack: string, folder?: string, keyPath: Array<string\|number>}>` | checking a declared `packFolders` against the derived pack list — a folder naming a pack that does not exist is an error, a pack no folder names is a warning                      |

package/docs/commands.md

@@ -441,7 +441,7 @@ None.
 
 **NAME**
 
-Take a newer version of a dependency, keeping the lockfile's formatting.
+Take a newer published version of a declared dependency.
 
 **SYNOPSIS**
 
@@ -453,17 +453,20 @@ package-build bump [packages..] [--tag <tag>] [--check]
 
 Takes the newest published version of one or more declared dependencies,
 updating `package-lock.json` — and `package.json` when the declared range has to
-move — then restoring both files to the indentation they already used.
+move — and holding both files to the indentation they already carry.
 
-npm performs the resolution, so a version whose dependency set differs from the
-one it replaces is handled as correctly as one that moves three lines. Editing
-those three lines by hand is only right while the two dependency sets are
-identical, and nothing tells the author when they are not.
+npm performs the resolution, which is what this exists for. A version whose
+dependency set differs from the one it replaces is handled as correctly as one
+that moves three lines, while editing the `version` / `resolved` / `integrity`
+lines by hand is only right while the two dependency sets are identical — and
+nothing tells the author when they are not.
 
-The indentation is the reason this exists rather than `npm install` being run
-directly. Every repository consuming this toolchain writes `package-lock.json`
-with four spaces and prettier-ignores it; npm rewrites it with two, turning a
-three-line version change into a whole-file reformat no reviewer can read past.
+npm writes `package-lock.json` with the indentation `package.json` uses, so a
+consumer whose manifest is formatted gets a formatted lockfile back and the
+diff is the version change alone. The indentation step covers the case where
+the two files disagree: each is written back with the indent it already
+carried, rather than the lockfile taking the manifest's. A run that had to put
+an indent back names the file it rewrote.
 
 Named no packages, it takes every `@heroiclands/*` dependency the manifest
 declares. That scope is the one a person bumps by hand — a first-party release
@@ -496,7 +499,6 @@ every package is already current.
 ```
 $ package-build bump
 @heroiclands/package-build  20.6.0 → 20.7.0
-   kept the existing indentation of package-lock.json
 
 Install it with `npm ci`, which resolves from the lockfile this just moved.
 ```

package/docs/content-format.md

@@ -1754,8 +1754,17 @@ not. The website and a Foundry journal get true CSS wrap from the same
 directive. Expect the same statement, not the same page.
 
 An image with no `float:` is an ordinary block in the flow, where it was
-written. A `.full-width` image is placed at the top of the page it falls on,
-since a block cannot leave the column it is set in.
+written. A `.full-width` image is set at the **top of a new page**: the book is
+set in two columns, only a float spans them both, and a float is placed where
+the page has room rather than where it was written — so the page breaks before
+the picture, and the prose that follows it runs below it on the same page. The
+picture can therefore never print above the prose that introduces it or after
+the prose that follows it, at the cost of the page before it ending short. A
+picture taller than the page takes a page of its own.
+
+A `.full-width` image that **also states a `float:`** is asking for a float and
+gets one, with no break before it. A float is placed where it fits, which may be
+the next page.
 
 ##### Both vocabularies are closed
 

package/engine/dependency-bump.mjs

@@ -12,19 +12,17 @@
  */
 
 /**
- * Taking a newer version of a dependency, without reformatting the lockfile.
+ * Taking a newer version of a dependency.
  *
- * npm resolves the bump; this module's whole job is what npm does badly here.
- * Every repository in the constellation indents `package-lock.json` with four
- * spaces and prettier-ignores it, and npm rewrites it with two — so a
- * three-line version change arrives as a seventeen-thousand-line diff that no
- * reviewer can read past.
+ * npm does the resolution, and that is the point of the command: editing the
+ * three `version` / `resolved` / `integrity` lines by hand is correct only
+ * while the new version's dependency set is identical to the old one's, and
+ * nothing tells the author when it is not. npm is what knows.
  *
- * The alternative — editing the three `version` / `resolved` / `integrity`
- * lines by hand — is only correct while the new version's dependency set is
- * identical to the old one's, and nothing tells the author when it is not. npm
- * is what knows; so npm does the resolution and the indentation is restored
- * afterwards.
+ * npm writes `package-lock.json` with the indentation `package.json` uses, so
+ * a consumer whose two files agree sees only the lines that moved. Each file
+ * is written back with the indent it already carried, so a lockfile indented
+ * unlike its manifest keeps its own.
  */
 
 import fs from "node:fs";
@@ -121,8 +119,8 @@ export function lockedVersion(lock, name) {
  * Take the newest published version of one or more dependencies.
  *
  * npm performs the resolution — so a bump that changes the dependency set is
- * as correct as one that moves three lines — and both JSON files are restored
- * to the indentation they already used.
+ * as correct as one that moves three lines — and both JSON files are written
+ * back with the indentation they already used.
  *
  * @param {object} options - Options.
  * @param {string} options.rootDir - The repository root holding `package.json`.
@@ -196,9 +194,9 @@ export function bumpDependencies({ rootDir, packages, tag = "latest", check = fa
         rootDir,
     );
 
-    // Restore what npm reformatted. Both files, because npm rewrites the
-    // manifest too when a range has to move — which below 1.0 it always does,
-    // a caret there being locked to the minor.
+    // Hold each file to the indent it already carried. Both, because npm
+    // rewrites the manifest too when a range has to move — which below 1.0 it
+    // always does, a caret there being locked to the minor.
     const reindented = [];
     if (reindentJsonFile(lockPath, detectJsonIndent(lockText))) reindented.push(lockPath);
     if (reindentJsonFile(manifestPath, detectJsonIndent(manifestText))) {

package/engine/pdf-render.mjs

@@ -667,14 +667,22 @@ function renderLink(href, inner, ctx) {
  * ## The width class is the measure
  *
  * An image with no class is one column wide. That is `width: 100%` of whatever
- * container it is set in — the page today, and a column once the book is set in
- * two — so the ordinary case needs nothing but an ordinary block and stays
- * correct through the change.
- *
- * `.full-width` has to leave its column, and a block cannot: only a float
- * placed with `scope: "parent"` spans every column of the page. So a
- * full-width image is always placed, whether or not it states a `float:`, and
- * an image that states neither is left in the flow where it was written.
+ * container it is set in — a column of the two the body is set in — so the
+ * ordinary case needs nothing but an ordinary block, and lands exactly where it
+ * was written.
+ *
+ * `.full-width` has to leave its column, and only a float placed with
+ * `scope: "parent"` spans every column of a page. A float, though, is placed
+ * where the page has room rather than where it was written: it is set at the
+ * top of the page, above the prose that introduces it, and where the page is
+ * too far along to take it, on the next page — after prose that follows it in
+ * the note. Document order governs what follows an image, so
+ * {@link bookTypstPreamble}'s `book-figure` breaks the page first and places
+ * the figure at the top of the fresh one, where nothing is above it to displace
+ * it and nothing that follows it can print first.
+ *
+ * A `.full-width` image that **also states a `float:`** is asking for a float,
+ * and keeps one — deferral is the honest consequence of the request.
  *
  * ## A float occupies the measure
  *
@@ -712,8 +720,10 @@ function renderImage(token, ctx) {
     // In the flow where it was written: no class asking for the page, and no
     // position asking for the top or the bottom of the column.
     if (!float && scope === "column") return `\n${figure}\n\n`;
-    const align = float?.align ?? "top";
-    return `\n#place(${align}, float: true, scope: "${scope}", clearance: 0.7em)[\n${figure}\n]\n\n`;
+    // The page, in document order: a width class says how wide the picture is
+    // and not when it appears.
+    if (!float) return `\n#book-figure[\n${figure}\n]\n\n`;
+    return `\n#place(${float.align}, float: true, scope: "${scope}", clearance: 0.7em)[\n${figure}\n]\n\n`;
 }
 
 /**
@@ -904,6 +914,26 @@ export function bookTypstPreamble() {
             "  place(top + left)[#book-plate(kicker, title, banner, 9cm, body)]\n" +
             "  pagebreak()\n" +
             "}",
+        // A full-width figure spans the page in document order. Only a float
+        // spans every column, and a float is placed where the page has room
+        // rather than where it was written — at the top, above the prose that
+        // introduces it, or on the next page when this one is too far along.
+        // Breaking first puts it at the top of a page whose float region is
+        // empty, which is the one place it cannot be displaced. A picture
+        // taller than the page takes a page of its own, for the reason
+        // `book-wide` states.
+        //
+        // `measure` alone is stable here. A rule reading `here().position()`
+        // to keep the break for the cases that need it does not converge: the
+        // position decides the layout and the layout decides the position.
+        "#let book-figure(body) = context {\n" +
+            "  if measure(block(width: book-text-width)[#body]).height >= book-text-height * 0.88 {\n" +
+            "    page(columns: 1)[#body]\n" +
+            "  } else {\n" +
+            "    pagebreak(weak: true)\n" +
+            '    place(top, float: true, scope: "parent", clearance: 0.7em)[#body]\n' +
+            "  }\n" +
+            "}",
         // Wide content spans the page, and how it spans depends on how tall it
         // is: a float is unbreakable and silently overflows, so anything taller
         // than a page takes pages of its own instead.

package/manifest.mjs

@@ -94,6 +94,49 @@ export function normalizeRepoUrl(repository) {
     return url;
 }
 
+/**
+ * Where every HeroicLands package's homepage is served from.
+ *
+ * Stated once here and read by {@link packageHomepage}, so the origin a
+ * manifest advertises and the origin the configuration documents cannot come
+ * to disagree.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_ORIGIN = "https://www.heroiclands.org";
+
+/**
+ * A package's homepage — the page `url` sends a reader to.
+ *
+ * Derived from the content package rather than declared, because the address is
+ * already fixed: every package publishes an authored homepage at
+ * `<origin>/<contentPackage>/`, and the shared site-deploy workflow publishes
+ * it there. A declared copy would be a second spelling of a settled fact, free
+ * to drift — and the one that drifts is this one, because nothing fetches `url`
+ * the way Foundry fetches `manifest`, so a wrong value is never reported.
+ *
+ * The site's own `baseURL` says the same thing, and is deliberately not the
+ * source: it sits at `site/hugo.toml` in most repositories and `kb/hugo.toml`
+ * in the system, so reading it would mean the packaging half knowing where each
+ * repository keeps its site configuration.
+ *
+ * @param {string} contentPackage - The package's content-package name.
+ * @returns {string} The homepage URL, with its trailing slash.
+ * @throws {TypeError} When no name is given. Interpolating a missing one yields
+ *   `<origin>/undefined/`, a URL that resolves and is wrong — and nothing
+ *   fetches `url`, so it would be advertised for as long as nobody clicked it.
+ */
+export function packageHomepage(contentPackage) {
+    const name = String(contentPackage ?? "").trim();
+    if (!name) {
+        throw new TypeError(
+            "the configuration declares no `contentPackage`, so the manifest has " +
+                "no homepage to advertise.",
+        );
+    }
+    return `${HOMEPAGE_ORIGIN}/${name}/`;
+}
+
 /**
  * The addresses a Foundry manifest advertises.
  *
@@ -103,15 +146,23 @@ export function normalizeRepoUrl(repository) {
  * install at that release forever. `download` points at this exact version,
  * because that is the archive this manifest describes.
  *
+ * **`url` is the homepage, not the repository.** It is the Project Homepage
+ * link a reader follows from the package listing *before* installing anything,
+ * so it answers "what is this?" — which a page written for that question does
+ * and a source tree does not. `bugs`, `manifest` and `download` address release
+ * artefacts and stay on the repository that holds them.
+ *
  * @param {object} opts
  * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.homeUrl - The package's homepage, from
+ *   {@link packageHomepage}.
  * @param {string} opts.version - The version being built.
  * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
  * @returns {{url: string, bugs: string, manifest: string, download: string}}
  */
-export function releaseUrls({ repoUrl, version, artifact }) {
+export function releaseUrls({ repoUrl, homeUrl, version, artifact }) {
     return {
-        url: repoUrl,
+        url: homeUrl,
         bugs: `${repoUrl}/issues`,
         manifest: `${repoUrl}/releases/latest/download/${artifact}.json`,
         download: `${repoUrl}/releases/download/v${version}/${artifact}.zip`,
@@ -434,7 +485,12 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
         id: config.foundryPackage,
         version: packageJson.version,
         packs: manifestPacks(config),
-        ...releaseUrls({ repoUrl, version: packageJson.version, artifact }),
+        ...releaseUrls({
+            repoUrl,
+            homeUrl: packageHomepage(config.contentPackage),
+            version: packageJson.version,
+            artifact,
+        }),
     };
     if (config.compatibility) derived.compatibility = config.compatibility;
 
@@ -482,16 +538,14 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     // A flag rather than a top-level key because Foundry's manifest schema is
     // closed and `flags` is its declared extension point; an unknown key at the
     // top level is dropped by some readers and rejected by others.
-    if (config.contentPackage) {
-        merged.flags = {
-            ...(declared.flags ?? {}),
-            metadataUrl: metadataUrl({
-                repoUrl,
-                version: packageJson.version,
-                contentPackage: config.contentPackage,
-            }),
-        };
-    }
+    merged.flags = {
+        ...(declared.flags ?? {}),
+        metadataUrl: metadataUrl({
+            repoUrl,
+            version: packageJson.version,
+            contentPackage: config.contentPackage,
+        }),
+    };
 
     if (flags && Object.keys(flags).length) {
         merged.flags = { ...(merged.flags ?? declared.flags ?? {}) };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "21.2.0",
+    "version": "22.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/dependency-bump.d.mts

@@ -57,8 +57,8 @@ export function lockedVersion(lock: object, name: string): string | undefined;
  * Take the newest published version of one or more dependencies.
  *
  * npm performs the resolution — so a bump that changes the dependency set is
- * as correct as one that moves three lines — and both JSON files are restored
- * to the indentation they already used.
+ * as correct as one that moves three lines — and both JSON files are written
+ * back with the indentation they already used.
  *
  * @param {object} options - Options.
  * @param {string} options.rootDir - The repository root holding `package.json`.

package/types/manifest.d.mts

@@ -17,6 +17,28 @@
 export function normalizeRepoUrl(repository: string | {
     url?: string;
 }): string;
+/**
+ * A package's homepage — the page `url` sends a reader to.
+ *
+ * Derived from the content package rather than declared, because the address is
+ * already fixed: every package publishes an authored homepage at
+ * `<origin>/<contentPackage>/`, and the shared site-deploy workflow publishes
+ * it there. A declared copy would be a second spelling of a settled fact, free
+ * to drift — and the one that drifts is this one, because nothing fetches `url`
+ * the way Foundry fetches `manifest`, so a wrong value is never reported.
+ *
+ * The site's own `baseURL` says the same thing, and is deliberately not the
+ * source: it sits at `site/hugo.toml` in most repositories and `kb/hugo.toml`
+ * in the system, so reading it would mean the packaging half knowing where each
+ * repository keeps its site configuration.
+ *
+ * @param {string} contentPackage - The package's content-package name.
+ * @returns {string} The homepage URL, with its trailing slash.
+ * @throws {TypeError} When no name is given. Interpolating a missing one yields
+ *   `<origin>/undefined/`, a URL that resolves and is wrong — and nothing
+ *   fetches `url`, so it would be advertised for as long as nobody clicked it.
+ */
+export function packageHomepage(contentPackage: string): string;
 /**
  * The addresses a Foundry manifest advertises.
  *
@@ -26,14 +48,23 @@ export function normalizeRepoUrl(repository: string | {
  * install at that release forever. `download` points at this exact version,
  * because that is the archive this manifest describes.
  *
+ * **`url` is the homepage, not the repository.** It is the Project Homepage
+ * link a reader follows from the package listing *before* installing anything,
+ * so it answers "what is this?" — which a page written for that question does
+ * and a source tree does not. `bugs`, `manifest` and `download` address release
+ * artefacts and stay on the repository that holds them.
+ *
  * @param {object} opts
  * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.homeUrl - The package's homepage, from
+ *   {@link packageHomepage}.
  * @param {string} opts.version - The version being built.
  * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
  * @returns {{url: string, bugs: string, manifest: string, download: string}}
  */
-export function releaseUrls({ repoUrl, version, artifact }: {
+export function releaseUrls({ repoUrl, homeUrl, version, artifact }: {
     repoUrl: string;
+    homeUrl: string;
     version: string;
     artifact: "system" | "module";
 }): {
@@ -223,6 +254,16 @@ export function writeManifest({ config, packageJson, artifact, outDir, flags, co
  * convention this project is free to choose.
  */
 export const ARTIFACTS: readonly string[];
+/**
+ * Where every HeroicLands package's homepage is served from.
+ *
+ * Stated once here and read by {@link packageHomepage}, so the origin a
+ * manifest advertises and the origin the configuration documents cannot come
+ * to disagree.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_ORIGIN: string;
 /**
  * Relationship keys that direct the **build**, rather than describe the
  * package.