@heroiclands/package-build 23.1.0 → 23.2.0

package/sohl/kb-passes.mjs

@@ -51,9 +51,9 @@ import log from "loglevel";
  * code spans rather than refuse to build.
  *
  * **Configuring one that cannot be used is a defect, and it fails the build.**
- * A missing file, a malformed one, a permissions error and a path typo used to
+ * A missing file, a malformed one, a permissions error and a path typo would
  * be indistinguishable from each other *and* from a correctly configured build
- * with no symbols: a bare `catch` returned `{}` for all five. Nothing then
+ * with no symbols, were a bare `catch` to return `{}` for all of them. Nothing then
  * compares an emitted page against what its source asked for, so the first
  * observer of a broken map was a reader who clicked nothing, because every
  * `{@link}` on the published site had quietly become a code span.
@@ -112,7 +112,7 @@ function readSymbolMap(file, repoRoot) {
 
     // Reported because a map that loaded and a map that loaded empty are
     // otherwise indistinguishable without reading the emitted HTML — and an
-    // empty one degrades every tag exactly as a missing one used to.
+    // empty one degrades every tag exactly as a missing one does.
     log.info(`resolved ${Object.keys(parsed).length} API symbols from ${file}`);
     return parsed;
 }

package/types/container.d.mts

@@ -91,10 +91,12 @@ export function resolveFoundryVersion(stage: string, { env, stages, compatibilit
 /**
  * The image a run uses.
  *
- * `FOUNDRYVTT_CONTAINER_IMAGE` wins, then `packageBuild.container.image`, then
- * felddy's major tag for whichever version the package already implies — the
- * pinned build, or failing that the compatibility floor. Only a package that
- * claims neither floats.
+ * `FOUNDRYVTT_CONTAINER_IMAGE` wins, then `packageBuild.container.image`. A
+ * pinned exact build takes felddy's tag for that build: each image installs its
+ * own build by default and warns that a different `FOUNDRY_VERSION` "may not
+ * function properly". Otherwise felddy's major tag for whichever version the
+ * package implies — the pin, or failing that the compatibility floor. Only a
+ * package that claims neither floats.
  *
  * @param {object} [opts]
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
@@ -162,6 +164,37 @@ export function resolveDataRoot(stage: string, { env }?: {
  * @returns {[string, string][]} The pairs to pass through.
  */
 export function passthroughEnv(env?: NodeJS.ProcessEnv): [string, string][];
+/**
+ * Whether the image has to sign in to foundryvtt.com to start.
+ *
+ * Given `FOUNDRY_USERNAME` and `FOUNDRY_PASSWORD`, the image signs in and asks
+ * for a download URL on every container it creates, even when the release is
+ * already in its cache. Each of those is a request foundryvtt.com rate-limits,
+ * and one refused with HTTP 429 stops the container before Foundry starts. The
+ * account serves two purposes only: downloading a release that is not cached,
+ * and fetching a licence key for an unlicensed data root. When neither applies
+ * the account is withheld, and the release installs from the cache with no
+ * network request.
+ *
+ * The image caches `foundryvtt-<version>.zip` in the mounted cache, or in
+ * `container_cache` beneath the data root when no cache is mounted.
+ *
+ * @param {object} opts
+ * @param {string|null} [opts.cacheDir] - The host cache mounted into the container.
+ * @param {string} opts.dataRoot - The host data root mounted at `/data`.
+ * @param {string|null} [opts.version] - The pinned build; with none, the
+ *   archive's name is unknown.
+ * @param {string|null} [opts.licenseKey] - The licence key the image is given.
+ * @param {(file: string) => boolean} [opts.fileExists] - Replaceable for tests.
+ * @returns {boolean} Whether to pass the account through.
+ */
+export function needsFoundryAccount({ cacheDir, dataRoot, version, licenseKey, fileExists, }: {
+    cacheDir?: string | null | undefined;
+    dataRoot: string;
+    version?: string | null | undefined;
+    licenseKey?: string | null | undefined;
+    fileExists?: ((file: string) => boolean) | undefined;
+}): boolean;
 /**
  * The full `docker run` argument vector for a stage's container.
  *
@@ -179,9 +212,16 @@ export function passthroughEnv(env?: NodeJS.ProcessEnv): [string, string][];
  * @param {string|null} [opts.version] - Exact build to pin.
  * @param {string|null} [opts.world] - World to auto-launch; `""` forces none.
  * @param {string|null} [opts.licenseKey] - Dedicated licence key.
+ * @param {boolean} [opts.account] - Whether to pass `FOUNDRY_USERNAME` and
+ *   `FOUNDRY_PASSWORD` through; see {@link needsFoundryAccount}.
+ * @param {string|null} [opts.user] - `--user` value to run the container as.
+ *   `felddy/foundryvtt` runs Foundry as user 1000 and ignores `FOUNDRY_UID` and
+ *   `FOUNDRY_GID`; under rootless Docker, container root is the host user, so
+ *   `0:0` makes every file under the data root theirs. Blank or `null` leaves
+ *   the image's own user.
  * @returns {string[]} Arguments after `docker`.
  */
-export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, }: {
+export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, account, user, }: {
     name: string;
     image: string;
     port: number;
@@ -191,6 +231,8 @@ export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, vers
     version?: string | null | undefined;
     world?: string | null | undefined;
     licenseKey?: string | null | undefined;
+    account?: boolean | undefined;
+    user?: string | null | undefined;
 }): string[];
 /**
  * Run the `docker` CLI, inheriting stdio.
@@ -200,6 +242,70 @@ export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, vers
  * @throws {Error} When `docker` is not on `PATH`.
  */
 export function runDocker(args: string[]): number;
+/**
+ * The `docker run` argument vector for a short-lived container that runs a
+ * shell script against a stage's data root.
+ *
+ * It uses the stage's own image and mounts the data root at `/data`, so the
+ * script sees files exactly as the Foundry container does. Under rootless
+ * Docker, only the container's user namespace can unlink what the container's
+ * user wrote, and only it can hand files to that user.
+ *
+ * @param {object} opts
+ * @param {string} opts.image - Image reference.
+ * @param {string} opts.dataRoot - Host directory to mount at `/data`.
+ * @param {string} opts.script - A `sh` script; `$1`, `$2` … are `args`.
+ * @param {string[]} [opts.args] - Positional arguments for the script.
+ * @param {string|null} [opts.user] - `--user` value; `null` runs as the image's
+ *   own user.
+ * @returns {string[]} Arguments after `docker`.
+ */
+export function dataRootScriptArgs({ image, dataRoot, script, args, user }: {
+    image: string;
+    dataRoot: string;
+    script: string;
+    args?: string[] | undefined;
+    user?: string | null | undefined;
+}): string[];
+/**
+ * Run a shell script against a stage's data root in a throwaway container.
+ *
+ * @param {object} opts - As for {@link dataRootScriptArgs}.
+ * @returns {string} The script's standard output.
+ * @throws {Error} When `docker` is missing or the script exits non-zero.
+ */
+export function runDataRootScript(opts: object): string;
+/**
+ * A remover for trees under a stage's data root that the container's user
+ * owns, run as root in a throwaway container on that data root — the same
+ * mechanism that hands an end-to-end install to the container's user.
+ *
+ * @param {object} opts
+ * @param {ResolvedContainer} opts.container - The stage's container.
+ * @param {(opts: object) => string} [opts.runScript] - Throwaway-container runner.
+ * @returns {(tree: string, where: {dataRoot: string}) => void} Removes one tree.
+ */
+export function containerTreeRemover({ container, runScript }: {
+    container: ResolvedContainer;
+    runScript?: ((opts: object) => string) | undefined;
+}): (tree: string, where: {
+    dataRoot: string;
+}) => void;
+/**
+ * The command {@link containerTreeRemover} runs, written out for a person to
+ * paste when the deploy could not run it.
+ *
+ * @param {object} opts
+ * @param {string} opts.image - Image reference.
+ * @param {string} opts.dataRoot - Host directory mounted at `/data`.
+ * @param {string} opts.tree - The tree to remove, beneath the data root.
+ * @returns {string} A `docker run` command line.
+ */
+export function containerRemovalCommand({ image, dataRoot, tree }: {
+    image: string;
+    dataRoot: string;
+    tree: string;
+}): string;
 /**
  * Run the `docker` CLI and capture its output, tolerating failure.
  *
@@ -255,6 +361,7 @@ export function clearStaleLock(dataRoot: string, log?: (message: string) => void
  * @property {string|null} world
  * @property {string|null} licenseKey
  * @property {string|null} cacheDir
+ * @property {string|null} user - From `FOUNDRYVTT_CONTAINER_USER`.
  */
 /**
  * Resolve a stage's container settings.
@@ -367,4 +474,8 @@ export type ResolvedContainer = {
     world: string | null;
     licenseKey: string | null;
     cacheDir: string | null;
+    /**
+     * - From `FOUNDRYVTT_CONTAINER_USER`.
+     */
+    user: string | null;
 };

package/types/content-config.d.mts

@@ -87,28 +87,6 @@ export namespace DEFAULT_PATHS {
  * @satisfies {readonly PackDocumentType[]}
  */
 export const PACK_DOCUMENT_TYPES: readonly ["Actor", "Adventure", "Item", "JournalEntry", "Macro", "Scene"];
-/**
- * Address-scheme keys a configuration may no longer declare.
- *
- * A retired key has exactly two possible fates, and only one of them is honest
- * — the same reasoning `engine/retired-fields.mjs` applies to a retired
- * frontmatter field. Left honoured, it keeps doing whatever it did, which is
- * why it was retired. Left *ignored*, it reads to its author as though it still
- * works: the configuration says one thing and the build does another, and
- * nothing says so. This module has no third option, because it has no warning
- * channel — every finding goes through `fail()`, which throws. So a retired
- * key is **refused**, at the line it was written on, with a message that says
- * the mechanism is gone rather than naming a value to correct.
- *
- * **`landing` is one such key.** It named which note addressed a whole section
- * rather than a page within one — a *landing page*, which therefore had no slug
- * of its own. There are no sections to address: a section is a Hugo content
- * directory the note format does not carry, a page's address names no
- * directory, and so no note lands anything.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
 /**
  * A repository's address scheme, with the defaults an unconfigured one gets.
  *
@@ -119,9 +97,7 @@ export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
  * knowledge, held in `PACKAGE_BASE` (`engine/content-address.mjs`) and prefixed at
  * resolve time, so it is never recorded here.
  *
- * It is the whole scheme: `landing`, the key that named which note addressed a
- * whole section, is retired with the sections themselves — see
- * {@link RETIRED_ADDRESS_KEYS}.
+ * It is the whole scheme.
  */
 export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
@@ -136,6 +112,16 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
  * @type {readonly string[]}
  */
 export const RELATIONSHIP_KEYS: readonly string[];
+/**
+ * The closed list a person's `role` in `authors` is drawn from.
+ *
+ * One role per entry: a person with two roles is listed twice. Printed in
+ * title case after the name on a book's title page; the Foundry manifest,
+ * whose author schema has no role, never receives it.
+ *
+ * @type {readonly string[]}
+ */
+export const AUTHOR_ROLES: readonly string[];
 /**
  * How the loader hands {@link defineConfig} the system version it resolved.
  *
@@ -164,6 +150,44 @@ export const DERIVED_SYSTEM_VERSION: symbol;
  * @type {Readonly<Record<string, string>>}
  */
 export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
+/**
+ * One declared book, resolved.
+ */
+export type ResolvedPdfBook = {
+    /**
+     * Its name on the command line, `--book <id>`.
+     */
+    id: string;
+    title: string;
+    /**
+     * `""` when none is declared.
+     */
+    subtitle: string;
+    /**
+     * Absolute; `""` when none is declared.
+     * Whether the file exists is checked when the
+     * book is built, not here.
+     */
+    coverImage: string;
+    /**
+     * Absolute paths of the front matter.
+     */
+    front: readonly string[];
+    /**
+     * The file stem; the version is appended.
+     */
+    out: string;
+    /**
+     * The tree written inline, or
+     * `null` when `document` names a file.
+     */
+    contents: readonly object[] | null;
+    /**
+     * Absolute path of the tree's file, or `""`
+     * when the tree is written inline.
+     */
+    document: string;
+};
 export type PackageKind = "systems" | "modules" | "documentation";
 export type PackDocumentType = "Actor" | "Adventure" | "Item" | "JournalEntry" | "Macro" | "Scene";
 /**
@@ -573,6 +597,26 @@ export type ItemRegistrySpec = {
      */
     builders: Record<string, ItemBuilderEntry>;
 };
+/**
+ * One person in the top-level `authors` list.
+ */
+export type AuthorSpec = {
+    /**
+     * As printed.
+     */
+    name: string;
+    email?: string | undefined;
+    url?: string | undefined;
+    /**
+     * A Discord handle, as Foundry's author schema
+     *   carries one.
+     */
+    discord?: string | undefined;
+    /**
+     * One of {@link AUTHOR_ROLES}.
+     */
+    role?: string | undefined;
+};
 /**
  * The configuration a consumer writes.
  */
@@ -606,14 +650,12 @@ export type ContentBuildConfigInput = {
      */
     homepage?: string | undefined;
     /**
-     * `package.json`'s own `author`, in
-     * either of npm's forms.
+     * The people who made the
+     *        package. The Foundry manifest's
+     *        `authors` and the site's byline
+     *        are generated from it.
      */
-    author?: string | {
-        name: string;
-        email?: string;
-        url?: string;
-    } | undefined;
+    authors?: AuthorSpec[] | undefined;
     /**
      * Whether the package is a system, a
      * module, or documentation — the kind
@@ -720,9 +762,15 @@ export type ContentBuildConfig = {
      */
     homepage: string | null;
     /**
-     *                                     `package.json`'s own `author`, normalised
-     *                                     from either of npm's forms; `null` when
-     *                                     the package declares none.
+     * The people who made
+     * the package, in the order declared; `[]`
+     * when none are.
+     */
+    authors: readonly Readonly<AuthorSpec>[];
+    /**
+     *                                     Derived: the first of `authors`, in npm's
+     *                                     `author` shape — the site's byline.
+     *                                     `null` when no author is declared.
      */
     author: Readonly<{
         name: string;

package/types/deploy.d.mts

@@ -85,9 +85,17 @@ export function buildConnection(stageUpper: string, remote: {
  *
  * @param {string} srcAbs - The staged tree.
  * @param {string} destDir - Where the package installs.
- * @returns {Promise<void>}
+ * @param {object} [opts]
+ * @param {(tree: string) => void|Promise<void>} [opts.removeTree] - Removes a
+ *   previous tree the host user is refused permission to remove.
+ * @returns {Promise<{leftovers: LeftoverTree[]}>} The previous trees that
+ *   could not be removed; the new one is installed either way.
  */
-export function deployLocal(srcAbs: string, destDir: string): Promise<void>;
+export function deployLocal(srcAbs: string, destDir: string, { removeTree }?: {
+    removeTree?: ((tree: string) => void | Promise<void>) | undefined;
+}): Promise<{
+    leftovers: LeftoverTree[];
+}>;
 /**
  * Mirror the staged build into a remote directory over SFTP, with the same
  * staged swap {@link deployLocal} performs.
@@ -100,11 +108,14 @@ export function deployLocal(srcAbs: string, destDir: string): Promise<void>;
  * @param {string} remoteDir - Where the package installs on the host.
  * @param {object} [opts]
  * @param {(uploaded: string) => void} [opts.onUpload] - Per-file progress.
- * @returns {Promise<void>}
+ * @returns {Promise<{leftovers: LeftoverTree[]}>} The previous tree when it
+ *   could not be removed; the new one is installed either way.
  */
 export function deployRemote(conn: object, srcAbs: string, remoteDir: string, { onUpload }?: {
     onUpload?: ((uploaded: string) => void) | undefined;
-}): Promise<void>;
+}): Promise<{
+    leftovers: LeftoverTree[];
+}>;
 /**
  * Deploy a staged package to one stage, choosing the transport from the
  * configured destination.
@@ -117,10 +128,13 @@ export function deployRemote(conn: object, srcAbs: string, remoteDir: string, {
  * @param {NodeJS.ProcessEnv} [opts.env] - The environment to read.
  * @param {string} [opts.prefix] - Fallback variable prefix for SFTP overrides.
  * @param {(message: string) => void} [opts.log] - Progress reporting.
- * @returns {Promise<{stage: string, destination: string, remote: boolean}>}
+ * @param {RemoveTree} [opts.removeTree] - Removes a previous local tree the
+ *   host user is refused permission to remove.
+ * @returns {Promise<{stage: string, destination: string, remote: boolean, leftovers: LeftoverTree[]}>}
+ *   `leftovers` names each previous tree the deploy installed past but could not remove.
  * @throws {Error} On an unknown stage, or one with no destination configured.
  */
-export function deployStage({ stage, source, packageKind, packageId, env, prefix, log, }: {
+export function deployStage({ stage, source, packageKind, packageId, env, prefix, log, removeTree, }: {
     stage: string;
     source: string;
     packageKind: "systems" | "modules";
@@ -128,10 +142,12 @@ export function deployStage({ stage, source, packageKind, packageId, env, prefix
     env?: NodeJS.ProcessEnv | undefined;
     prefix?: string | undefined;
     log?: ((message: string) => void) | undefined;
+    removeTree?: RemoveTree | undefined;
 }): Promise<{
     stage: string;
     destination: string;
     remote: boolean;
+    leftovers: LeftoverTree[];
 }>;
 /**
  * The environment variable naming each stage's Foundry data root.
@@ -146,3 +162,23 @@ export const STAGE_ENV_MAP: Readonly<{
     prod: "FOUNDRYVTT_PROD_DATA";
     test: "FOUNDRYVTT_TEST_DATA";
 }>;
+/**
+ * A previous package tree a deploy could not remove after the swap.
+ */
+export type LeftoverTree = {
+    /**
+     * - The tree, still under its `….old-<pid>` name.
+     */
+    path: string;
+    /**
+     * - Why the last attempt to remove it failed.
+     */
+    reason: string;
+};
+/**
+ * Removes a tree the host user cannot, typically by acting as the user that
+ * owns its files. Receives the tree and the stage's data root.
+ */
+export type RemoveTree = (tree: string, where: {
+    dataRoot: string;
+}) => void | Promise<void>;

package/types/e2e.d.mts

@@ -146,25 +146,57 @@ export function parseFastArgs(argv: string[], build: Record<string, {
  *
  * Writes `world.json` and compiles each LevelDB collection from JSON, so the
  * result is a genuine world Foundry launches without migration or setup. The
- * world directory is wiped and rewritten each time, which is what makes a run
- * repeatable.
+ * world directory is replaced each time, which is what makes a run repeatable.
+ *
+ * The world is built in a staging directory beside the worlds, then moved into
+ * place and handed to the Foundry container's user by a throwaway container
+ * mounting the same data root. Replacing the old world happens there too. Both
+ * halves matter: a database the host user wrote cannot be locked by the
+ * container's user, and a directory the container's user wrote (such as the
+ * `lost/` folder Foundry's repair makes) cannot be unlinked by the host user.
  *
  * @param {object} opts
  * @param {object} opts.config - The resolved package-build configuration.
  * @param {object} opts.packageJson - The repository's `package.json`.
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
  * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @param {(opts: object) => string} [opts.runScript] - Runs a shell script in a
+ *   throwaway container on the data root; replaceable for tests.
  * @returns {Promise<{worldDir: string, world: E2EWorld}>} Where it landed.
  */
-export function seedTestWorld({ config, packageJson, env, log }: {
+export function seedTestWorld({ config, packageJson, env, log, runScript, }: {
     config: object;
     packageJson: object;
     env?: NodeJS.ProcessEnv | undefined;
     log?: ((message: string) => void) | undefined;
+    runScript?: ((opts: object) => string) | undefined;
 }): Promise<{
     worldDir: string;
     world: E2EWorld;
 }>;
+/**
+ * Deploy the staged package to the end-to-end stage so the container's user
+ * can run it.
+ *
+ * The package's databases (compendium packs) are written by the host user, and
+ * Foundry cannot lock them unless it owns them; a pack Foundry has repaired
+ * holds directories the host user cannot unlink. So the previous install is
+ * removed, and the new one handed over, by a throwaway container on the same
+ * data root. A remote destination is deployed as {@link deployStage} does.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @param {(opts: object) => string} [opts.runScript] - Throwaway-container runner.
+ * @returns {Promise<void>}
+ */
+export function deployForContainer({ config, env, log, runScript, }: {
+    config: object;
+    env?: NodeJS.ProcessEnv | undefined;
+    log?: ((message: string) => void) | undefined;
+    runScript?: ((opts: object) => string) | undefined;
+}): Promise<void>;
 /**
  * Poll until the world is active, or fail with a diagnosis.
  *

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

@@ -40,26 +40,13 @@ export function isAddressSegment(value: unknown): boolean;
  * The shape every address segment must match: **lowercase** ASCII letters and
  * digits only.
  *
- * Case *was* deliberately unconstrained, on the reasoning that case has no
- * bearing on the separator — which is true, and beside the point.
- *
  * **Two names that differ only in case are two names nobody can tell apart.** A
  * shortcode is how a person names a thing when writing a reference —
  * `model: weapongear-dgr`, `[[skill-melee|…]]` — and `Dgr` beside `dgr` is a
- * distinction you cannot say out loud and can only see by looking twice.
- *
- * The toolchain had already half-decided it: {@link canonicalKey} lowercases the
- * address it builds, so a note declaring `Clb` published
- * `sohl-sohl-weapongear-clb` and its `_id` derived from that. The authored name
- * and its address disagreed, and everything downstream keys on the address —
- * which left two notes differing only in case sharing one address, one `_id` and
- * one URL, with nothing to report it. It also forces two exceptions elsewhere:
- * the shortcode has to be exempted from the lowercase rule pinned on every
- * other segment, and its case has to be folded in the item catalogue because
- * an address is lowercased when read.
- *
- * One case, one spelling, no exceptions. Every tree already complies but two,
- * and nothing in any of them collides when folded.
+ * distinction you cannot say out loud and can only see by looking twice. So the
+ * shortcode is held to the same rule as every other segment: a note declaring
+ * `shortcode: Dgr` is refused, and so is a declared Address spelling one with a
+ * capital.
  *
  * @type {RegExp}
  */

package/types/engine/address.d.mts

@@ -21,11 +21,16 @@
  * - `no-content-index` — the package named publishes no content index, so there
  *   is nothing to resolve the rest of the target against.
  * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `shortcode-not-lowercase` — the Address spells its shortcode with a
+ *   capital and is otherwise well formed. `shortcode` carries the segment as
+ *   written, and `lowercase` the reading of the lowercase spelling: complete
+ *   for a declared Address, and as partial as the written value otherwise.
  * - `invalid-segment` — a declared Address contains a malformed segment.
  * - `no-package` — a declared Address cannot supply its package.
  * - `invalid-system` — a declared Address cannot supply a registered system.
  *
- * @typedef {{reason: string, package?: string}} AddressProblem
+ * @typedef {{reason: string, package?: string, shortcode?: string,
+ *   lowercase?: AddressTuple}} AddressProblem
  */
 /**
  * The configured types whose prose compiles into a separate JournalEntry.
@@ -94,17 +99,15 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  *   label already removed.
  * @param {AddressDefaults} [defaults] - The position's defaults and the tree's
  *   vocabularies.
- * @param {{declared?: boolean, legacyShortcodeCase?: boolean}} [options] - A declared Address validates every
- *   segment and requires complete defaults. Package membership is a separate
- *   resolution question in this mode; prose recognition keeps its vocabulary checks.
- *   `legacyShortcodeCase` accepts case-insensitive model Shortcodes while the
- *   completed tuple contains their canonical lowercase identity.
+ * @param {{declared?: boolean}} [options] - A declared Address is validated as
+ *   written: every segment, the shortcode included, is lowercase, and the
+ *   defaults must be complete. Package membership is a separate resolution
+ *   question in this mode; prose recognition keeps its vocabulary checks.
  * @returns {AddressTuple|AddressProblem} The complete Address, or why there is
  *   none.
  */
-export function parseAddress(written: unknown, defaults?: AddressDefaults, { declared, legacyShortcodeCase }?: {
+export function parseAddress(written: unknown, defaults?: AddressDefaults, { declared }?: {
     declared?: boolean;
-    legacyShortcodeCase?: boolean;
 }): AddressTuple | AddressProblem;
 /**
  * Split a written value at its anchor.
@@ -343,6 +346,10 @@ export type AddressTuple = {
  * - `no-content-index` — the package named publishes no content index, so there
  *   is nothing to resolve the rest of the target against.
  * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `shortcode-not-lowercase` — the Address spells its shortcode with a
+ *   capital and is otherwise well formed. `shortcode` carries the segment as
+ *   written, and `lowercase` the reading of the lowercase spelling: complete
+ *   for a declared Address, and as partial as the written value otherwise.
  * - `invalid-segment` — a declared Address contains a malformed segment.
  * - `no-package` — a declared Address cannot supply its package.
  * - `invalid-system` — a declared Address cannot supply a registered system.
@@ -350,6 +357,8 @@ export type AddressTuple = {
 export type AddressProblem = {
     reason: string;
     package?: string;
+    shortcode?: string;
+    lowercase?: AddressTuple;
 };
 /**
  * The vocabularies a written Address is read against.

package/types/engine/art-fields.d.mts

@@ -106,7 +106,8 @@ export function assetImageInfoByPathname(records?: readonly object[]): Map<strin
  *   slot's. Omitted, any asset type is taken, which is an embed's rule: it
  *   draws a file, and every asset type is a file.
  * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
- *   |{record: null, reason: string, type?: string}} The asset and the pathname
+ *   |{record: null, reason: string, type?: string, shortcode?: string,
+ *   declared?: string}} The asset and the pathname
  *   it is at, or a reason from
  *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}, or `not-accepted`
  *   when `accepts` is given and the parsed type falls outside it.
@@ -123,6 +124,8 @@ export function readAssetAddress(index: object, value: unknown, defaultType: str
     record: null;
     reason: string;
     type?: string;
+    shortcode?: string;
+    declared?: string;
 };
 /**
  * The index record an art value resolves to, or `null`.
@@ -184,9 +187,9 @@ export function checkArtSlotSizes(records?: readonly object[], { config, assetsB
  * The pathname an art value names, in the form an authored one takes.
  *
  * Handing the result to {@link module:engine/helpers.resolveImg} is what puts an
- * art address and a body image through one ownership rule. The two empties
- * survive it unchanged: `null` and an absent key mean *no art named, apply the
- * default*, and `""` means *ship blank on purpose*.
+ * art address and a body image through one ownership rule. `null` and an
+ * absent key mean *no art named, apply the default*; an empty string names
+ * nothing and is unresolved like any other address nothing answers.
  *
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.

package/types/engine/art-slots.d.mts

@@ -34,6 +34,12 @@ export type ArtSlot = {
      * - Whether the slot reaches a compiled document.
      */
     document: boolean;
+    /**
+     * - The literal value that declines the slot's
+     * art on purpose. It is never read as an Address: it resolves to no image and
+     * is emitted as a blank, which a theme reads as "draw none".
+     */
+    declines?: string | undefined;
     /**
      * - One line, for the author-facing reference.
      */