@kensio/colophon 2.4.0 → 2.6.0

package/README.md

@@ -24,6 +24,8 @@ work.
   frontmatter with real VS Code theme colours.
 - **Configurable branding.** Colours, gradient, fonts, footer and badge come from
   config, not from any one site's stylesheet.
+- **Themes.** Eight named looks, or your own colours with a mesh, grain, a dot
+  grid or ruled lines over them.
 - **Multiple sizes from one input.** A 1:1 square and a 1.91:1 landscape by
   default, or whatever set you configure.
 - **Manifest and meta tags.** A JSON record of what was generated, and the Open
@@ -70,6 +72,8 @@ export default defineConfig({
 });
 ```
 
+`colophon init` writes that file for you, guessing where your content lives.
+
 Run it over a content tree:
 
 ```bash
@@ -78,7 +82,12 @@ colophon content --config colophon.config.ts
 
 For every file that declares `meta_img_props`, Colophon writes one PNG per
 output size next to it, named `<slug>-<size>.png`, so `post/index.md` produces
-`post/post-og.png` and `post/post-square.png`.
+`post/post-og.png` and `post/post-square.png`. Set `format` to `webp`, `jpeg` or
+`avif` for a quarter of the bytes.
+
+While tuning a template, `colophon preview <file>` renders one post and opens
+it, `--watch` rebuilds on every change, and `--dry-run` reports what would
+change without writing anything.
 
 There is also a programmatic API. `renderMetaImages` takes props and config and
 returns rendered bytes, and `generate` ties walking, rendering and writing
@@ -89,20 +98,27 @@ together.
 Full documentation is in [`docs/`](./docs/).
 
 - [Getting started](./docs/getting-started/ "Install, frontmatter, config and the CLI")
+- [The command line](./docs/cli/ "Every command and flag, including init, preview, eject, dry runs and watching")
 - [Templates](./docs/templates/ "The built-in layouts and how to register your own")
 - [The code template](./docs/code-template/ "Syntax-highlighted code images")
+- [Astro](./docs/astro/ "The integration and the meta tags component")
+- [The browser-safe core](./docs/core/ "Running the template layer outside Node")
 - [The layout toolkit](./docs/layout/ "The primitives templates are built from")
+- [Themes and background treatments](./docs/configuration/themes/ "Named looks, meshes, grain, dots and rules")
 - [Logos and photographs](./docs/configuration/images/ "Branding an image with a logo, avatar or background photo")
 - [Configuration](./docs/configuration/ "Every option, and what happens to an unknown one")
+- [Output formats](./docs/configuration/formats/ "WebP, JPEG and AVIF, quality, size caps and the SVG source")
+- [File size](./docs/configuration/compression/ "How hard the rendered PNGs are compressed, and what it costs")
 - [Rebuilds](./docs/rebuilds/ "How Colophon decides what to render again")
 - [Programmatic use](./docs/programmatic-use/ "The API behind the CLI")
 - [Upgrading](./docs/upgrading/ "The breaking changes in 2.0 and 3.0")
 
 ## Sample output
 
-These are generated by [`scripts/gen-samples.ts`](scripts/gen-samples.ts). Run
-`pnpm samples` to regenerate them after changing a template, then commit the
-updated PNGs so this gallery stays in sync.
+These are generated by [`scripts/gen-samples.ts`](scripts/gen-samples.ts) from
+the sample list in [`test/samples.ts`](test/samples.ts). Run `pnpm samples` to
+regenerate them after changing a template, then commit the updated PNGs so this
+gallery stays in sync.
 
 <table>
   <tr>
@@ -135,19 +151,129 @@ updated PNGs so this gallery stays in sync.
       <sub><code>code</code> · 1200×630 · TypeScript, <code>night-owl</code></sub>
     </td>
   </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/article-wide.png" alt="article template, landscape" width="100%" /><br />
+      <sub><code>article</code> · 1200×630 · tags, headline, byline and avatar</sub>
+    </td>
+    <td>
+      <img src="docs/samples/terminal-wide.png" alt="terminal template, landscape" width="100%" /><br />
+      <sub><code>terminal</code> · 1200×630 · a command and its output</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/quote-square.png" alt="quote template, square" width="100%" /><br />
+      <sub><code>quote</code> · 1200×1200 · pull quote with attribution</sub>
+    </td>
+    <td>
+      <img src="docs/samples/release-square.png" alt="release template, square" width="100%" /><br />
+      <sub><code>release</code> · 1200×1200 · version and headline changes</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/stat-square.png" alt="stat template, square" width="100%" /><br />
+      <sub><code>stat</code> · 1200×1200 · one figure and a caption</sub>
+    </td>
+    <td>
+      <img src="docs/samples/event-square.png" alt="event template, square" width="100%" /><br />
+      <sub><code>event</code> · 1200×1200 · date, title and location</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/photo-wide.png" alt="photo template, landscape" width="100%" /><br />
+      <sub><code>photo</code> · 1200×630 · the post's own photograph, scrimmed</sub>
+    </td>
+    <td>
+      <img src="docs/samples/wordmark-wide.png" alt="wordmark template, landscape" width="100%" /><br />
+      <sub><code>wordmark</code> · 1200×630 · logo, name and tagline</sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/docs-wide.png" alt="docs template, landscape" width="100%" /><br />
+      <sub><code>docs</code> · 1200×630 · breadcrumb, title and summary</sub>
+    </td>
+    <td></td>
+  </tr>
+</table>
+
+### Themes
+
+One line of config each: `theme: "midnight"`. See
+[Themes and background treatments](./docs/configuration/themes/) for what a
+theme sets and how to override part of one.
+
+<table>
+  <tr>
+    <td width="25%">
+      <img src="docs/samples/theme-midnight.png" alt="midnight theme" width="100%" /><br />
+      <sub><code>midnight</code></sub>
+    </td>
+    <td width="25%">
+      <img src="docs/samples/theme-aurora.png" alt="aurora theme" width="100%" /><br />
+      <sub><code>aurora</code></sub>
+    </td>
+    <td width="25%">
+      <img src="docs/samples/theme-ember.png" alt="ember theme" width="100%" /><br />
+      <sub><code>ember</code></sub>
+    </td>
+    <td width="25%">
+      <img src="docs/samples/theme-forest.png" alt="forest theme" width="100%" /><br />
+      <sub><code>forest</code></sub>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="docs/samples/theme-bloom.png" alt="bloom theme" width="100%" /><br />
+      <sub><code>bloom</code></sub>
+    </td>
+    <td>
+      <img src="docs/samples/theme-slate.png" alt="slate theme" width="100%" /><br />
+      <sub><code>slate</code></sub>
+    </td>
+    <td>
+      <img src="docs/samples/theme-paper.png" alt="paper theme" width="100%" /><br />
+      <sub><code>paper</code></sub>
+    </td>
+    <td>
+      <img src="docs/samples/theme-sandstone.png" alt="sandstone theme" width="100%" /><br />
+      <sub><code>sandstone</code></sub>
+    </td>
+  </tr>
 </table>
 
 ## Development
 
-| Script                            | What it does                                                               |
-| --------------------------------- | -------------------------------------------------------------------------- |
-| `pnpm build`                      | Compile to `dist/`.                                                        |
-| `pnpm test`, `pnpm test:coverage` | Run Vitest.                                                                |
-| `pnpm lint`                       | ESLint and Prettier check.                                                 |
-| `pnpm fmt`                        | Auto-fix.                                                                  |
-| `pnpm samples`                    | Regenerate the sample images into `docs/samples/`.                         |
-| `pnpm fta`                        | [FTA](https://ftaproject.dev) scores, failing on any file 50 or above.     |
-| `pnpm check`                      | Format, FTA, typecheck and test with coverage. Run this before committing. |
+| Script                            | What it does                                                                 |
+| --------------------------------- | ---------------------------------------------------------------------------- |
+| `pnpm build`                      | Compile to `dist/`.                                                          |
+| `pnpm test`, `pnpm test:coverage` | Run Vitest.                                                                  |
+| `pnpm lint`                       | ESLint and Prettier check.                                                   |
+| `pnpm fmt`                        | Auto-fix.                                                                    |
+| `pnpm samples`                    | Regenerate the sample images into `docs/samples/`.                           |
+| `pnpm baselines`                  | Re-record the visual regression baselines in `test/baselines/`.              |
+| `pnpm fta`                        | [FTA](https://ftaproject.dev) scores, failing on any file 50 or above.       |
+| `pnpm check`                      | Format, FTA, typecheck, build and test with coverage. Run before committing. |
+
+### Visual regression
+
+Templates are pictures, so `pnpm test` renders every sample and compares it
+against a committed baseline in `test/baselines/`. A change to a template shows
+up as a failure naming how far the image moved, and writes what it rendered to
+`test/.visual/` so you can open the two side by side. CI uploads the same
+images as an artifact when the check fails.
+
+When the change was the point, run `pnpm baselines` and commit the new PNGs with
+it. The diff is then the before and after, which is the review the check exists
+to make possible.
+
+The baselines are rendered with font files rather than whatever the machine has
+installed, and at a fraction of the width they are laid out at, which keeps them
+reproducible anywhere and small enough to live in the repository. The gallery
+above is rendered separately, as a project would render it.
 
 ## License
 

package/dist/astro/index.d.ts

@@ -0,0 +1,49 @@
+import type { GenerateOptions } from "../generate/index.js";
+/**
+ * The shape Astro wants an integration to be.
+ *
+ * Declared here rather than imported from `astro`, so that installing Colophon
+ * does not drag a framework in and a project on any Astro version can use this
+ * one. It is structural: what matters is that the object fits where an
+ * integration goes, and a zero-argument hook fits a slot expecting one that
+ * takes the build's context.
+ */
+export interface AstroIntegration {
+    readonly name: string;
+    readonly hooks: {
+        readonly "astro:config:setup": () => Promise<void>;
+    };
+}
+/** What the integration needs, which is what `generate` needs. */
+export type ColophonIntegrationOptions = GenerateOptions;
+/**
+ * Render the site's meta images as part of an Astro build.
+ *
+ * ```js
+ * // astro.config.mjs
+ * import colophon from "@kensio/colophon/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     colophon({
+ *       contentDir: "src/content",
+ *       config: { manifest: "src/data/colophon.json", footer: "example.com" },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * It runs on `astro:config:setup`, which is the one hook that fires for
+ * `astro dev` as well as `astro build`, and which runs before anything is
+ * rendered. Both matter: the manifest has to be on disk before a page that
+ * reads it is built, and a dev server should show the images the build will
+ * produce rather than whatever the last build left behind.
+ *
+ * Running on every dev start sounds expensive and is not, because of the
+ * rebuild stamps: a second run reads the content tree, compares digests and
+ * renders nothing. The manifest is rewritten either way, being a small file
+ * describing images that are already there. Only the first run in a session
+ * pays for rendering, and only for the images that changed.
+ */
+export default function colophon(options: ColophonIntegrationOptions): AstroIntegration;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE;QAGd,QAAQ,CAAC,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KACpD,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,MAAM,0BAA0B,GAAG,eAAe,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CAUlB"}

package/dist/astro/index.js

@@ -0,0 +1,42 @@
+import { generate } from "../generate/index.js";
+/**
+ * Render the site's meta images as part of an Astro build.
+ *
+ * ```js
+ * // astro.config.mjs
+ * import colophon from "@kensio/colophon/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     colophon({
+ *       contentDir: "src/content",
+ *       config: { manifest: "src/data/colophon.json", footer: "example.com" },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * It runs on `astro:config:setup`, which is the one hook that fires for
+ * `astro dev` as well as `astro build`, and which runs before anything is
+ * rendered. Both matter: the manifest has to be on disk before a page that
+ * reads it is built, and a dev server should show the images the build will
+ * produce rather than whatever the last build left behind.
+ *
+ * Running on every dev start sounds expensive and is not, because of the
+ * rebuild stamps: a second run reads the content tree, compares digests and
+ * renders nothing. The manifest is rewritten either way, being a small file
+ * describing images that are already there. Only the first run in a session
+ * pays for rendering, and only for the images that changed.
+ */
+export default function colophon(options) {
+    return {
+        name: "@kensio/colophon",
+        hooks: {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            "astro:config:setup": async () => {
+                await generate(options);
+            },
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/astro/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAwBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,OAAmC;IAEnC,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE;YACL,gEAAgE;YAChE,oBAAoB,EAAE,KAAK,IAAmB,EAAE;gBAC9C,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/background/gradient.d.ts

@@ -0,0 +1,12 @@
+import type { Background, Dimensions } from "../types.js";
+/**
+ * A linear gradient across the whole image: a `<defs>` block holding the
+ * gradient under the given `id`, and a rect filled with it.
+ *
+ * The coordinates are object-bounding-box units, so the default runs corner to
+ * corner whatever the image's proportions are.
+ */
+export declare function gradientBackground(background: Extract<Background, {
+    readonly type: "gradient";
+}>, dimensions: Dimensions, id: string): string;
+//# sourceMappingURL=gradient.d.ts.map

package/dist/background/gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradient.d.ts","sourceRoot":"","sources":["../../src/background/gradient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,EAC9D,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,GACT,MAAM,CAgBR"}

package/dist/background/gradient.js

@@ -0,0 +1,21 @@
+/**
+ * A linear gradient across the whole image: a `<defs>` block holding the
+ * gradient under the given `id`, and a rect filled with it.
+ *
+ * The coordinates are object-bounding-box units, so the default runs corner to
+ * corner whatever the image's proportions are.
+ */
+export function gradientBackground(background, dimensions, id) {
+    const { width, height } = dimensions;
+    const from = background.from ?? { x: 0, y: 0 };
+    const to = background.to ?? { x: 1, y: 1 };
+    const stops = background.stops
+        .map((stop) => `<stop offset="${stop.offset}" stop-color="${stop.color}"/>`)
+        .join("");
+    return (`<defs>` +
+        `<linearGradient id="${id}" x1="${String(from.x)}" y1="${String(from.y)}"` +
+        ` x2="${String(to.x)}" y2="${String(to.y)}">${stops}</linearGradient>` +
+        `</defs>` +
+        `<rect width="${String(width)}" height="${String(height)}" fill="url(#${id})"/>`);
+}
+//# sourceMappingURL=gradient.js.map

package/dist/background/gradient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradient.js","sourceRoot":"","sources":["../../src/background/gradient.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAA8D,EAC9D,UAAsB,EACtB,EAAU;IAEV,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IACrC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK;SAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,IAAI,CAAC,MAAM,iBAAiB,IAAI,CAAC,KAAK,KAAK,CAAC;SAC3E,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,CACL,QAAQ;QACR,uBAAuB,EAAE,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG;QAC1E,QAAQ,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,mBAAmB;QACtE,SAAS;QACT,gBAAgB,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CACjF,CAAC;AACJ,CAAC"}

package/dist/background/image.d.ts

@@ -0,0 +1,14 @@
+import type { Rect } from "../layout/index.js";
+import type { Background, ImageAsset } from "../types.js";
+/**
+ * A photograph behind the text: the backdrop, the picture, and the wash over
+ * it that keeps the text readable.
+ *
+ * The scrim is on by default and has to be turned off rather than on. Text
+ * over an unshaded photo is the failure this would otherwise ship with, and it
+ * is not one an author notices unless they look at every image.
+ */
+export declare function imageBackground(background: Extract<Background, {
+    readonly type: "image";
+}>, area: Rect, id: string, asset: ImageAsset | undefined): string;
+//# sourceMappingURL=image.d.ts.map

package/dist/background/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/background/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAS,MAAM,aAAa,CAAC;AAgBjE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,EAC3D,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,CAkBR"}

package/dist/background/image.js

@@ -0,0 +1,36 @@
+import { box, image as imageElement, scrim } from "../layout/index.js";
+/** Behind a background image, and either side of one that is `contain`ed. */
+const defaultBackdrop = "#000000";
+/**
+ * How heavily the default scrim shades, top and bottom.
+ *
+ * It starts at a quarter rather than at nothing, because a template is free to
+ * put its text anywhere and a wash that only darkens the bottom leaves a
+ * centred title sitting on whatever the middle of the photograph happens to
+ * be. Shading the whole picture a little and the bottom a lot covers both, and
+ * a project that wants the picture untouched at the top sets `from: 0`.
+ */
+const defaultScrim = { from: 0.25, to: 0.65 };
+/**
+ * A photograph behind the text: the backdrop, the picture, and the wash over
+ * it that keeps the text readable.
+ *
+ * The scrim is on by default and has to be turned off rather than on. Text
+ * over an unshaded photo is the failure this would otherwise ship with, and it
+ * is not one an author notices unless they look at every image.
+ */
+export function imageBackground(background, area, id, asset) {
+    const backdrop = box(area, { fill: background.color ?? defaultBackdrop });
+    if (asset === undefined) {
+        return backdrop;
+    }
+    const shade = background.scrim ?? {};
+    return (backdrop +
+        imageElement(area, asset.href, { fit: background.fit ?? "cover" }) +
+        scrim(area, `${id}-scrim`, {
+            ...(shade.color !== undefined && { color: shade.color }),
+            from: shade.from ?? defaultScrim.from,
+            to: shade.to ?? defaultScrim.to,
+        }));
+}
+//# sourceMappingURL=image.js.map

package/dist/background/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/background/image.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGvE,6EAA6E;AAC7E,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA2D,EAC3D,IAAU,EACV,EAAU,EACV,KAA6B;IAE7B,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC,CAAC;IAE1E,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAU,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;IAE5C,OAAO,CACL,QAAQ;QACR,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,IAAI,OAAO,EAAE,CAAC;QAClE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE;YACzB,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACxD,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,YAAY,CAAC,IAAI;YACrC,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,YAAY,CAAC,EAAE;SAChC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/{background.d.ts → background/index.d.ts}

@@ -1,8 +1,8 @@
-import type { Background, Dimensions, ImageAsset } from "./types.js";
+import type { Background, Dimensions, ImageAsset } from "../types.js";
 /**
- * Render a full-bleed background as SVG. For a gradient, this emits a `<defs>`
- * block with a `<linearGradient>` (using the given `id`) followed by a filled
- * rect; for a solid colour it emits just the rect.
+ * Render a full-bleed background as SVG. Gradients and meshes emit a `<defs>`
+ * block naming their fills after the given `id`, followed by the rects that
+ * use them; a solid colour is just the rect.
  *
  * A background image has to be read before it can be drawn, which is the
  * renderer's job. Called without one, an image background is the colour behind
@@ -10,4 +10,4 @@ import type { Background, Dimensions, ImageAsset } from "./types.js";
  * reference to something that is not there.
  */
 export declare function backgroundSvg(background: Background, dimensions: Dimensions, id: string, asset?: ImageAsset): string;
-//# sourceMappingURL=background.d.ts.map
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKtE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,UAAU,GACjB,MAAM,CAqBR"}

package/dist/background/index.js

@@ -0,0 +1,27 @@
+import { gradientBackground } from "./gradient.js";
+import { imageBackground } from "./image.js";
+import { meshBackground } from "./mesh.js";
+/**
+ * Render a full-bleed background as SVG. Gradients and meshes emit a `<defs>`
+ * block naming their fills after the given `id`, followed by the rects that
+ * use them; a solid colour is just the rect.
+ *
+ * A background image has to be read before it can be drawn, which is the
+ * renderer's job. Called without one, an image background is the colour behind
+ * it, so a caller assembling an SVG by hand gets a plain image rather than a
+ * reference to something that is not there.
+ */
+export function backgroundSvg(background, dimensions, id, asset) {
+    const { width, height } = dimensions;
+    if (background.type === "solid") {
+        return `<rect width="${String(width)}" height="${String(height)}" fill="${background.color}"/>`;
+    }
+    if (background.type === "image") {
+        return imageBackground(background, { x: 0, y: 0, width, height }, id, asset);
+    }
+    if (background.type === "mesh") {
+        return meshBackground(background, dimensions, id);
+    }
+    return gradientBackground(background, dimensions, id);
+}
+//# sourceMappingURL=index.js.map

package/dist/background/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAsB,EACtB,UAAsB,EACtB,EAAU,EACV,KAAkB;IAElB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAErC,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO,gBAAgB,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,WAAW,UAAU,CAAC,KAAK,KAAK,CAAC;IAClG,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO,eAAe,CACpB,UAAU,EACV,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAC7B,EAAE,EACF,KAAK,CACN,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC/B,OAAO,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/background/mesh.d.ts

@@ -0,0 +1,12 @@
+import type { Background, Dimensions } from "../types.js";
+/**
+ * Soft blobs of colour over a flat base, which is what a linear gradient
+ * cannot do: colour that moves in more than one direction at once.
+ *
+ * Every blob covers the whole image and is mostly transparent, so they are
+ * drawn in the order they were given and the later ones sit over the earlier.
+ */
+export declare function meshBackground(background: Extract<Background, {
+    readonly type: "mesh";
+}>, dimensions: Dimensions, id: string): string;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/background/mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../src/background/mesh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AAsCpE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,GACT,MAAM,CAYR"}

package/dist/background/mesh.js

@@ -0,0 +1,43 @@
+/** Radius of a blob that does not name one, as a fraction of the longer side. */
+const defaultRadius = 0.7;
+/**
+ * One blob: a radial fade from its colour to nothing, and a rect filled with
+ * it. A rect rather than a circle because the fade reaches the edge of the
+ * image on at least one side of most blobs, and a circle would clip it there.
+ *
+ * The gradient is in user space rather than in bounding-box units, so the fade
+ * stays circular. In bounding-box units it would take the proportions of the
+ * rect it fills, which is the whole image, and a landscape image would stretch
+ * every blob into an ellipse.
+ */
+function blobSvg(blob, dimensions, id) {
+    const { width, height } = dimensions;
+    const radius = (blob.radius ?? defaultRadius) * Math.max(width, height);
+    const opacity = blob.opacity ?? 1;
+    const def = `<radialGradient id="${id}" gradientUnits="userSpaceOnUse"` +
+        ` cx="${String((blob.x ?? 0.5) * width)}"` +
+        ` cy="${String((blob.y ?? 0.5) * height)}" r="${String(radius)}">` +
+        `<stop offset="0%" stop-color="${blob.color}" stop-opacity="${String(opacity)}"/>` +
+        `<stop offset="100%" stop-color="${blob.color}" stop-opacity="0"/>` +
+        `</radialGradient>`;
+    return {
+        def,
+        rect: `<rect width="${String(width)}" height="${String(height)}" fill="url(#${id})"/>`,
+    };
+}
+/**
+ * Soft blobs of colour over a flat base, which is what a linear gradient
+ * cannot do: colour that moves in more than one direction at once.
+ *
+ * Every blob covers the whole image and is mostly transparent, so they are
+ * drawn in the order they were given and the later ones sit over the earlier.
+ */
+export function meshBackground(background, dimensions, id) {
+    const { width, height } = dimensions;
+    const blobs = background.blobs.map((blob, index) => blobSvg(blob, dimensions, `${id}-blob-${String(index)}`));
+    return (`<defs>${blobs.map((blob) => blob.def).join("")}</defs>` +
+        `<rect width="${String(width)}" height="${String(height)}" fill="${background.color}"/>${blobs
+            .map((blob) => blob.rect)
+            .join("")}`);
+}
+//# sourceMappingURL=mesh.js.map

package/dist/background/mesh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.js","sourceRoot":"","sources":["../../src/background/mesh.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B;;;;;;;;;GASG;AACH,SAAS,OAAO,CACd,IAAc,EACd,UAAsB,EACtB,EAAU;IAEV,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAElC,MAAM,GAAG,GACP,uBAAuB,EAAE,kCAAkC;QAC3D,QAAQ,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG;QAC1C,QAAQ,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,IAAI;QAClE,iCAAiC,IAAI,CAAC,KAAK,mBAAmB,MAAM,CAAC,OAAO,CAAC,KAAK;QAClF,mCAAmC,IAAI,CAAC,KAAK,sBAAsB;QACnE,mBAAmB,CAAC;IAEtB,OAAO;QACL,GAAG;QACH,IAAI,EAAE,gBAAgB,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM;KACvF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,UAA0D,EAC1D,UAAsB,EACtB,EAAU;IAEV,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IACrC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACjD,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CACzD,CAAC;IAEF,OAAO,CACL,SAAS,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS;QACxD,gBAAgB,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,WAAW,UAAU,CAAC,KAAK,MAAM,KAAK;aAC3F,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;aACxB,IAAI,CAAC,EAAE,CAAC,EAAE,CACd,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,13 @@
+/** What the CLI has been asked to do. */
+export type CliCommand = "generate" | "init" | "preview" | "eject";
+/**
+ * Read the command out of the first argument.
+ *
+ * It is a command only where it names one: `colophon content` has always meant
+ * "build this tree", so a bare positional stays the content directory, and a
+ * subcommand is an addition to that rather than a replacement for it. The cost
+ * is that a content directory called `init` or `preview` has to be written as
+ * `./init`, which is worth saying in the help text and no more.
+ */
+export declare function commandOf(first: string | undefined): CliCommand;
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/cli/args/command.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAYnE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAE/D"}

package/dist/cli/args/command.js

@@ -0,0 +1,22 @@
+/**
+ * The commands that are named on the command line. `generate` is not among
+ * them because it is what a run with no command does.
+ */
+const named = {
+    init: "init",
+    preview: "preview",
+    eject: "eject",
+};
+/**
+ * Read the command out of the first argument.
+ *
+ * It is a command only where it names one: `colophon content` has always meant
+ * "build this tree", so a bare positional stays the content directory, and a
+ * subcommand is an addition to that rather than a replacement for it. The cost
+ * is that a content directory called `init` or `preview` has to be written as
+ * `./init`, which is worth saying in the help text and no more.
+ */
+export function commandOf(first) {
+    return (first === undefined ? undefined : named[first]) ?? "generate";
+}
+//# sourceMappingURL=command.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/cli/args/command.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,KAAK,GAAyC;IAClD,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,KAAyB;IACjD,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC;AACxE,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { CliCommand } from "./command.js";
+export type { CliCommand } from "./command.js";
+export { usage } from "./usage.js";
+/**
+ * The parsed command line.
+ */
+export interface CliArgs {
+    readonly command: CliCommand;
+    /**
+     * The content tree to build. `undefined` where the run named none, which
+     * `generate` reads as the default and `init` as an invitation to guess.
+     */
+    readonly contentDir: string | undefined;
+    /** The post `preview` renders. */
+    readonly file: string | undefined;
+    /** What `eject` writes, naming the generator it is for. */
+    readonly adapter: string | undefined;
+    readonly configPath: string | undefined;
+    readonly overwrite: boolean;
+    readonly dryRun: boolean;
+    readonly watch: boolean;
+    readonly concurrency: number | undefined;
+    /** Which configured size `preview` renders. */
+    readonly size: string | undefined;
+}
+/** Read the command line into the options each command takes. */
+export declare function parseCliArgs(argv: readonly string[]): CliArgs;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/args/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAM/C,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AA2CD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAyC7D"}