@kensio/colophon 2.15.2 → 2.15.4

package/dist/cli/args/usage.d.ts

@@ -1,3 +1,3 @@
 /** Help text for `--help`, and for a run that asks for nothing else. */
-export declare const usage = "colophon: generate social meta images from frontmatter\n\nUsage:\n  colophon [contentDir] [options]    Render the images for a content tree\n  colophon init [contentDir]         Write a starter config module\n  colophon preview <file> [options]  Render one post and open it\n  colophon eject hugo                Write a Hugo partial that reads the\n                                     manifest and emits the meta tags\n\nImages carry a stamp of the props, config and size they came from, so a rebuild\nrenders only the ones that have actually changed.\n\nOptions:\n  -c, --config <path>   Load a config module. Its default export is either a\n                        ColophonConfig or a function (async or not) returning\n                        one, for a config that has to compute something.\n  -f, --force           Re-render every image, ignoring the stamps. For init\n                        and eject, overwrite a file that is already there\n  -o, --overwrite       Alias for --force\n  -n, --dry-run         Report what would change and write nothing\n  -w, --watch           Rebuild whenever a content file changes\n  --concurrency <n>     How many images to render at once\n  --size <name>         Which configured size preview renders\n  -h, --help            Show this help\n\nDefaults:\n  contentDir            content\n  --concurrency         one per available CPU\n  --size                the first configured size\n\nThe first argument is a command where it names one, so a content directory\ncalled init, preview or eject has to be written as ./init.";
+export declare const usage = "colophon: generate social meta images from frontmatter\n\nUsage:\n  colophon [contentDir] [options]    Render the images for a content tree\n  colophon init [contentDir]         Write a starter config module\n  colophon preview <file> [options]  Render one post and open it\n  colophon eject hugo                Write a Hugo partial that reads the\n                                     manifest and emits the meta tags\n\nImages carry a stamp of the props, config and size they came from, so a rebuild\nrenders only the ones that have actually changed.\n\nOptions:\n  -c, --config <path>   Load a config module. Its default export is either a\n                        ColophonConfig or a function (async or not) returning\n                        one, for a config that has to compute something.\n  -f, --force           Re-render every image, ignoring the stamps. For init\n                        and eject, overwrite a file that is already there\n  -o, --overwrite       Alias for --force\n  -n, --dry-run         Report what would change and write nothing\n  -w, --watch           Rebuild whenever a content file changes\n  --concurrency <n>     How many images to render at once\n  --size <name>         Which configured size preview renders\n  -h, --help            Show this help\n\nDefaults:\n  contentDir            content\n  --concurrency         one per available CPU\n  --size                the first configured size\n\nRendering happens on the libuv thread pool, four threads deep unless\nUV_THREADPOOL_SIZE says otherwise. A higher concurrency than that queues, and\nthe build warns. Raise the pool by setting the variable in the environment.\n\nThe first argument is a command where it names one, so a content directory\ncalled init, preview or eject has to be written as ./init.";
 //# sourceMappingURL=usage.d.ts.map

package/dist/cli/args/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,KAAK,qiDA+ByC,CAAC"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,KAAK,ywDAmCyC,CAAC"}

package/dist/cli/args/usage.js

@@ -29,6 +29,10 @@ Defaults:
   --concurrency         one per available CPU
   --size                the first configured size
 
+Rendering happens on the libuv thread pool, four threads deep unless
+UV_THREADPOOL_SIZE says otherwise. A higher concurrency than that queues, and
+the build warns. Raise the pool by setting the variable in the environment.
+
 The first argument is a command where it names one, so a content directory
 called init, preview or eject has to be written as ./init.`;
 //# sourceMappingURL=usage.js.map

package/dist/cli/args/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DA+BsC,CAAC"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../../src/cli/args/usage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DAmCsC,CAAC"}

package/dist/generate/index.d.ts

@@ -13,7 +13,10 @@ export type { GeneratedImage, GenerateOptions } from "./options.js";
  * everything. Sizes with no image to render are never rasterised.
  *
  * Rendering runs `concurrency` images at a time rather than all of them, so a
- * large tree does not start hundreds of rasterisations at once.
+ * large tree does not start hundreds of rasterisations at once. How many of
+ * those make progress at a time is the libuv thread pool's business, and a
+ * build asking for more than the pool has says so in a warning. See
+ * {@link GenerateOptions.concurrency}.
  *
  * `dryRun` stops short of writing: the plan is built and the stamps are read,
  * so the results say which images are out of date, but nothing is rendered and

package/dist/generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC,CA+B3B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAMpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC,CAgC3B"}

package/dist/generate/index.js

@@ -4,6 +4,7 @@ import { readImageStamp } from "../stamp/index.js";
 import { resolveConcurrency } from "./options.js";
 import { planBuild } from "./plan.js";
 import { renderImage } from "./render-image.js";
+import { warnIfPoolIsSmaller } from "./thread-pool.js";
 export { defaultOutputPath } from "./output-path.js";
 /**
  * Walk a content tree and render meta images for every file that declares
@@ -17,7 +18,10 @@ export { defaultOutputPath } from "./output-path.js";
  * everything. Sizes with no image to render are never rasterised.
  *
  * Rendering runs `concurrency` images at a time rather than all of them, so a
- * large tree does not start hundreds of rasterisations at once.
+ * large tree does not start hundreds of rasterisations at once. How many of
+ * those make progress at a time is the libuv thread pool's business, and a
+ * build asking for more than the pool has says so in a warning. See
+ * {@link GenerateOptions.concurrency}.
  *
  * `dryRun` stops short of writing: the plan is built and the stamps are read,
  * so the results say which images are out of date, but nothing is rendered and
@@ -26,6 +30,7 @@ export { defaultOutputPath } from "./output-path.js";
 export async function generate(options) {
     const concurrency = resolveConcurrency(options.concurrency);
     const plan = await planBuild(options);
+    warnIfPoolIsSmaller(concurrency, plan.config.onWarning);
     const results = await mapConcurrent(plan.jobs, concurrency, async (job) => {
         const isSkipped = options.overwrite !== true &&
             (await readImageStamp(job.outputPath)) === job.stamp;

package/dist/generate/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAwB;IAExB,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;IAEtC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACxE,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,KAAK,IAAI;YAC1B,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC;QAEvD,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAmB;YAC7B,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,OAAO,EAAE,SAAS;SACnB,CAAC;QACF,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,kEAAkE;IAClE,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAwB;IAExB,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;IACtC,mBAAmB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAExD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACxE,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,KAAK,IAAI;YAC1B,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC;QAEvD,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAmB;YAC7B,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,OAAO,EAAE,SAAS;SACnB,CAAC;QACF,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,kEAAkE;IAClE,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/generate/options.d.ts

@@ -51,6 +51,14 @@ export interface GenerateOptions {
     /**
      * How many images to render at once. Defaults to the number of CPUs the
      * process can use. Must be a positive integer.
+     *
+     * The parts of a render that take real time (the rasteriser, the PNG
+     * recompression and the quantiser) all run on the libuv thread pool. That
+     * pool has four threads unless `UV_THREADPOOL_SIZE` says otherwise, so on a
+     * machine with more cores than that a higher concurrency only queues work
+     * up. libuv sizes the pool from the environment before the process starts,
+     * and a build can only read it. Where the pool is the smaller of the two,
+     * `generate` warns.
      */
     readonly concurrency?: number;
     /** Called after each image is written or skipped. */
@@ -61,6 +69,12 @@ export interface GenerateOptions {
  * the process can actually use. Rasterising is CPU-bound, so starting more
  * than that only queues the work up while holding every pending image in
  * memory.
+ *
+ * The real ceiling is the smaller of this and the libuv thread pool. That
+ * pool holds four threads unless `UV_THREADPOOL_SIZE` was set in the
+ * environment, so the default here is reached on a machine of four cores or
+ * fewer, or with the pool sized to match. `generate` warns where the two
+ * disagree.
  */
 export declare function resolveConcurrency(concurrency: number | undefined): number;
 //# sourceMappingURL=options.d.ts.map

package/dist/generate/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/generate/options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CACtD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAY1E"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/generate/options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CACtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAY1E"}

package/dist/generate/options.js

@@ -4,6 +4,12 @@ import { availableParallelism } from "node:os";
  * the process can actually use. Rasterising is CPU-bound, so starting more
  * than that only queues the work up while holding every pending image in
  * memory.
+ *
+ * The real ceiling is the smaller of this and the libuv thread pool. That
+ * pool holds four threads unless `UV_THREADPOOL_SIZE` was set in the
+ * environment, so the default here is reached on a machine of four cores or
+ * fewer, or with the pool sized to match. `generate` warns where the two
+ * disagree.
  */
 export function resolveConcurrency(concurrency) {
     if (concurrency === undefined) {

package/dist/generate/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/generate/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AA+D/C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAA+B;IAChE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,oBAAoB,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,uBAAuB,MAAM,CAAC,WAAW,CAAC,gCAAgC,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/generate/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAuE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAA+B;IAChE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,oBAAoB,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,uBAAuB,MAAM,CAAC,WAAW,CAAC,gCAAgC,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/generate/plan.d.ts

@@ -1,5 +1,6 @@
 import type { PlannedManifest } from "../manifest/index.js";
 import type { Stamper } from "../stamp/index.js";
+import type { ResolvedConfig } from "../types.js";
 import type { RenderJob } from "./job.js";
 import type { GenerateOptions } from "./options.js";
 /**
@@ -9,6 +10,13 @@ import type { GenerateOptions } from "./options.js";
 export interface BuildPlan {
     readonly jobs: readonly RenderJob[];
     readonly stamper: Stamper;
+    /**
+     * The build's own config, before any per-size overrides. Where a build has
+     * something to say about the run as a whole, this is where its `onWarning`
+     * comes from. The per-image handler lives on each job, and a tree with no
+     * images to render has no job to take one from.
+     */
+    readonly config: ResolvedConfig;
     /** What to write down about the build, where a config asked for it. */
     readonly manifest: PlannedManifest | undefined;
 }

package/dist/generate/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/generate/plan.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAMpD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;CAChD;AAqBD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAmD5E"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/generate/plan.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAIjD,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAMpD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;CAChD;AAqBD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAoD5E"}

package/dist/generate/plan.js

@@ -66,6 +66,7 @@ export async function planBuild(options) {
     return {
         jobs: all,
         stamper,
+        config: resolved,
         manifest: planManifest(options.config?.manifest, all),
     };
 }

package/dist/generate/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/generate/plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/generate/plan.ts"],"names":[],"mappings":"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"}

package/dist/generate/thread-pool.d.ts

@@ -0,0 +1,30 @@
+import type { WarningHandler } from "../types.js";
+/**
+ * How many threads this process's libuv pool has.
+ *
+ * The pool is sized once from the environment, the first time anything asks it
+ * to do work. A `process.env.UV_THREADPOOL_SIZE` written from inside the
+ * process arrives after that moment and changes nothing. This function only
+ * reads.
+ *
+ * libuv reads the setting with `atoi` and treats a zero as unset, and an
+ * unparseable value gives it a zero. Anything short of a positive integer
+ * therefore reads back here as the default.
+ */
+export declare function threadPoolSize(setting?: string | undefined): number;
+/**
+ * A warner that says the concurrency a build asked for is above what the
+ * thread pool can serve, and says it once.
+ *
+ * Once, because the ceiling belongs to the process. A watch rebuilding on
+ * every content change would otherwise repeat the same line all day, and no
+ * build can act on it while it runs. The state lives in the returned function,
+ * so a test can hold one of its own and the shared warner stays shared.
+ */
+export declare function createThreadPoolWarner(): (concurrency: number, onWarning: WarningHandler, poolSize?: number) => void;
+/**
+ * Tell a build that its concurrency is capped by the thread pool. One warner
+ * for the process, so every build in it shares the one warning.
+ */
+export declare const warnIfPoolIsSmaller: (concurrency: number, onWarning: WarningHandler, poolSize?: number) => void;
+//# sourceMappingURL=thread-pool.d.ts.map

package/dist/generate/thread-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-pool.d.ts","sourceRoot":"","sources":["../../src/generate/thread-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,MAAM,GAAG,SAA6C,GAC9D,MAAM,CAQR;AAcD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,cAAc,EACzB,QAAQ,CAAC,EAAE,MAAM,KACd,IAAI,CAWR;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,gBApBjB,MAAM,aACR,cAAc,aACd,MAAM,KACd,IAiBsD,CAAC"}

package/dist/generate/thread-pool.js

@@ -0,0 +1,59 @@
+/**
+ * How many threads libuv starts when `UV_THREADPOOL_SIZE` says nothing, and
+ * the largest pool it will build however big the setting is.
+ */
+const DEFAULT_POOL_SIZE = 4;
+const MAX_POOL_SIZE = 1024;
+/**
+ * How many threads this process's libuv pool has.
+ *
+ * The pool is sized once from the environment, the first time anything asks it
+ * to do work. A `process.env.UV_THREADPOOL_SIZE` written from inside the
+ * process arrives after that moment and changes nothing. This function only
+ * reads.
+ *
+ * libuv reads the setting with `atoi` and treats a zero as unset, and an
+ * unparseable value gives it a zero. Anything short of a positive integer
+ * therefore reads back here as the default.
+ */
+export function threadPoolSize(setting = process.env["UV_THREADPOOL_SIZE"]) {
+    const parsed = Number(setting);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        return DEFAULT_POOL_SIZE;
+    }
+    return Math.min(parsed, MAX_POOL_SIZE);
+}
+/** What to say about a concurrency the pool is too small to serve. */
+function message(concurrency, poolSize) {
+    return (`Rendering ${String(concurrency)} images at once, but the libuv thread` +
+        ` pool has ${String(poolSize)} threads. Rasterising, PNG recompression` +
+        ` and quantising all run on that pool, so only ${String(poolSize)}` +
+        " renders make progress at a time. Set" +
+        ` UV_THREADPOOL_SIZE=${String(concurrency)} in the environment before the` +
+        " process starts to lift the ceiling.");
+}
+/**
+ * A warner that says the concurrency a build asked for is above what the
+ * thread pool can serve, and says it once.
+ *
+ * Once, because the ceiling belongs to the process. A watch rebuilding on
+ * every content change would otherwise repeat the same line all day, and no
+ * build can act on it while it runs. The state lives in the returned function,
+ * so a test can hold one of its own and the shared warner stays shared.
+ */
+export function createThreadPoolWarner() {
+    let hasWarned = false;
+    return (concurrency, onWarning, poolSize = threadPoolSize()) => {
+        if (hasWarned || concurrency <= poolSize) {
+            return;
+        }
+        hasWarned = true;
+        onWarning(message(concurrency, poolSize));
+    };
+}
+/**
+ * Tell a build that its concurrency is capped by the thread pool. One warner
+ * for the process, so every build in it shares the one warning.
+ */
+export const warnIfPoolIsSmaller = createThreadPoolWarner();
+//# sourceMappingURL=thread-pool.js.map

package/dist/generate/thread-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-pool.js","sourceRoot":"","sources":["../../src/generate/thread-pool.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAO,GAAuB,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAE/D,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAE/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACzC,CAAC;AAED,sEAAsE;AACtE,SAAS,OAAO,CAAC,WAAmB,EAAE,QAAgB;IACpD,OAAO,CACL,aAAa,MAAM,CAAC,WAAW,CAAC,uCAAuC;QACvE,aAAa,MAAM,CAAC,QAAQ,CAAC,0CAA0C;QACvE,iDAAiD,MAAM,CAAC,QAAQ,CAAC,EAAE;QACnE,uCAAuC;QACvC,uBAAuB,MAAM,CAAC,WAAW,CAAC,gCAAgC;QAC1E,sCAAsC,CACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB;IAKpC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,OAAO,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,GAAG,cAAc,EAAE,EAAE,EAAE;QAC7D,IAAI,SAAS,IAAI,WAAW,IAAI,QAAQ,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QAED,SAAS,GAAG,IAAI,CAAC;QACjB,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,EAAE,CAAC"}

package/package.json

@@ -5,7 +5,7 @@
   "repository": "https://github.com/KensioSoftware/colophon",
   "homepage": "https://github.com/KensioSoftware/colophon#readme",
   "license": "Apache-2.0",
-  "version": "2.15.2",
+  "version": "2.15.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -95,7 +95,7 @@
     "conventional-changelog-conventionalcommits": "9.3.1",
     "dejavu-fonts-ttf": "^2.37.3",
     "fta-cli": "^3.0.0",
-    "oxfmt": "^0.62.0",
+    "oxfmt": "^0.63.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",