@heroiclands/package-build 22.15.0 → 22.16.0

package/docs/guides/book.md

@@ -0,0 +1,153 @@
+---
+shortcode: guidesbook
+name: { full: "Build a PDF book" }
+type: doc
+subType: howto
+---
+
+# Build a PDF book
+
+`package-build pdf` selects notes from a content package and sets them as a
+PDF. The website can publish the whole content tree; the book follows the
+ordered document tree named by `pdf.document`. This makes the book's contents
+an editorial choice. A note outside every selection remains in the content
+package and on its site, but it has no book entry.
+
+The build writes Typst source under `pdf.out` and invokes the Typst binary to
+produce the PDF. Typst must be available on `PATH`, or named with `pdf.binary`.
+The [command reference](../commands.md) lists the CLI options; the
+[configuration reference](../configuration.md) lists the `pdf` keys.
+
+## Declare the book
+
+Give the book a title and document tree:
+
+```yaml
+pdf:
+  title: The Setting Guide
+  document: book.yaml
+  out: build/pdf
+```
+
+A tree containing only a homepage has no content pages for a book. With no
+`pdf` block or no content tree, the command has nothing to build. `pdf.title`
+and `pdf.document` are required together when `pdf` is declared.
+
+`book.yaml` contains an ordered list of sections. Each section contains prose
+files, note filters, or nested sections:
+
+```yaml
+contents:
+  - sectionName: Introduction
+    contents:
+      - file: prose/introduction.md
+  - sectionName: Places
+    contents:
+      - filter: "type = 'place'"
+      - sectionName: Settlements
+        contents:
+          - filter: "type = 'place' AND subType = 'settlement'"
+```
+
+The build keeps the order of prose and subsections as written. Notes selected
+by a filter are ordered by their folded display name. The filter is a SQL
+`WHERE` clause over this package's `notes` table; the build supplies
+`SELECT * FROM notes`. A filter cannot choose another package's notes. It is
+an error when a filter selects no printable note, while notes that no filter
+selects are simply outside this volume. A note selected more than once prints
+at each selected position; inbound book links reach its first occurrence.
+
+The document tree can include a section with prose and no selected notes, for
+example a preface. Empty sections do not print. `pdf.front` lists Markdown
+files placed before the book's contents.
+
+## Control a section's page
+
+Sections can provide a running footer and page presentation:
+
+```yaml
+contents:
+  - sectionName: Places
+    footer: The Atlas
+    page:
+      banner: assets/images/banners/atlas.webp
+      kicker: The Atlas
+      columns: 2
+    contents:
+      - filter: "type = 'place'"
+```
+
+`page.columns` accepts one through four columns. The ordinary page uses two.
+`page.banner` names an image the package ships, and `page.kicker` supplies the
+line above an entry title. A subsection inherits presentation from its
+ancestors; a declared `page` block replaces the inherited block as a whole,
+so it states every page option that subsection wants. A section without a
+banner still has a title plate. A banner path that cannot be read is a
+finding.
+
+Each section and each selected entry starts on its own page. The PDF has a
+contents page and an outline for section and entry navigation. A note's
+`description` appears as an epigraph when present. Wider tables span both
+columns; an uncaptioned wide table starts on a new page so it stays after its
+introduction. A captioned wide table may float to the page top, and its numbered
+caption stays with it. A table too tall for one page takes pages of its own.
+Caption numbers run through the whole book in reading order. Maps attached
+to selected places use landscape pages after those entries. Regional, theatre
+of the mind, battle, and local map backgrounds also print on landscape pages.
+Battle and local maps print each Scene level's background on its own page.
+The
+[content format](../content-format.md) describes image sizes, floats, and
+links as they are authored in notes.
+
+The book stages raster art at up to 300 dpi for its largest printed use.
+Ordinary images fit their column, full-width images fit the page's text width,
+and map backgrounds fit the landscape map area. An image smaller than that
+target keeps its authored pixels and still fills its allotted space on the
+page. SVG art stays vector. The build never changes authored image files.
+
+## Set fonts and icon fonts
+
+The build supplies its default book fonts and searches its own font directory
+for them. A package can choose families and add a font directory:
+
+```yaml
+pdf:
+  title: The Setting Guide
+  document: book.yaml
+  fonts:
+    serif: Libertinus Serif
+    sans: Libertinus Sans
+    mono: DejaVu Sans Mono
+    path: assets/fonts
+  iconFonts:
+    fontawesome: assets/fonts/fa-solid-900.ttf
+```
+
+The `fonts` values are family names; `fonts.path` is a directory to search.
+`iconFonts` maps an icon family to the file carrying its glyphs. The Typst
+invocation ignores system-installed fonts, so a machine's font collection
+does not silently change the book. Check a chosen font's coverage for the
+characters in the notes: Typst can substitute a face and still exit
+successfully. The [content format](../content-format.md) covers icon names
+written in notes; the [configuration reference](../configuration.md) covers
+the font registry.
+
+## Build and inspect
+
+```bash
+package-build pdf
+package-build pdf --no-compile
+package-build pdf --out build/book
+```
+
+`--no-compile` emits the Typst source and staged images without invoking
+Typst. The source and assets sit under the output directory, because Typst
+reads paths relative to its compilation root. An authored image from this
+package can be staged into the book. A remote image or one owned by another
+package cannot be read by this build; the build reports that limitation.
+
+Wikilinks between selected notes become internal PDF destinations. A link to
+a note outside the selection or another package remains a web address.
+Anchors on headings are scoped to their entries, so two entries can use the
+same heading anchor. The build reports an unresolved destination while
+keeping the source available for inspection.

package/docs/guides/e2e.md

@@ -0,0 +1,143 @@
+---
+shortcode: guidese2e
+name: { full: "Test a package in Foundry" }
+type: doc
+subType: howto
+---
+
+# Test a package in Foundry
+
+`package-build e2e` serves a staged package in a disposable Foundry world and
+hands control to the repository's browser suite. The harness owns deployment,
+world seeding, container lifecycle, and the wait for an active world. The
+repository chooses the suite command, build targets, and result files. See the
+[e2e command](../commands.md#package-build-e2e-action) and
+[configuration reference](../configuration.md#packagebuilde2e) for the full
+contract.
+
+## Configure the suite
+
+Declare a headless runner, and optionally an interactive one. The suite
+command is an argument array, so each item is one process argument:
+
+```yaml
+packageBuild:
+  e2e:
+    suite:
+      run: [npx, cypress, run]
+      open: [npx, cypress, open]
+    results: [cypress/results]
+    build:
+      code: { script: build:code, recreate: true }
+      packs: build:db
+```
+
+Here `build:code` and `build:db` are scripts in the consuming repository's
+`package.json`. The `build` mapping is ordered: a `fast` run executes targets
+in that order even when they are requested in another order. Mark a target
+`recreate: true` when it changes something Foundry reads only when the world
+starts, such as the manifest. Configure the runner to write to the paths in
+`results`; the example runner writes to `cypress/results`. A zero exit with no
+fresh result in those paths is reported as
+a failed run; the harness also checks that the runner executable remains
+installed through the run.
+
+The optional `world`, `gm`, and `documents` mappings set the disposable
+world's identity, GM credentials, and seeded collections. With no override,
+the world is named from the package and includes a GM and active scene. A
+module package is enabled in that world. The harness does not supply a
+Cypress test suite; `suite.run` and `suite.open` name the repository's own.
+
+## Keep local settings in `.env.local`
+
+Create `.env.local` at the repository root with a data directory reserved for
+this harness and a Foundry license available to the test container:
+
+```dotenv
+FOUNDRYVTT_TEST_DATA=/path/to/isolated-foundry-test-data
+FOUNDRYVTT_TEST_LICENSE_KEY=replace-with-test-license-key
+FOUNDRYVTT_TEST_PORT=30003
+# FOUNDRYVTT_TEST_VERSION=14.367
+```
+
+Keep `.env.local` ignored by git; it holds machine-specific paths and real
+credentials. `package-build init` creates this basic `.gitignore` skeleton:
+
+```gitignore
+node_modules
+/build/
+/nogit/
+/.env*
+/.DS_Store
+/.claude/
+*.tgz
+```
+
+`/.env*` covers `.env.local`, `.env`, and other local environment files.
+`/build/` keeps generated indexes, packs, site files, and books out of commits;
+`/nogit/` reserves local scratch. The CLI reads `.env.local` from the
+configured repository root before `.env`. Values already set in the shell take precedence over both files, and
+`.env.local` takes precedence over `.env`. A separate git worktree needs its
+own `.env.local` because that ignored file is not copied with the branch.
+The test data path is a Foundry data root, beneath which the harness creates
+`Data/worlds/` and installs the package. Use an absolute path; `~` and shell
+variables are not expanded in `.env.local`. Set `FOUNDRYVTT_TEST_VERSION` to
+select a specific Foundry build for routine runs. With the local settings in
+place, seed the world:
+
+```bash
+package-build e2e seed
+```
+
+The seed command writes the disposable world beneath that data root. It
+replaces the seeded world with the same ID each time. The harness refuses a
+root shared with another Foundry stage, so test seeding cannot overwrite a
+development or production world.
+
+## Run the whole suite
+
+Build the staged package first, then use one of the full-run modes:
+
+```bash
+package-build e2e run
+package-build e2e open
+```
+
+`run` deploys the stage, reseeds the world, recreates the container, waits for
+the world to become active, runs the headless suite, and stops the container.
+`open` uses the same setup and launches `suite.open`; it leaves the server up
+for interactive testing. Arguments after `--` are passed to the suite, for
+example `package-build e2e run -- --browser chrome`. A port answering is not
+enough: the harness waits until Foundry's join page shows the world is active.
+
+## Iterate without reseeding
+
+`fast` rebuilds declared targets, redeploys the full stage, cycles the world,
+waits for it, and runs the headless suite:
+
+```bash
+package-build e2e fast
+package-build e2e fast --build=packs -- --spec cypress/e2e/items.cy.js
+package-build e2e fast --build=none --no-run
+```
+
+`--build=` takes declared target names, a comma-separated subset, `all`, or
+`none`. `--no-run` updates the environment without launching the suite.
+`--recreate` forces a fresh container even when the selected targets do not
+require it. This mode keeps the existing seeded world's Foundry generation;
+use a full run when changing the Foundry build.
+
+## Verify another Foundry build
+
+Name an exact Foundry build for a compatibility sweep:
+
+```bash
+package-build e2e sweep 14.367
+```
+
+The sweep runs the full reseeded suite with that build for this invocation
+only. It does not change the repository's compatibility declaration. A bare
+major version or moving tag is refused, because the result must name the
+build actually tested. A passing sweep provides evidence for choosing a
+new `compatibility.verified` value; a routine run exercises the pinned
+minimum build.

package/docs/guides/icons.md

@@ -0,0 +1,126 @@
+---
+shortcode: guidesicons
+name: { full: "Icons and artwork" }
+type: doc
+subType: howto
+---
+
+# Icons and artwork
+
+Content uses two kinds of icons. An **asset icon** is an image file with an
+address, suitable for a sheet portrait, token, or embedded picture. An **inline
+icon** is a named font glyph in prose, such as the symbol beside an interface
+control. They have different sources and different authoring syntax.
+
+The [content format](../content-format.md) defines addresses, art slots, and
+image embeds. The [configuration reference](../configuration.md) defines the
+icon registry and PDF font settings.
+
+## Give an image an address
+
+Put a small image under `assets/icons/` and use its filename without the
+extension as its shortcode. For example,
+`assets/icons/tools/anvil.svg` has the address
+`<package>-none-icon-anvil`. Directories beneath `assets/icons/` do not enter
+the address, so filenames must be unique across that root. Larger illustrations
+belong under `assets/images/` and have type `image`. Both types can be used in
+art slots, but a bare value takes the slot's default type.
+
+```yaml
+shortcode: smith
+name: { full: The Smith }
+type: being
+subType: character
+data:
+  icon: anvil
+  tokenIcon: image-smith-token
+```
+
+Here `data.icon` resolves an `icon` asset and `data.tokenIcon` resolves an
+`image` asset. A full address, such as `sohl-none-image-smith-token`, names
+another package when that package is available to the build. `data.icon` and
+`data.tokenIcon` default to the `icon` type; `data.bgImage` and `data.banner`
+default to `image`. An explicit `image-` or `icon-` type works in any of the
+four slots. A pathname with slashes or an extension is not an art-slot address.
+
+| Art slot         | Its use                                         |
+| ---------------- | ----------------------------------------------- |
+| `data.icon`      | Profile art on a compiled Actor or Item         |
+| `data.tokenIcon` | Actor token art; follows `data.icon` when unset |
+| `data.bgImage`   | Background of a map Scene                       |
+| `data.banner`    | Page hero image for the site                    |
+
+An Item without `data.icon` uses its builder's configured default art. An
+Actor without `data.icon` uses its compiled default art. Write `data.icon`
+when the note needs a particular image. A portrait within the prose is an
+image embed, for example `![[image-smith-portrait|The smith]]{size=medium}`;
+it does not set a document's profile art. The
+[art-slot reference](../reference/format-details.md#the-four-art-slots) gives each
+slot's type and document destination.
+
+## Write an inline icon in prose
+
+Declare the glyph vocabulary in `package-build.config.yaml` or a separate YAML
+file named by `icons:`. The registry maps a stable content name to a font
+family, glyph name, style, and accessible label:
+
+```yaml
+icons:
+  families:
+    fontawesome: { class: fa, styles: [solid, regular], describe: Font Awesome }
+  icons:
+    warning: { style: solid, icon: triangle-exclamation, label: Warning }
+```
+
+With one family, each icon uses it automatically. With several families, set
+`defaultFamily` or give an entry `family`. The package supplies the stylesheet
+and font that these declarations name; an empty registry supplies no glyphs.
+The registry key uses lowercase letters, digits, and hyphens. This name is a glyph key in the local registry, not a content Address.
+
+```markdown
+Check the :icon warning: marker before opening the gate.
+
+The larger :icon warning:{size=2x} marks a hazardous passage.
+```
+
+The `size` attribute is a closed list: `lg`, `xl`, `2x`, and `3x`. These values
+enlarge the glyph relative to running text on the web and in the PDF. The
+glyph name must be declared in this package's `icons` registry; there is no
+global closed list of names. An unknown name remains visible as literal
+`:icon name:` text and produces a warning at the note's position. Invalid
+attributes produce errors. In HTML, a known name renders as an icon element
+with an accessible label.
+
+For a PDF, point `pdf.iconFonts` at the font file for each family used in the
+book:
+
+```yaml
+pdf:
+  title: The Setting Guide
+  document: book.yaml
+  iconFonts:
+    fontawesome: assets/fonts/fa-solid-900.ttf
+```
+
+The book build reads glyphs from those font files. Its findings identify a
+font that cannot be read or a glyph that cannot be resolved. The
+[book guide](book.md) covers book selection and font configuration.
+
+## Check the result
+
+Run the content lint and build the surfaces the package publishes:
+
+```bash
+package-build lint
+package-build package compile
+package-build site
+package-build pdf --no-compile
+```
+
+The content index assigns addresses to image assets. The lint reports unknown
+inline names and invalid art addresses. A documentation package has no packs,
+so it skips `package compile`. Inspect a compiled Actor or Item's
+`img`, an Actor's `prototypeToken.texture.src`, and a map's `background.src`
+when checking document art. Inspect the site page and emitted Typst source for
+inline icons and banners. The [command reference](../commands.md) gives the
+available build and lint options.

package/docs/guides/localization.md

@@ -0,0 +1,120 @@
+---
+shortcode: guideslocalization
+name: { full: "Localize a Foundry package" }
+type: doc
+subType: howto
+---
+
+# Localize a Foundry package
+
+A Foundry package ships translation files under `lang/` and lists them in its
+generated manifest. The language commands check three different things: the
+file can load in Foundry, every referenced key exists, and templates contain no
+untranslated user-visible text. The [command reference](../commands.md) gives
+their options and exit behavior; [configuration](../configuration.md#packagebuildlang)
+defines the scan paths and exceptions.
+
+## Declare a language
+
+Put a JSON object in `lang/en.json`. Flat dotted keys make the path each call
+site uses visible:
+
+```json
+{
+  "EXAMPLE.Actor.greeting": "Well met, {name}.",
+  "EXAMPLE.Skill.label": "Skill"
+}
+```
+
+Foundry's formatted localization uses single-brace placeholders, such as
+`{name}`. A key cannot be both a value and a prefix: declaring both
+`EXAMPLE.Skill` and `EXAMPLE.Skill.label` makes Foundry's object expansion
+fail. Keep a key segment to letters, digits, underscores, and hyphens. The
+`lang check` command reports invalid JSON, a non-object top level, collisions,
+invalid segments, and malformed placeholders.
+
+Include the language directory in `packageBuild.assets` and declare its file
+under `packageBuild.manifest.languages`:
+
+```yaml
+packageBuild:
+  assets:
+    - { from: lang, to: lang }
+  manifest:
+    languages:
+      - { lang: en, name: English, path: lang/en.json }
+```
+
+The [manifest configuration](../configuration.md#packagebuildmanifest) covers
+the rest of the manifest declaration. `package-build manifest` writes the
+Foundry manifest from that configuration.
+
+## Check that the file loads
+
+```bash
+package-build lang check
+```
+
+This command reads every file matching `packageBuild.lang.sources`, which
+defaults to `lang/*.json`. It fails when the glob finds nothing. A content-only
+package can use this check without configuring code or template scans.
+
+## Check the keys used by code and templates
+
+For packages with scripts or Handlebars templates, point the scan at the
+files that reference localization keys:
+
+```yaml
+packageBuild:
+  lang:
+    primary: lang/en.json
+    scripts: "src/**/*.{ts,mjs}"
+    templates: "templates/**/*.hbs"
+```
+
+```bash
+package-build lang coverage
+package-build lang coverage --unused
+package-build lang hardcoded
+```
+
+`coverage` compares keys in the primary file with references extracted from
+scripts and templates. A referenced key that is absent fails the check. An
+unreferenced declared key is advisory, because runtime code may construct its
+name. `--unused` prints every advisory rather than a short preview. The scan
+recognizes literal references and dynamic key shapes, including a key such as
+`` `EXAMPLE.Calendar.Month.${index}.label` ``. It derives key roots from the
+primary file, or uses `packageBuild.lang.keyRoots` when a root has no declared
+key to derive it from.
+
+`hardcoded` checks user-visible template text and checks that each template
+compiles. It requires at least one template matching its configured glob;
+`coverage` requires at least one matching script or template. A package with
+no such files runs `lang check` alone.
+
+## Account for generated keys and intentional literals
+
+When a repository generates localization keys by its own convention, set
+`packageBuild.lang.references` to a module exporting
+`references(context) -> ReferenceSet`. Its `keys`, `namespaces`, `patterns`,
+and `findings` join the built-in scan before coverage analysis. This lets the
+package describe dynamic references without making an unreferenced key look
+used merely because it has the right prefix. The [API reference](../api.md)
+defines the `ReferenceSet` fields.
+
+Use `packageBuild.lang.retained` for a declared key prefix that is intentionally
+not reached by the scan. Use `packageBuild.lang.allow` for user-visible text in
+a template that is deliberately literal. Each entry includes a reason:
+
+```yaml
+packageBuild:
+  lang:
+    retained:
+      - { prefix: EXAMPLE.ExternalNames, reason: Read from saved documents }
+    allow:
+      - { literal: d20, reason: Dice notation is the same in every language }
+```
+
+Review coverage and hardcoded findings after changing a template or a
+translation file. The checks are read-only; the authored JSON and templates
+remain the source of the package's text.