@kensio/colophon 2.2.0 → 2.4.0

package/README.md

@@ -1,22 +1,34 @@
-# @kensio/colophon
-
-Generate social meta images (Open Graph / share-card images) for the posts of a
-static website, driven by each post's frontmatter.
-
-You describe an image in frontmatter — `title`, `subtitle`, `version`, a
-template name — and Colophon renders branded PNGs at the sizes you need. The
-name comes from the printer's _colophon_: the emblem a publisher stamps on a
-finished work.
-
-- **Frontmatter-driven** — general props read from a post, not a fixed schema.
-- **Templates** — a small registry of layouts; frontmatter picks one.
-- **Syntax-highlighted code images** — the `code` template renders a snippet
-  from 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.
-- **Multiple sizes from one input** — a 1:1 square plus a 1.91:1 landscape by
+# <img src="https://colophonjs.dev/favicon.png" alt="Colophon logo" width="28" height="28">&nbsp;&nbsp;@kensio/colophon
+
+[![npm version](https://img.shields.io/npm/v/%40kensio%2Fcolophon)](https://www.npmjs.com/package/@kensio/colophon)
+![CI](https://img.shields.io/github/actions/workflow/status/KensioSoftware/colophon/pr.yml?label=CI)
+![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/hughgrigg/f2d667bbcc14dab9efa679f2113b1e00/raw/coverage.json)
+![Node](https://img.shields.io/node/v/%40kensio%2Fcolophon)
+![TypeScript](https://img.shields.io/badge/TS-TypeScript-3178C6)
+![License](https://img.shields.io/npm/l/%40kensio%2Fcolophon)
+
+Generate social meta images (Open Graph and share-card images) for the posts of
+a static website, driven by each post's frontmatter.
+
+[https://colophonjs.dev/](https://colophonjs.dev/ "Colophon documentation website")
+
+You describe an image in frontmatter with a title, a subtitle, a version and a
+template name, and Colophon renders branded PNGs at the sizes you need. The name
+comes from the printer's _colophon_, the emblem a publisher stamps on a finished
+work.
+
+- **Frontmatter-driven.** Props are read from a post rather than fixed by a
+  schema.
+- **Templates.** A small registry of layouts, picked per post from frontmatter.
+- **Syntax-highlighted code images.** The `code` template renders a snippet from
+  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.
+- **Multiple sizes from one input.** A 1:1 square and a 1.91:1 landscape by
   default, or whatever set you configure.
-- **Small, reusable API** — a render core with no filesystem concerns, plus an
+- **Manifest and meta tags.** A JSON record of what was generated, and the Open
+  Graph and Twitter tags that go with it.
+- **Small, reusable API.** A render core with no filesystem concerns, plus an
   optional content walker and CLI.
 
 ## Install
@@ -25,10 +37,12 @@ finished work.
 pnpm add @kensio/colophon
 ```
 
-`sharp` is a dependency and does the SVG → PNG rasterisation; `shiki` provides
-the grammars and themes for the `code` template.
+`@resvg/resvg-js` rasterises the SVG to PNG, and `shiki` provides the grammars
+and themes for the `code` template. No headless browser is involved. Fonts can
+be handed to the renderer as files, so a build renders the same image
+everywhere.
 
-## Quick start (CLI)
+## Quick start
 
 Add image props to a post's frontmatter:
 
@@ -43,7 +57,7 @@ meta_img_props:
 ---
 ```
 
-Create a config module (optional — omit to use the neutral defaults):
+Create a config module, or omit it to use the neutral defaults:
 
 ```ts
 // colophon.config.ts
@@ -63,238 +77,30 @@ 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`
-(`post/index.md` → `post/post-og.png` and `post/post-square.png`). Existing
-files are skipped unless you pass `--overwrite`.
-
-```
-colophon [contentDir] [options]
-
-  -c, --config <path>   Config module whose default export is a ColophonConfig
-  -o, --overwrite       Re-render even if the output file already exists
-  -h, --help            Show help
-
-  contentDir            defaults to "content"
-```
-
-## Programmatic use
-
-### Render from props (core)
-
-The core takes props and config and returns rendered bytes — no filesystem, no
-content discovery:
-
-```ts
-import { renderMetaImages } from "@kensio/colophon";
-import { writeFile } from "node:fs/promises";
-
-const images = await renderMetaImages(
-  {
-    template: "banner",
-    title: "@kensio/colophon",
-    subtitle: "Generate social meta images from frontmatter",
-    version: "1.2.0",
-  },
-  {
-    colors: { brand: "#2563eb" },
-    footer: "example.com",
-    badge: { text: "npm" },
-  },
-);
-
-for (const image of images) {
-  // image.name is the output-size name ("og", "square", …).
-  await writeFile(`social-${image.name}.png`, image.png);
-}
-```
-
-### Walk content + generate (host helpers)
-
-`walkContent` finds `.md` files and reads their frontmatter; `generate` ties
-walking, rendering and writing together (this is what the CLI uses):
-
-```ts
-import { generate } from "@kensio/colophon";
-
-await generate({
-  contentDir: "content",
-  config: { colors: { brand: "#2563eb" } },
-  overwrite: false,
-  onResult: (result) =>
-    console.log(`${result.skipped ? "skip" : "wrote"} ${result.outputPath}`),
-});
-```
-
-Import the walker on its own from the `@kensio/colophon/content` subpath if you
-only want frontmatter discovery.
+output size next to it, named `<slug>-<size>.png`, so `post/index.md` produces
+`post/post-og.png` and `post/post-square.png`.
 
-## Templates
+There is also a programmatic API. `renderMetaImages` takes props and config and
+returns rendered bytes, and `generate` ties walking, rendering and writing
+together.
 
-| Name     | Layout                                                                       |
-| -------- | ---------------------------------------------------------------------------- |
-| `banner` | Left-aligned title with optional version, subtitle, corner badge and footer. |
-| `card`   | Minimal centred title with an optional subtitle.                             |
-| `code`   | Syntax-highlighted snippet on a rounded panel over the background.           |
+## Documentation
 
-Register your own by passing `templates` in config — a template is `{ name,
-render(context) }` returning SVG foreground content, either directly or as a
-promise. Anything you add merges over (and can override) the built-ins.
+Full documentation is in [`docs/`](./docs/).
 
-### The `code` template
-
-Put the snippet in frontmatter and name its language:
-
-```yaml
----
-title: eslint changed TypeScript files only
-slug: eslint-changed-ts-files-only
-meta_img_props:
-  template: code
-  language: bash
-  code: |
-    mapfile -t CHANGED_TS < <(
-      git diff origin/main --name-only \
-        | grep '\.ts'
-    )
----
-```
-
-| Prop       | Notes                                                            |
-| ---------- | ---------------------------------------------------------------- |
-| `code`     | The snippet. Trimmed, tabs expanded, common indentation removed. |
-| `language` | Any [Shiki language]; unknown names fall back to plain text.     |
-| `title`    | Optional heading above the panel. Omit for a bare code image.    |
-| `theme`    | Optional per-post override of `config.code.theme`.               |
-
-[Shiki language]: https://shiki.style/languages
-
-Pygments-style names carried over from an older pipeline (`text`, `console`,
-`html+handlebars`, …) are mapped onto their Shiki equivalents, so existing
-frontmatter usually needs no changes.
-
-The font size is fitted to the snippet: Colophon measures the longest line and
-the line count against a monospace grid and picks the largest size that fits on
-both axes, within `minFontScale`/`maxFontScale`. Those bounds are fractions of
-the image _width_, because that is what a feed scales a share image to — a
-landscape image would otherwise render the same snippet at half the size of its
-square counterpart. Code too long to fit at the floor is truncated with an
-ellipsis rather than shrunk into unreadability, and the panel then shrinks onto
-what's left so the code isn't marooned in a larger box.
-
-That trade matters most on the landscape sizes, which have around half the
-vertical room of the square: at the default floor an Open Graph image fits
-roughly nine lines of about sixty characters. Snippets written to that budget
-render identically at every size; longer ones keep their opening lines and lose
-the tail. Lower `minFontScale` if you would rather show the whole snippet small.
-
-Nothing in a finished image says the sample continued, so Colophon says it for
-you — a snippet that had to lose lines is reported through `onWarning`:
-
-```
-colophon: content/post/index.md: code snippet does not fit the 1200x630 image at
-a legible size: 4 of 13 lines dropped. Shorten the sample, or lower
-code.minFontScale to fit it in smaller.
-```
-
-A snippet's leading indentation is dropped before any of this, so lifting a
-sample out of a nested block costs you no width.
-
-Styling comes from `config.code`:
-
-```ts
-export default defineConfig({
-  colors: { brand: "#2563eb" },
-  footer: "example.com",
-  code: {
-    theme: "night-owl", // any bundled Shiki theme
-    fontFamily: '"JetBrains Mono", monospace',
-    charWidthRatio: 0.6, // glyph advance ÷ font size, for your monospace face
-    lineHeight: 1.55,
-    tabSize: 2,
-    cornerScale: 0.025,
-    maxFontScale: 0.075, // fractions of the image width
-    minFontScale: 0.025,
-  },
-});
-```
-
-`charWidthRatio` is how the layout knows where each token sits, so it must match
-the font actually used — `0.6` suits most monospace faces (Source Code Pro,
-Menlo, DejaVu Sans Mono); Consolas wants about `0.55`. Fonts must be installed
-where `sharp` can see them; the default stack ends in the generic `monospace`
-family so it always resolves to something.
-
-## Configuration
-
-All fields are optional; sensible defaults apply.
-
-| Option       | Default                        | Notes                                               |
-| ------------ | ------------------------------ | --------------------------------------------------- |
-| `colors`     | neutral indigo/pink            | `brand`, `brandDark`, `brandWarm`, `foreground`.    |
-| `background` | gradient derived from `colors` | Or a `{ type: "solid" }` / custom gradient.         |
-| `fontFamily` | `Arial, Helvetica, sans-serif` | Uses fonts available to `sharp`/librsvg.            |
-| `footer`     | none                           | Footer text; omit the field for none.               |
-| `badge`      | none                           | Corner badge for `banner`; omit the field for none. |
-| `code`       | `github-dark`, monospace stack | Styling for the `code` template (see above).        |
-| `onWarning`  | `console.warn`                 | Where compromises are reported (see below).         |
-| `sizes`      | `og` + `square`                | Named output sizes (see below).                     |
-| `templates`  | `banner`, `card`, `code`       | Merged over the built-ins.                          |
-
-### Warnings
-
-Some inputs can't be honoured exactly — code too long to render legibly, so far.
-Colophon renders anyway and reports the compromise through `onWarning`, which
-defaults to `console.warn`. Pass your build's logger to route them, or a no-op
-to silence them:
-
-```ts
-export default defineConfig({
-  onWarning: () => {},
-});
-```
-
-`generate` prefixes each message with the content file it came from, so a build
-over a whole tree still names the post to fix.
-
-### Output sizes and filenames
-
-Each output size is a named `{ name, width, height }`. The `name` becomes the
-filename suffix, so every image is distinct: `my-post-og.png`,
-`my-post-square.png`. The default set is one 1.91:1 Open Graph landscape and one
-1:1 square, which between them satisfy `og:image` and both `twitter:image` card
-types (`summary_large_image` reuses the landscape; `summary` uses the square).
-
-`SIZE_PRESETS` ships the common standards — compose your own set:
-
-```ts
-import { defineConfig, SIZE_PRESETS } from "@kensio/colophon";
-
-export default defineConfig({
-  sizes: [
-    SIZE_PRESETS.og, // 1200×630 — og:image (Facebook, LinkedIn, Slack, …)
-    SIZE_PRESETS.square, // 1200×1200 — Twitter summary card, universal
-    SIZE_PRESETS.twitter, // 1200×600 (2:1) — Twitter summary_large_image
-    SIZE_PRESETS.pinterest, // 1000×1500 (2:3) — Pinterest
-    { name: "hero", width: 1600, height: 900 }, // or anything custom
-  ],
-});
-```
-
-The base filename is the **post slug**: Colophon reads a top-level `slug` from
-frontmatter (SEO-friendly, keyword-rich), falling back to the file name — or the
-parent directory for `index.*` files. Point `slugField` at a different key, or
-override naming entirely with `generate`'s `outputPath` callback.
-
-### Frontmatter shape
-
-By default Colophon reads a `meta_img_props` object and a `template` field
-within it, plus a top-level `slug`. All are configurable via walk options
-(`propsKey`, `templateField`, `defaultTemplate`, `slugField`, `extensions`) so
-you can match an existing convention.
+- [Getting started](./docs/getting-started/ "Install, frontmatter, config and the CLI")
+- [Templates](./docs/templates/ "The built-in layouts and how to register your own")
+- [The code template](./docs/code-template/ "Syntax-highlighted code images")
+- [The layout toolkit](./docs/layout/ "The primitives templates are built from")
+- [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")
+- [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
+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.
 
@@ -331,26 +137,17 @@ updated PNGs so this gallery stays in sync.
   </tr>
 </table>
 
-## Upgrading from 1.x
-
-Adding the `code` template made two small breaking changes:
-
-- `Template.render` may now return `string | Promise<string>`, and `buildSvg`
-  is `async`. Custom templates that return a string still work unchanged; call
-  sites of `buildSvg` need an `await`. `renderMetaImages` and `generate` were
-  already async and are unaffected.
-- `MetaImageProps.title` is optional, and `walkContent`/`extractProps` no
-  longer skip a file that declares props without a title — a `code` post
-  describes its image entirely through `code` and `language`.
-
 ## Development
 
-- `pnpm build` — compile to `dist/`.
-- `pnpm test` / `pnpm test:coverage` — run Vitest.
-- `pnpm lint` — ESLint + Prettier check.
-- `pnpm fmt` — auto-fix.
-- `pnpm samples` — regenerate the README sample images into `docs/samples/`.
-- `pnpm check` — format, typecheck and test with coverage (run 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 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. |
 
 ## License
 

package/dist/background.d.ts

@@ -1,8 +1,13 @@
-import type { Background, Dimensions } 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.
+ *
+ * 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 declare function backgroundSvg(background: Background, dimensions: Dimensions, id: string): string;
+export declare function backgroundSvg(background: Background, dimensions: Dimensions, id: string, asset?: ImageAsset): string;
 //# sourceMappingURL=background.d.ts.map

package/dist/background.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,GACT,MAAM,CAqBR"}
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAS,MAAM,YAAY,CAAC;AAiD5E;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,EACV,KAAK,CAAC,EAAE,UAAU,GACjB,MAAM,CA8BR"}

package/dist/background.js

@@ -1,13 +1,56 @@
+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.
+ */
+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,
+        }));
+}
 /**
  * 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.
+ *
+ * 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) {
+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);
+    }
     const from = background.from ?? { x: 0, y: 0 };
     const to = background.to ?? { x: 1, y: 1 };
     const stops = background.stops

package/dist/background.js.map

@@ -1 +1 @@
-{"version":3,"file":"background.js","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAsB,EACtB,UAAsB,EACtB,EAAU;IAEV,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,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"}
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAGtE,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,SAAS,eAAe,CACtB,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;AAED;;;;;;;;;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,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/cli/args.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The parsed command line.
+ */
+export interface CliArgs {
+    readonly contentDir: string;
+    readonly configPath: string | undefined;
+    readonly overwrite: boolean;
+    readonly concurrency: number | undefined;
+}
+/** 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]\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\n  -o, --overwrite       Alias for --force\n  --concurrency <n>     How many images to render at once\n  -h, --help            Show this help\n\nDefaults:\n  contentDir            content\n  --concurrency         one per available CPU";
+/** Read the command line into the options `generate` takes. */
+export declare function parseCliArgs(argv: readonly string[]): CliArgs;
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,wEAAwE;AACxE,eAAO,MAAM,KAAK,gxBAmB4B,CAAC;AAwB/C,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4B7D"}

package/dist/cli/args.js

@@ -0,0 +1,67 @@
+/** Help text for `--help`, and for a run that asks for nothing else. */
+export const usage = `colophon: generate social meta images from frontmatter
+
+Usage:
+  colophon [contentDir] [options]
+
+Images carry a stamp of the props, config and size they came from, so a rebuild
+renders only the ones that have actually changed.
+
+Options:
+  -c, --config <path>   Load a config module. Its default export is either a
+                        ColophonConfig or a function (async or not) returning
+                        one, for a config that has to compute something.
+  -f, --force           Re-render every image, ignoring the stamps
+  -o, --overwrite       Alias for --force
+  --concurrency <n>     How many images to render at once
+  -h, --help            Show this help
+
+Defaults:
+  contentDir            content
+  --concurrency         one per available CPU`;
+/** `--overwrite` is kept as an alias so existing build scripts keep working. */
+const forceFlags = new Set(["-f", "--force", "-o", "--overwrite"]);
+/** Flags that take the next argument as their value. */
+const valueFlags = new Set(["-c", "--config", "--concurrency"]);
+/**
+ * A mistyped count would otherwise reach `generate` as `NaN` and be reported
+ * without naming the flag it came from, so it is rejected here instead.
+ */
+function parseConcurrency(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error(`Invalid value for --concurrency: "${value}"; expected a positive integer.`);
+    }
+    return parsed;
+}
+/** Read the command line into the options `generate` takes. */
+export function parseCliArgs(argv) {
+    let contentDir = "content";
+    let configPath;
+    let shouldOverwrite = false;
+    let concurrency;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg !== undefined && valueFlags.has(arg)) {
+            index += 1;
+            const value = argv[index];
+            if (value === undefined) {
+                throw new Error(`Missing value for ${arg}`);
+            }
+            if (arg === "--concurrency") {
+                concurrency = parseConcurrency(value);
+            }
+            else {
+                configPath = value;
+            }
+        }
+        else if (arg !== undefined && forceFlags.has(arg)) {
+            shouldOverwrite = true;
+        }
+        else if (arg !== undefined && !arg.startsWith("-")) {
+            contentDir = arg;
+        }
+    }
+    return { contentDir, configPath, overwrite: shouldOverwrite, concurrency };
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAUA,wEAAwE;AACxE,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;8CAmByB,CAAC;AAE/C,gFAAgF;AAChF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;AAEnE,wDAAwD;AACxD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;AAEhE;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAE7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,qCAAqC,KAAK,iCAAiC,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,IAAuB;IAClD,IAAI,UAAU,GAAG,SAAS,CAAC;IAC3B,IAAI,UAA8B,CAAC;IACnC,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,IAAI,WAA+B,CAAC;IAEpC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7C,KAAK,IAAI,CAAC,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;YAC9C,CAAC;YACD,IAAI,GAAG,KAAK,eAAe,EAAE,CAAC;gBAC5B,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACN,UAAU,GAAG,KAAK,CAAC;YACrB,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpD,eAAe,GAAG,IAAI,CAAC;QACzB,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,UAAU,GAAG,GAAG,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC;AAC7E,CAAC"}

package/dist/cli/config.d.ts

@@ -0,0 +1,12 @@
+import type { ColophonConfig } from "../types.js";
+/**
+ * Load the config module named by `--config`.
+ *
+ * The default export may be the config itself or a function returning one,
+ * possibly async. A config that has to compute something cannot be written as
+ * a literal, and without the function form such a project has to abandon the
+ * CLI and call `generate` from a script of its own, reimplementing the
+ * reporting the CLI already does along the way.
+ */
+export declare function loadConfig(configPath: string | undefined): Promise<ColophonConfig | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC;AAwBvE;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAiBrC"}

package/dist/cli/config.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * A module that exports nothing usable is a mistake rather than a config that
+ * happens to be empty: the run named the file on the command line, so falling
+ * back to the defaults would render a whole tree with none of what it asked
+ * for and say nothing about it.
+ *
+ * An array is rejected for that reason and not for its own: `validateConfig`
+ * reads the keys of what it is given, and an empty one has none, so it is the
+ * one non-config that would otherwise pass as an empty config.
+ */
+function assertConfig(value, source) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${source} is not a config object.` +
+            ` Export a ColophonConfig, or a function returning one.`);
+    }
+}
+/**
+ * Load the config module named by `--config`.
+ *
+ * The default export may be the config itself or a function returning one,
+ * possibly async. A config that has to compute something cannot be written as
+ * a literal, and without the function form such a project has to abandon the
+ * CLI and call `generate` from a script of its own, reimplementing the
+ * reporting the CLI already does along the way.
+ */
+export async function loadConfig(configPath) {
+    if (configPath === undefined) {
+        return undefined;
+    }
+    const url = pathToFileURL(path.resolve(configPath)).href;
+    const module = (await import(url));
+    const exported = module.default;
+    if (typeof exported === "function") {
+        const config = await exported();
+        assertConfig(config, `The function exported by ${configPath}`);
+        return config;
+    }
+    assertConfig(exported, `The default export of ${configPath}`);
+    return exported;
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAIzC;;;;;;;;;GASG;AACH,SAAS,YAAY,CACnB,KAAc,EACd,MAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,0BAA0B;YACjC,wDAAwD,CAC3D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,UAA8B;IAE9B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IACzD,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAsC,CAAC;IACxE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;IAEhC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAChC,YAAY,CAAC,MAAM,EAAE,4BAA4B,UAAU,EAAE,CAAC,CAAC;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,YAAY,CAAC,QAAQ,EAAE,yBAAyB,UAAU,EAAE,CAAC,CAAC;IAC9D,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}