@arraypress/covers 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `@arraypress/covers` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] — 2026-11-07
+
+### Added
+
+- **`terminal-poster`**, on the 400-wide grid (4:5, 1:1, 9:16 and A-series portrait): a terminal / crypto launch poster in acid lime (`#c8ff00`, any `ink`) on black (`ground`), set like a HUD readout. A lime bar across the top with the terminal line, a small nested-square icon and a seeded code (`480-A<3.56.7.128>`); `INIT` in outline type; a small mono log under it (`CORE REVIEW [START]`, `CORE 1`–`CORE 6 …… OK` in three columns with dot leaders, `CORES STABLE`, `RESULTS [PRNTD]`); a big lime panel with chamfered corners, a tab and a notch along its top and foot, holding the mark large in the ground colour (or, with `pixel: true`, rastered into square cells through `@logomarks/core`'s `pixelCells`, `cells` across), tiny serials mirrored in two corners and a 3 × 3 dot grid; a row of HUD glyphs (a barcode, a crosshair, an ×, a square target, two seeded two-digit numbers); the `headline` (`Launch`) huge in a lime panel, fitted to its width and stretched taller on tall canvases; a notched footer with the name and a sign-off; short ticks down both margins. Options `name`, `headline`, `ink`, `ground`, `pixel`, `cells`, and the meta strings `init`, `terminal`, `code`, `serial`, `log` (`[start, stable, results]`), `core`, `status`, `signoff`. The display face is `font` (`Rubik Mono One` by default, OFL, not bundled: register it, or Inter stands in), the small type `mono` (`Space Mono`). The code, serial and numbers follow the seed.
+
+## [1.6.1] — 2026-11-06
+
+### Added
+
+- **`image` `focus` points** (with sharp): `[x, y]` (0–1 in the photo) centres that point in the box, and `'subject'` centres a cut-out's head across (the alpha-weighted centre of the top 45% of its opaque rows), its top at the box's top. A cut-out moves freely sideways, the ground showing round it; an opaque photo keeps its box filled. Without sharp, `'subject'` falls back to `'top'` and a point to `'center'`.
+
+### Changed
+
+- **`dissolve-poster`**: the cut-out runs full bleed and is centred on its face (`focus: 'subject'`; `focus: [x, y]` overrides), so a cropped top runs off the poster instead of showing a flat cut. The fade starts lower so the eyes stay clean: from 0.5 without a title, and 0.24 above the merge with one.
+
+## [1.6.0] — 2026-11-06
+
+### Added
+
+- **`dissolve-poster`**, on the 400-wide grid (4:5, 1:1, 9:16): one flat strong ground (red `#e10a14` by default), the subject in the ink (a `cutout` or `photo` portrait, its tones mapped from the ink to the ground, or the mark large with no photo) dissolving into the ground through a growing diamond dot screen, tiny at the top of the fade and merging at its foot, a few seeded strays above. Small Swiss corner type (the name, a series or Vol. line, a credit, the year) and an optional big tight `title` along the foot sit over the dissolve; with a title the dots merge just above it. Options `ground`, `ink`, `dots` (default the ground), `direction`, `fadeStart`, `fadeEnd`, `cell`.
+- The `halftoneFade` effect from `@logomarks/image-effects` 0.4.0 on any layer, and in the schema.
+
+### Changed
+
+- Depends on `@logomarks/image-effects` `^0.4.0`.
+
+## [1.5.2] — 2026-11-06
+
+### Changed
+
+- **`fluted-poster`**: `subject: 'name'` now sets the name's initial huge behind the glass, filling the height between the year and the title (stretched taller on tall canvases), the way a single letter stays legible and glassy behind ribs; the full name stays in the title and corner type. `initial` overrides the letter (one or two characters). The whole name across the width is `subject: 'word'`. With no mark, the initial is drawn.
+- The gentle convex glass 1.5.1 gave the name is gone: every subject uses the `fluted` preset unless `preset` names another.
+
 ## [1.5.1] — 2026-11-06
 
 ### Changed

package/README.md

@@ -36,7 +36,7 @@ await writeFile('public/covers/introducing-covers.webp', webp);
 - [API](https://github.com/arraypress/covers/blob/main/docs/api.md): every export and cover option
 - [Layers](https://github.com/arraypress/covers/blob/main/docs/layers.md): mesh, grain, text, diagrams, riso inks, dithers, poster type and more
 - [Effects](https://github.com/arraypress/covers/blob/main/docs/effects.md): filters and pixel effects on any layer, masks, paints
-- [Recipes](https://github.com/arraypress/covers/blob/main/docs/recipes.md): seventeen built-ins, 90 flyers and release covers, your own
+- [Recipes](https://github.com/arraypress/covers/blob/main/docs/recipes.md): seventeen built-ins, 92 flyers and release covers, your own
 - [JSON recipes](https://github.com/arraypress/covers/blob/main/docs/json-recipes.md): a cover style as data, with no JavaScript
 - [Palettes](https://github.com/arraypress/covers/blob/main/docs/palettes.md): presets, one accent, a theme's tokens
 - [Formats, print and brand kits](https://github.com/arraypress/covers/blob/main/docs/formats.md): social sizes with safe zones, print with bleed, `kit`, `lint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/covers",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Covers, flyers, posters, release art, social formats and print stationery from one seed and a stack of layers: mesh gradients, grain, riso inks and halftones, knockout and justified type, torn paper, barcodes, safe zones and bleed, as SVG or WebP/PNG/AVIF/JPEG. Recipes are JSON. Runs in Node, browsers and Cloudflare Workers.",
   "type": "module",
   "main": "src/index.js",
@@ -86,7 +86,7 @@
   "dependencies": {
     "@arraypress/color-utils": "^1.3.0",
     "@logomarks/core": "^0.1.5",
-    "@logomarks/image-effects": "^0.3.2",
+    "@logomarks/image-effects": "^0.4.0",
     "harfbuzzjs": "^1.6.3"
   },
   "peerDependencies": {

package/recipes/flyers/dissolve-poster.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "../../schema/recipe.schema.json",
+  "name": "dissolve-poster",
+  "description": "Halftone dissolve poster: one flat strong ground (red by default), the subject in the ink over it (a portrait, cut out or plain, its tones mapped from the ink to the ground; or, with no photo, the mark large), dissolving into the ground through a growing dot screen (@logomarks/image-effects' halftoneFade): tiny dots at the top of the fade, growing and merging at its foot, a few strays above, in the ground colour unless dots names another. By default the dots begin at half the height and merge by 92%; with a title they merge just above it, so the title stands on clear ground (fadeStart and fadeEnd, 0–1, set them). A cut-out runs full bleed, centred across on its face (focus [x, y], 0–1 in the photo, overrides), so a cropped top runs off the poster. Over it, small Swiss type the dots never touch: the name and a Vol. line across the top, an optional big tight title along the foot, a credit and the year under it. Drawn on a 400-wide grid as tall as the canvas, so it sets at 4:5, 1:1 and 9:16 alike; the strays follow the seed.",
+  "params": {
+    "name": "Kestrel",
+    "series": "Vol. 07 — Dissolve",
+    "year": "2026",
+    "credit": "",
+    "title": "",
+    "ground": "#e10a14",
+    "ink": "#0a0a0a",
+    "dots": "",
+    "direction": "up",
+    "fadeStart": "",
+    "fadeEnd": "",
+    "cell": "2.2vmin",
+    "focus": ""
+  },
+  "vars": {
+    "h": { "mul": [400, { "div": ["@height", "@width"] }] },
+    "end": { "if": "fadeEnd", "then": "{fadeEnd}", "else": { "if": "title", "then": { "sub": [0.78, { "div": [40, "$h"] }] }, "else": 0.92 } },
+    "start": { "if": "fadeStart", "then": "{fadeStart}", "else": { "if": "title", "then": { "sub": ["$end", 0.24] }, "else": { "min": [0.5, { "sub": ["$end", 0.1] }] } } }
+  },
+  "layers": [
+    { "id": "ground", "type": "solid", "color": "{ground}" },
+    {
+      "id": "subject",
+      "type": "group",
+      "viewBox": [0, 0, 400, "$h"],
+      "fit": "contain",
+      "effects": [{ "kind": "halftoneFade", "color": { "if": "dots", "then": "{dots}", "else": "{ground}" }, "direction": "{direction}", "start": "$start", "end": "$end", "cell": "{cell}", "grid": "diamond", "shape": "dot", "jitter": 0.3 }],
+      "layers": [
+        { "id": "field", "type": "solid", "color": "{ground}" },
+        { "id": "cutout", "type": "image", "when": "cutout", "src": "{cutout}", "fit": "cover", "focus": { "if": "focus", "then": "{focus}", "else": "subject" }, "duotone": ["{ink}", "{ground}"] },
+        { "id": "photo", "type": "image", "when": { "all": ["photo", { "not": "cutout" }] }, "src": "{photo}", "fit": "cover", "focus": { "if": "focus", "then": "{focus}", "else": "center" }, "duotone": ["{ink}", "{ground}"] },
+        { "id": "mark", "type": "outline", "when": { "all": ["mark", { "not": "cutout" }, { "not": "photo" }] }, "markup": "{mark}", "lines": 0, "x": 40, "y": 60, "width": 320, "height": { "sub": ["$h", 120] }, "color": "{ink}" }
+      ]
+    },
+    {
+      "id": "type",
+      "type": "group",
+      "viewBox": [0, 0, 400, "$h"],
+      "fit": "contain",
+      "layers": [
+        { "id": "name", "type": "text", "content": "{name}", "when": "name", "font": "Inter Tight", "weight": 700, "size": 8, "letterSpacing": 0, "x": 16, "y": 24, "maxWidth": 180, "maxLines": 1, "color": "{ink}" },
+        { "id": "series", "type": "text", "content": "{series}", "when": "series", "font": "Inter Tight", "weight": 500, "size": 8, "letterSpacing": 0, "x": 384, "y": 24, "align": "right", "maxWidth": 180, "maxLines": 1, "color": "{ink}" },
+        {
+          "id": "title",
+          "type": "text",
+          "content": "{title}",
+          "when": "title",
+          "transform": "uppercase",
+          "font": "Inter Tight",
+          "weight": 800,
+          "size": 80,
+          "lineHeight": 0.86,
+          "letterSpacing": -0.05,
+          "fit": "width",
+          "maxWidth": 368,
+          "maxHeight": { "mul": ["$h", 0.22] },
+          "anchor": "bottom-left",
+          "margin": 0,
+          "offset": { "x": 16, "y": -34 },
+          "color": "{ink}"
+        },
+        { "id": "credit", "type": "text", "content": { "if": "credit", "then": "{credit}", "else": "Design — {name}" }, "font": "Inter Tight", "weight": 500, "size": 7, "letterSpacing": 0, "x": 16, "y": { "sub": ["$h", 16] }, "maxWidth": 200, "maxLines": 1, "color": "{ink}" },
+        { "id": "year", "type": "text", "content": "{year}", "when": "year", "font": "Inter Tight", "weight": 500, "size": 7, "letterSpacing": 0, "x": 384, "y": { "sub": ["$h", 16] }, "align": "right", "maxWidth": 100, "maxLines": 1, "color": "{ink}" }
+      ]
+    }
+  ]
+}

package/recipes/flyers/fluted-poster.json

@@ -1,11 +1,12 @@
 {
   "$schema": "../../schema/recipe.schema.json",
   "name": "fluted-poster",
-  "description": "Fluted glass poster: the mark (or the name, set huge) in white on black, seen through reeded glass (@logomarks/image-effects' fluted effect: by default its fluted preset for a mark, and gentler glass for the name, 12 wide convex ribs at light refraction (0.15) and little defocus, so the word steps at the rib edges but never doubles; a preset given, fluted, reeded-deep, reeded-prism or reeded-soft, is used as it is), with a soft light in one accent colour behind it (none with accent \"\"). Over the glass, small Swiss type stays vector: the year stacked large top-left, the series top-right, a two-line title bottom-left with a glitched || ornament of plain bars right of it in the accent, credits and an edition line along the foot. The glass is rastered at the output size and embedded; the type is outlines. Drawn on a 400-wide grid as tall as the canvas, so it sets at 4:5, 1:1, 9:16 and A-series portrait alike; the ornament's glitch follows the seed.",
+  "description": "Fluted glass poster: a subject in white on black, seen through reeded glass (@logomarks/image-effects' fluted effect, its fluted preset unless preset names another: reeded-deep, reeded-prism, reeded-soft): the mark (subject 'mark', the default), the name's initial set huge, filling the height between the year and the title (about two thirds of a 4:5 poster, three quarters of a 9:16 one, stretched taller there) (subject 'name', or with no mark; initial overrides it, one or two characters), or the whole name across the width (subject 'word'). A soft light in one accent colour sits behind it (none with accent \"\"). Over the glass, small Swiss type stays vector: the year stacked large top-left, the series top-right, a two-line title bottom-left with a glitched || ornament of plain bars right of it in the accent, credits and an edition line along the foot. The glass is rastered at the output size and embedded; the type is outlines. Drawn on a 400-wide grid as tall as the canvas, so it sets at 4:5, 1:1, 9:16 and A-series portrait alike; the ornament's glitch follows the seed.",
   "params": {
     "name": "Kestrel",
     "subject": "mark",
     "preset": "",
+    "initial": "",
     "title": ["Through", "the glass"],
     "year": "2026",
     "series": "",
@@ -31,14 +32,23 @@
       "type": "group",
       "viewBox": [0, 0, 400, "$h"],
       "fit": "contain",
-      "effects": [{ "kind": "fluted", "preset": { "if": "preset", "then": "{preset}", "else": "fluted" }, "profile": { "if": { "all": [{ "any": [{ "subject": "name" }, { "not": "mark" }] }, { "not": "preset" }] }, "then": "convex" }, "ribs": { "if": { "all": [{ "any": [{ "subject": "name" }, { "not": "mark" }] }, { "not": "preset" }] }, "then": 12 }, "refraction": { "if": { "all": [{ "any": [{ "subject": "name" }, { "not": "mark" }] }, { "not": "preset" }] }, "then": 0.15 }, "stretch": { "if": { "all": [{ "any": [{ "subject": "name" }, { "not": "mark" }] }, { "not": "preset" }] }, "then": "0.4vmin" }, "chroma": { "if": { "all": [{ "any": [{ "subject": "name" }, { "not": "mark" }] }, { "not": "preset" }] }, "then": 0.2 } }],
+      "effects": [{ "kind": "fluted", "preset": { "if": "preset", "then": "{preset}", "else": "fluted" } }],
       "layers": [
         { "id": "light", "type": "radial", "when": "accent", "x": 0.5, "y": 0.47, "colors": ["{accent}", "{ground}"], "radius": "52vmin", "opacity": 0.75 },
-        { "id": "mark", "type": "outline", "when": { "all": ["mark", { "not": { "subject": "name" } }] }, "markup": "{mark}", "lines": 0, "x": 70, "y": { "sub": [{ "mul": ["$h", 0.47] }, 130] }, "width": 260, "height": 260, "color": "{ink}" },
+        { "id": "mark", "type": "outline", "when": { "all": ["mark", { "subject": "mark" }] }, "markup": "{mark}", "lines": 0, "x": 70, "y": { "sub": [{ "mul": ["$h", 0.47] }, 130] }, "width": 260, "height": 260, "color": "{ink}" },
+        {
+          "id": "initial",
+          "type": "group",
+          "when": { "any": [{ "subject": "name" }, { "all": [{ "not": "mark" }, { "subject": "mark" }] }] },
+          "transform": { "scale": [1, "$tall"], "origin": [200, { "div": [{ "sub": ["$h", 36] }, 2] }] },
+          "layers": [
+            { "id": "letter", "type": "text", "content": { "if": "initial", "then": { "slice": ["{initial}", 0, 2] }, "else": { "slice": ["{name}", 0, 1] } }, "transform": "uppercase", "font": "Inter Tight", "weight": 800, "size": 400, "lineHeight": 0.73, "letterSpacing": -0.04, "fit": "width", "maxWidth": 330, "maxHeight": { "div": [{ "sub": ["$h", 164] }, "$tall"] }, "anchor": "center", "margin": 0, "offset": { "x": 0, "y": -18 }, "color": "{ink}" }
+          ]
+        },
         {
           "id": "word",
           "type": "group",
-          "when": { "any": [{ "subject": "name" }, { "not": "mark" }] },
+          "when": { "subject": "word" },
           "transform": { "scale": [1, "$tall"], "origin": [200, { "mul": ["$h", 0.47] }] },
           "layers": [
             { "id": "name", "type": "text", "content": "{name}", "transform": "uppercase", "font": "Inter Tight", "weight": 800, "size": 120, "lineHeight": 0.9, "letterSpacing": -0.05, "fit": "width", "maxWidth": 360, "maxHeight": { "div": [{ "mul": ["$h", 0.42] }, "$tall"] }, "anchor": "center", "margin": 0, "offset": { "x": 0, "y": { "mul": ["$h", -0.03] } }, "color": "{ink}" }

package/recipes/flyers/terminal-poster.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "../../schema/recipe.schema.json",
+  "name": "terminal-poster",
+  "description": "Terminal launch poster: acid lime (any ink) on black, set like a HUD readout. A lime bar across the top with the terminal line, a small nested-square icon and a seeded code (480-A<3.56.7.128>); INIT in outline type; a small mono log under it (CORE REVIEW [START], CORE 1–6 … OK in three columns with dot leaders, CORES STABLE, RESULTS [PRNTD]); a big lime panel with chamfered corners, a tab and a notch along its top and foot, holding the mark large in the ground colour (or, with pixel: true, rastered into square cells, @logomarks/core's pixelCells), tiny serials mirrored in two corners and a 3 × 3 dot grid; a row of HUD glyphs (a barcode, a crosshair, an ×, a square target, two seeded two-digit numbers); the headline huge in a lime panel, fitted to its width; and a notched lime footer with the name. Short ticks run down both margins. The display face is font (Rubik Mono One by default: wide, mono, OFL; register it, or it falls back to Inter); the small type is mono (Space Mono). Drawn on a 400-wide grid as tall as the canvas, so it sets at 4:5, 1:1, 9:16 and A-series portrait alike; the code, serial and numbers follow the seed.",
+  "params": { "name": "Kestrel", "headline": "Launch", "init": "Init", "terminal": "Public access terminal", "code": "", "serial": "", "log": ["Core review [start]", "Cores stable", "Results [prntd]"], "core": "Core", "status": "OK", "signoff": "End of line", "pixel": false, "cells": 20, "font": "Rubik Mono One", "mono": "Space Mono", "ink": "#c8ff00", "ground": "#000000" },
+  "vars": {
+    "h": { "mul": [400, { "div": ["@height", "@width"] }] },
+    "tall": { "min": [1.45, { "max": [0.9, { "div": ["$h", 500] }] }] },
+    "pt": 131,
+    "fb": { "sub": ["$h", 10] },
+    "ft": { "sub": ["$h", 24] },
+    "hb": { "sub": ["$h", 32] },
+    "ht": { "sub": [{ "sub": ["$h", 32] }, { "mul": [66, "$tall"] }] },
+    "gy": { "sub": ["$ht", 30] },
+    "pb": { "sub": ["$ht", 42] },
+    "c1": { "int": [100, 999] },
+    "c2": { "pick": ["A", "B", "C", "D", "E", "F", "H", "K", "M", "R", "X"] },
+    "c3": { "int": [1, 9] },
+    "c4": { "int": [10, 99] },
+    "c5": { "int": [1, 9] },
+    "c6": { "int": [100, 255] },
+    "s1": { "int": [1000, 9999] },
+    "s2": { "pick": ["A", "C", "K", "R", "T", "X", "Z"] },
+    "s3": { "int": [10, 99] },
+    "s4": { "int": [10, 99] },
+    "v1": { "int": [1, 9] },
+    "v2": { "int": [10, 99] },
+    "n1": { "int": [10, 99] },
+    "n2": { "int": [10, 99] }
+  },
+  "layers": [
+    { "id": "ground", "type": "solid", "color": "{ground}" },
+    {
+      "id": "poster",
+      "type": "group",
+      "viewBox": [0, 0, 400, "$h"],
+      "fit": "contain",
+      "layers": [
+        { "id": "ticks", "type": "repeat", "count": { "floor": { "div": [{ "sub": ["$h", 28] }, 6] } }, "x": 0, "y": 14, "step": [0, 6], "layer": { "type": "shape", "items": [{ "kind": "line", "x1": 5, "y1": 0, "x2": "{#i % 5 ? 8 : 10}", "y2": 0 }, { "kind": "line", "x1": 395, "y1": 0, "x2": "{#i % 5 ? 392 : 390}", "y2": 0 }], "stroke": "{ink}", "strokeWidth": 0.6, "opacity": 0.7 } },
+        { "id": "band", "type": "shape", "kind": "polygon", "points": [[16, 14], [384, 14], [384, 26], [378, 32], [16, 32]], "fill": "{ink}" },
+        { "id": "icon", "type": "shape", "items": [{ "kind": "rect", "x": 21.5, "y": 17.5, "width": 11, "height": 11, "fill": "none", "stroke": "{ground}", "strokeWidth": 1 }, { "kind": "rect", "x": 24.5, "y": 20.5, "width": 5, "height": 5, "fill": "{ground}" }], "fill": "{ground}" },
+        { "id": "terminal", "type": "text", "content": "{terminal}", "font": "{mono}", "weight": 700, "size": 7.5, "letterSpacing": 0.02, "x": 38, "y": 26, "maxWidth": 200, "maxLines": 1, "color": "{ground}", "transform": "uppercase" },
+        { "id": "code", "type": "text", "content": { "if": "code", "then": "{code}", "else": { "join": [["$c1", "-", "$c2", "<", "$c3", ".", "$c4", ".", "$c5", ".", "$c6", ">"], ""] } }, "font": "{mono}", "weight": 700, "size": 7.5, "letterSpacing": 0.02, "x": 376, "y": 26, "maxWidth": 130, "maxLines": 1, "color": "{ground}", "align": "right" },
+        { "id": "init", "type": "text", "content": "{init}", "when": "init", "transform": "uppercase", "font": "{font}", "weight": 700, "size": 34, "letterSpacing": 0.04, "x": 15, "y": 72, "maxWidth": 200, "maxLines": 1, "fill": "none", "stroke": "{ink}", "strokeWidth": 0.8, "color": "{ink}" },
+        { "id": "boot", "type": "text", "content": { "join": [["SYS", "$v1", ".", "$v2", " // ", "{name}"], ""] }, "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 384, "y": 52, "maxWidth": 170, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase", "opacity": 0.75 },
+        { "id": "rule", "type": "shape", "kind": "line", "x1": 214, "y1": 61, "x2": 384, "y2": 61, "stroke": "{ink}", "strokeWidth": 0.6, "dash": [1.2, 1.6] },
+        { "id": "mode", "type": "text", "content": { "join": [["RUN ", "$n1", "/", "$n2", " ▶"], ""] }, "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 384, "y": 72, "maxWidth": 170, "maxLines": 1, "color": "{ink}", "align": "right", "opacity": 0.75 },
+        { "id": "start", "type": "text", "content": "{log.0}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 16, "y": 88, "maxWidth": 170, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "core1", "type": "text", "content": "{core} 1", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 16, "y": 99, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok1", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 134, "y": 99, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        { "id": "core2", "type": "text", "content": "{core} 2", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 141, "y": 99, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok2", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 259, "y": 99, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        { "id": "core3", "type": "text", "content": "{core} 3", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 266, "y": 99, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok3", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 384, "y": 99, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        { "id": "core4", "type": "text", "content": "{core} 4", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 16, "y": 108, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok4", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 134, "y": 108, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        { "id": "core5", "type": "text", "content": "{core} 5", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 141, "y": 108, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok5", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 259, "y": 108, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        { "id": "core6", "type": "text", "content": "{core} 6", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 266, "y": 108, "maxWidth": 70, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "ok6", "type": "text", "content": "{status}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 384, "y": 108, "maxWidth": 40, "maxLines": 1, "color": "{ink}", "align": "right", "transform": "uppercase" },
+        {
+          "id": "leaders",
+          "type": "shape",
+          "items": [
+            { "kind": "line", "x1": "{layout.core1.right + 3}", "y1": 98.6, "x2": "{layout.ok1.left - 3}", "y2": 98.6 },
+            { "kind": "line", "x1": "{layout.core2.right + 3}", "y1": 98.6, "x2": "{layout.ok2.left - 3}", "y2": 98.6 },
+            { "kind": "line", "x1": "{layout.core3.right + 3}", "y1": 98.6, "x2": "{layout.ok3.left - 3}", "y2": 98.6 },
+            { "kind": "line", "x1": "{layout.core4.right + 3}", "y1": 107.6, "x2": "{layout.ok4.left - 3}", "y2": 107.6 },
+            { "kind": "line", "x1": "{layout.core5.right + 3}", "y1": 107.6, "x2": "{layout.ok5.left - 3}", "y2": 107.6 },
+            { "kind": "line", "x1": "{layout.core6.right + 3}", "y1": 107.6, "x2": "{layout.ok6.left - 3}", "y2": 107.6 }
+          ],
+          "stroke": "{ink}",
+          "strokeWidth": 0.9,
+          "dash": [0.9, 1.5]
+        },
+        { "id": "stable", "type": "text", "content": "{log.1}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 16, "y": 119, "maxWidth": 170, "maxLines": 1, "color": "{ink}", "transform": "uppercase" },
+        { "id": "results", "type": "text", "content": "{log.2}", "font": "{mono}", "weight": 700, "size": 6, "letterSpacing": 0.02, "x": 384, "y": 119, "maxWidth": 170, "maxLines": 1, "color": "{ink}", "transform": "uppercase", "align": "right" },
+        {
+          "id": "panel",
+          "type": "shape",
+          "kind": "polygon",
+          "points": [
+            [16, { "add": ["$pt", 8] }],
+            [24, "$pt"],
+            [60, "$pt"],
+            [65, { "add": ["$pt", -5] }],
+            [136, { "add": ["$pt", -5] }],
+            [141, "$pt"],
+            [250, "$pt"],
+            [255, { "add": ["$pt", 5] }],
+            [300, { "add": ["$pt", 5] }],
+            [305, "$pt"],
+            [384, "$pt"],
+            [384, { "add": ["$pb", -8] }],
+            [376, "$pb"],
+            [340, "$pb"],
+            [335, { "add": ["$pb", 5] }],
+            [264, { "add": ["$pb", 5] }],
+            [259, "$pb"],
+            [150, "$pb"],
+            [145, { "add": ["$pb", -5] }],
+            [100, { "add": ["$pb", -5] }],
+            [95, "$pb"],
+            [16, "$pb"]
+          ],
+          "fill": "{ink}"
+        },
+        { "id": "mark", "type": "outline", "when": { "all": ["mark", { "not": "pixel" }] }, "markup": "{mark}", "lines": 0, "x": 40, "y": { "add": ["$pt", 22] }, "width": 320, "height": { "sub": [{ "sub": ["$pb", "$pt"] }, 44] }, "color": "{ground}" },
+        { "id": "pixels", "type": "mosaic", "when": { "all": ["mark", "pixel"] }, "markup": "{mark}", "x": 40, "y": { "add": ["$pt", 22] }, "width": 320, "height": { "sub": [{ "sub": ["$pb", "$pt"] }, 44] }, "cells": "{cells}", "drop": 0, "gap": 0.08, "color": "{ground}" },
+        { "id": "serial", "type": "text", "content": { "if": "serial", "then": "{serial}", "else": { "join": [["SN.", "$s1", "-", "$s2", "$s3", " / LOT ", "$s4"], ""] } }, "font": "{mono}", "weight": 700, "size": 5, "letterSpacing": 0.02, "x": 26, "y": { "add": ["$pt", 15] }, "maxWidth": 120, "maxLines": 1, "color": "{ground}" },
+        {
+          "id": "mirror",
+          "type": "group",
+          "transform": { "rotate": 180, "origin": [374, { "sub": ["$pb", 15] }] },
+          "layers": [{ "id": "serialMirror", "type": "text", "content": { "if": "serial", "then": "{serial}", "else": { "join": [["SN.", "$s1", "-", "$s2", "$s3", " / LOT ", "$s4"], ""] } }, "font": "{mono}", "weight": 700, "size": 5, "letterSpacing": 0.02, "x": 374, "y": { "sub": ["$pb", 15] }, "maxWidth": 120, "maxLines": 1, "color": "{ground}" }]
+        },
+        {
+          "id": "dots",
+          "type": "shape",
+          "fill": "{ground}",
+          "items": [
+            { "kind": "circle", "cx": 362, "cy": { "add": ["$pt", 10] }, "r": 1.1 },
+            { "kind": "circle", "cx": 368, "cy": { "add": ["$pt", 10] }, "r": 1.1 },
+            { "kind": "circle", "cx": 374, "cy": { "add": ["$pt", 10] }, "r": 1.1 },
+            { "kind": "circle", "cx": 362, "cy": { "add": ["$pt", 16] }, "r": 1.1 },
+            { "kind": "circle", "cx": 368, "cy": { "add": ["$pt", 16] }, "r": 1.1 },
+            { "kind": "circle", "cx": 374, "cy": { "add": ["$pt", 16] }, "r": 1.1 },
+            { "kind": "circle", "cx": 362, "cy": { "add": ["$pt", 22] }, "r": 1.1 },
+            { "kind": "circle", "cx": 368, "cy": { "add": ["$pt", 22] }, "r": 1.1 },
+            { "kind": "circle", "cx": 374, "cy": { "add": ["$pt", 22] }, "r": 1.1 }
+          ]
+        },
+        { "id": "barcode", "type": "barcode", "kind": "seeded", "x": 16, "y": "$gy", "width": 76, "height": 18, "color": "{ink}" },
+        {
+          "id": "glyphs",
+          "type": "shape",
+          "stroke": "{ink}",
+          "strokeWidth": 1,
+          "fill": "none",
+          "items": [
+            { "kind": "circle", "cx": 116, "cy": { "add": ["$gy", 9] }, "r": 6 },
+            { "kind": "line", "x1": 106, "y1": { "add": ["$gy", 9] }, "x2": 126, "y2": { "add": ["$gy", 9] } },
+            { "kind": "line", "x1": 116, "y1": { "add": ["$gy", -1] }, "x2": 116, "y2": { "add": ["$gy", 19] } },
+            { "kind": "line", "x1": 140, "y1": { "add": ["$gy", 3] }, "x2": 152, "y2": { "add": ["$gy", 15] } },
+            { "kind": "line", "x1": 152, "y1": { "add": ["$gy", 3] }, "x2": 140, "y2": { "add": ["$gy", 15] } },
+            { "kind": "rect", "x": 166.5, "y": { "add": ["$gy", 2.5] }, "width": 13, "height": 13 },
+            { "kind": "rect", "x": 171, "y": { "add": ["$gy", 7] }, "width": 4, "height": 4, "fill": "{ink}", "stroke": "none" }
+          ]
+        },
+        { "id": "readout", "type": "text", "content": [{ "join": [["X ", "$c4", ".", "$c6"], ""] }, { "join": [["Y ", "$s3", ".", "$c1"], ""] }], "font": "{mono}", "weight": 700, "size": 5.5, "letterSpacing": 0.02, "x": 196, "y": { "add": ["$gy", 7.5] }, "maxWidth": 60, "maxLines": 2, "color": "{ink}", "lineHeight": 1.45, "opacity": 0.75 },
+        { "id": "n1", "type": "text", "content": "$n1", "font": "{font}", "weight": 700, "size": 15, "letterSpacing": 0, "x": 330, "y": { "add": ["$gy", 16.5] }, "align": "right", "maxWidth": 60, "maxLines": 1, "color": "{ink}" },
+        { "id": "slash", "type": "shape", "kind": "line", "x1": 340, "y1": { "add": ["$gy", 17] }, "x2": 348, "y2": { "add": ["$gy", 1] }, "stroke": "{ink}", "strokeWidth": 1 },
+        { "id": "n2", "type": "text", "content": "$n2", "font": "{font}", "weight": 700, "size": 15, "letterSpacing": 0, "x": 384, "y": { "add": ["$gy", 16.5] }, "align": "right", "maxWidth": 60, "maxLines": 1, "color": "{ink}" },
+        { "id": "headPanel", "type": "shape", "kind": "polygon", "points": [[16, "$ht"], [22, "$ht"], [26, { "add": ["$ht", -4] }], [84, { "add": ["$ht", -4] }], [88, "$ht"], [372, "$ht"], [384, { "add": ["$ht", 12] }], [384, "$hb"], [16, "$hb"]], "fill": "{ink}" },
+        {
+          "id": "stretch",
+          "type": "group",
+          "transform": { "scale": [1, "$tall"], "origin": [200, { "div": [{ "add": ["$ht", "$hb"] }, 2] }] },
+          "layers": [
+            {
+              "id": "headline",
+              "type": "text",
+              "content": "{headline}",
+              "when": "headline",
+              "transform": "uppercase",
+              "font": "{font}",
+              "weight": 800,
+              "size": 80,
+              "lineHeight": 1,
+              "letterSpacing": -0.01,
+              "fit": "width",
+              "maxWidth": 352,
+              "maxHeight": { "div": [{ "sub": [{ "sub": ["$hb", "$ht"] }, 18] }, "$tall"] },
+              "maxLines": 1,
+              "anchor": "center",
+              "margin": 0,
+              "offset": { "x": 0, "y": { "sub": [{ "div": [{ "add": ["$ht", "$hb"] }, 2] }, { "div": ["$h", 2] }] } },
+              "color": "{ground}"
+            }
+          ]
+        },
+        { "id": "footer", "type": "shape", "kind": "polygon", "points": [[16, "$ft"], [206, "$ft"], [211, { "add": ["$ft", 4] }], [252, { "add": ["$ft", 4] }], [257, "$ft"], [300, "$ft"], [306, { "add": ["$ft", 6] }], [384, { "add": ["$ft", 6] }], [384, "$fb"], [16, "$fb"]], "fill": "{ink}" },
+        { "id": "name", "type": "text", "content": "{name}", "font": "{mono}", "weight": 700, "size": 7, "letterSpacing": 0.02, "x": 22, "y": { "sub": ["$h", 14] }, "maxWidth": 180, "maxLines": 1, "color": "{ground}", "transform": "uppercase", "when": "name" },
+        { "id": "signoff", "type": "text", "content": "{signoff}", "font": "{mono}", "weight": 700, "size": 5.5, "letterSpacing": 0.02, "x": 378, "y": { "sub": ["$h", 12] }, "maxWidth": 76, "maxLines": 1, "color": "{ground}", "transform": "uppercase", "align": "right", "when": "signoff" }
+      ]
+    }
+  ]
+}

package/schema/recipe.schema.json

@@ -739,6 +739,7 @@
             "vhs",
             "jpeg",
             "print",
+            "halftoneFade",
             "newsprint",
             "chromatic",
             "rgbSplit",
@@ -4317,6 +4318,97 @@
             }
           }
         },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "halftoneFade"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "color": {
+                "$ref": "#/$defs/value",
+                "description": "The dots: a colour, none (they erase), or the colour round the edge (default)."
+              },
+              "direction": {
+                "$ref": "#/$defs/value",
+                "description": "up (default: dissolves from the bottom) | down | left | right | radial (from the edges in)"
+              },
+              "angle": {
+                "$ref": "#/$defs/value",
+                "description": "Degrees the dissolve travels (0 along x, 90 down); wins over direction."
+              },
+              "start": {
+                "$ref": "#/$defs/value",
+                "description": "0–1 along the fade: where the dots begin. Default 0.45."
+              },
+              "end": {
+                "$ref": "#/$defs/value",
+                "description": "0–1: where they have merged into solid. Default 0.92."
+              },
+              "curve": {
+                "$ref": "#/$defs/value",
+                "description": "linear (default) | ease-in | ease-out | smooth"
+              },
+              "cell": {
+                "$ref": "#/$defs/value",
+                "description": "Length: the dot pitch. Default \"2.2vmin\"."
+              },
+              "grid": {
+                "$ref": "#/$defs/value",
+                "description": "diamond (default, a 45° screen) | square"
+              },
+              "shape": {
+                "$ref": "#/$defs/value",
+                "description": "dot (default) | square | diamond"
+              },
+              "jitter": {
+                "$ref": "#/$defs/value",
+                "description": "0–1: dot sizes varied, a few strays above start."
+              },
+              "seed": {
+                "$ref": "#/$defs/value",
+                "description": "Number or string."
+              },
+              "mask": {
+                "$ref": "#/$defs/value",
+                "description": "{ gradient: linear | radial | band, from, to, center, angle, aspect, invert, ease } or { layers, invert }: where the effect applies."
+              },
+              "colorSpace": {
+                "$ref": "#/$defs/value",
+                "description": "sRGB (default) | linearRGB: where filter primitives do their arithmetic."
+              },
+              "pad": {
+                "$ref": "#/$defs/value",
+                "description": "Filter region padding, a fraction of the canvas."
+              }
+            },
+            "propertyNames": {
+              "enum": [
+                "color",
+                "direction",
+                "angle",
+                "start",
+                "end",
+                "curve",
+                "cell",
+                "grid",
+                "shape",
+                "jitter",
+                "seed",
+                "kind",
+                "mask",
+                "colorSpace",
+                "pad"
+              ]
+            }
+          }
+        },
         {
           "if": {
             "properties": {
@@ -5662,7 +5754,7 @@
               },
               "focus": {
                 "$ref": "#/$defs/value",
-                "description": "An anchor, attention or entropy."
+                "description": "An anchor, attention or entropy; [x, y] (0–1 in the photo) to centre that point; subject: a cut-out's head centred across, its top at the box's top."
               },
               "region": {
                 "$ref": "#/$defs/value",

package/src/index.d.ts

@@ -259,8 +259,8 @@ export interface ImageLayer extends BaseLayer {
   y?: Length | `${number}%`;
   width?: Length | `${number}%`;
   height?: Length | `${number}%`;
-  /** Crop focus: an anchor, or (with sharp) `'attention'` / `'entropy'`. Default `'center'`. */
-  focus?: Anchor | 'attention' | 'entropy';
+  /** Crop focus: an anchor, or (with sharp) `'attention'` / `'entropy'`; or (with sharp) a point centred in the box, `[x, y]` 0–1 in the photo, or `'subject'`, a cut-out's head centred across with its top at the box's top. Default `'center'`. */
+  focus?: Anchor | 'attention' | 'entropy' | 'subject' | [number, number];
   /** Default the whole canvas. */
   region?: Region;
   /** Map tones to two colours (shadows, highlights); `true` derives them from the palette. */

package/src/layer-options.js

@@ -14,7 +14,7 @@ export const LAYER_OPTIONS = {
   radial: { colors: 'Centre → edge.', x: 'Centre x, 0–1.', y: 'Centre y, 0–1.', radius: 'Length. Default "80vmax".', ease: 'Default true.' },
   mesh: { colors: 'Blob colours.', hues: 'Distinct colours to use. Default 3.', hueSpan: 'Keep the colours within this many degrees of hue (OKLCH): neighbouring hues only.', count: 'Blobs. Default 4.', blur: 'Length. Default "11vmax".', spread: '0–1. Default 1 (sweep), 0.7 (ring).', size: '[min, max] radius, fractions of the longer side.', base: 'Fill under the fields: "auto" (a gradient across the sweep between the first two colours; default), "bg", a colour, or null.', arrangement: 'sweep (default: long fields along one direction) | ring', angle: 'Sweep direction in degrees. Default seeded.', streak: 'How much more the sweep blurs along than across. Default 1.5.', tone: '{ l: [min, max], c: [min, max] }: pull colours into an OKLCH band.', fold: 'true or { color, to, position, bend, softness, sheen }: a second field meeting the first along a soft curve.', streaks: 'Thin light motion streaks along the sweep. Default 0.', from: 'A photo (path or bytes) to take the colours from (needs sharp).', blobs: 'Explicit [{ x, y, r, squash, rotate, color, opacity }].' },
   stripes: { direction: 'vertical | horizontal | diagonal', angle: 'For diagonal.', count: 'Stripes. Default 8.', widths: 'even | random | taper | [weights]', taper: 'Ratio for widths: taper.', colors: 'Cycled.', gap: 'Length.', radius: 'Length.', region: '{ x, y, width, height } fractions.', regionRadius: 'Length.' },
-  image: { x: 'Box left, px or "%" (with y, width, height: an explicit box instead of region).', y: 'Box top.', width: 'Box width.', height: 'Box height.', src: 'A local path, data: URI, URL (where allowed) or bytes ("{image}").', fit: 'cover | contain | stretch', focus: 'An anchor, attention or entropy.', region: 'Fractions.', duotone: 'true or [shadow, highlight].', grayscale: 'boolean', normalize: 'Stretch tones first.', tint: 'A colour or { color, amount, blend }.', blur: 'Length.' },
+  image: { x: 'Box left, px or "%" (with y, width, height: an explicit box instead of region).', y: 'Box top.', width: 'Box width.', height: 'Box height.', src: 'A local path, data: URI, URL (where allowed) or bytes ("{image}").', fit: 'cover | contain | stretch', focus: 'An anchor, attention or entropy; [x, y] (0–1 in the photo) to centre that point; subject: a cut-out\'s head centred across, its top at the box\'s top.', region: 'Fractions.', duotone: 'true or [shadow, highlight].', grayscale: 'boolean', normalize: 'Stretch tones first.', tint: 'A colour or { color, amount, blend }.', blur: 'Length.' },
   grain: { amount: '0–1. Default 0.08.', size: 'Grain px. Default 1.', monochrome: 'Default true.', vary: '"edges": heavier toward the edges (spray paint).' },
   pattern: { kind: 'grid | dots | lines | rings | waves', size: 'Cell. Length.', stroke: 'Length.', color: 'Default @text.', angle: 'For lines.', center: '{ x, y } fractions.', wavelength: 'Length.', amplitude: 'Length.', fade: 'none | radial | edges | top | bottom | left | right', dash: 'dotted | dashed | [on, off] lengths.', divisions: 'Grid/lines: N equal cells (inner lines only) instead of size; [cols, rows] for a design grid.', gaps: '[{ x, y, width, height }] fractions the lines break around.', region: 'Fractions.' },
   shapes: { kind: 'circle | square | pill | mixed', count: 'Default 6.', size: '[min, max] lengths.', colors: 'Cycled.', placement: 'scatter | row | column', items: '[{ kind, x, y, size, color, rotate, opacity }]', region: 'Fractions.', rotate: 'Tilt squares and pills.', radius: 'Square corner, fraction of size.', outline: 'true or a width.' },

package/src/layers/focal.d.ts

@@ -0,0 +1,8 @@
+// Placing a photo on a point of it: a focus [x, y], or a cut-out's head.
+
+/** A cut-out's head (the alpha-weighted centre of the top 45% of its opaque rows), 0–1 in the photo; null with no transparency. */
+export function subjectFocus(sharp: any, bytes: Uint8Array): Promise<[number, number] | null>;
+/** The drawn box (relative to the box) that centres a point of a `sw` × `sh` photo; `cover` keeps the box filled except sideways when `free` (a cut-out). */
+export function focalBox(box: { width: number; height: number }, sw: number, sh: number, fit: 'cover' | 'contain', point: [number, number], free?: boolean): { x: number; y: number; width: number; height: number };
+/** A `W` × `H` raster with the photo drawn at a box (raster pixels), the rest clear, as a sharp pipeline. */
+export function drawAt(sharp: any, bytes: Uint8Array, W: number, H: number, at: { x: number; y: number; width: number; height: number }): Promise<any>;

package/src/layers/focal.js

@@ -0,0 +1,109 @@
+/**
+ * Placing a photo on a point of it: a focus `[x, y]` (0–1 in the photo),
+ * or `'subject'`, a cut-out's head, found from its transparency. Used by
+ * the `image` layer when sharp is there to draw the pixels.
+ *
+ * @module layers/focal
+ */
+
+/** The share of a cut-out's opaque height, from its top, taken as its head. */
+const HEAD = 0.45;
+/** Rows and columns the transparency is read at. */
+const PROBE = 160;
+
+/**
+ * Where a cut-out's head is: the alpha-weighted centre of the top 45% of
+ * its opaque rows, as `[x, y]` fractions of the photo. Null for a photo
+ * with no transparency to read (an ordinary photo: no subject to find).
+ *
+ * @param {any} sharp - The sharp module.
+ * @param {Uint8Array} bytes
+ * @returns {Promise<[number, number] | null>}
+ *
+ * @example
+ * await subjectFocus(sharp, cutoutPng); // [0.56, 0.21]
+ */
+export async function subjectFocus(sharp, bytes) {
+  const meta = await sharp(bytes).metadata();
+  if (!meta.hasAlpha) return null;
+  const { data, info } = await sharp(bytes).rotate().ensureAlpha().resize(PROBE, PROBE, { fit: 'fill' }).raw().toBuffer({ resolveWithObject: true });
+  const { width: w, height: h, channels: c } = info;
+  const alpha = (/** @type {number} */ x, /** @type {number} */ y) => data[(y * w + x) * c + 3] / 255;
+  // The opaque rows: those with a few solid pixels.
+  const rows = [];
+  for (let y = 0; y < h; y++) {
+    let s = 0;
+    for (let x = 0; x < w; x++) s += alpha(x, y);
+    if (s >= 2) rows.push(y);
+  }
+  let clear = false;
+  for (let i = 3; i < data.length && !clear; i += c) clear = data[i] < 250;
+  if (!rows.length || !clear) return null;
+  const top = rows[0];
+  const bottom = rows[rows.length - 1];
+  const end = top + Math.max(1, Math.round((bottom - top + 1) * HEAD));
+  let sum = 0, sx = 0, sy = 0;
+  for (let y = top; y < end; y++) {
+    for (let x = 0; x < w; x++) {
+      const a = alpha(x, y);
+      sum += a; sx += a * (x + 0.5); sy += a * (y + 0.5);
+    }
+  }
+  return sum ? [sx / sum / w, sy / sum / h] : null;
+}
+
+/**
+ * Where a photo of `sw` × `sh` is drawn in a box so a point of it is
+ * centred: scaled to `fit` (cover or contain), then moved so the point
+ * sits on the box's centre. `cover` keeps the box filled (the move is
+ * held to the photo's overflow), except sideways for a cut-out
+ * (`free`), whose transparent sides show the ground; `contain` keeps it
+ * inside the box.
+ *
+ * @param {{ width: number, height: number }} box - Its size (any units).
+ * @param {number} sw @param {number} sh - The photo's size.
+ * @param {'cover' | 'contain'} fit
+ * @param {[number, number]} point - 0–1 in the photo.
+ * @param {boolean} [free=false] - Move freely sideways (a cut-out).
+ * @returns {{ x: number, y: number, width: number, height: number }} The photo's drawn box, relative to the box.
+ *
+ * @example
+ * focalBox({ width: 400, height: 500 }, 1000, 1000, 'cover', [0.3, 0]); // { x: 0, y: 0, width: 500, height: 500 }: held at the left edge
+ * focalBox({ width: 400, height: 500 }, 1000, 1000, 'cover', [0.3, 0], true); // { x: 50, … }: a cut-out, centred on 0.3
+ */
+export function focalBox(box, sw, sh, fit, [fx, fy], free = false) {
+  const k = fit === 'contain' ? Math.min(box.width / sw, box.height / sh) : Math.max(box.width / sw, box.height / sh);
+  const width = sw * k;
+  const height = sh * k;
+  let x = box.width / 2 - fx * width;
+  let y = box.height / 2 - fy * height;
+  /** Held between a and b (in either order). */
+  const hold = (/** @type {number} */ v, /** @type {number} */ a, /** @type {number} */ b) => Math.min(Math.max(a, b), Math.max(Math.min(a, b), v));
+  if (!free || fit === 'contain') x = hold(x, 0, box.width - width);
+  y = hold(y, 0, box.height - height);
+  return { x, y, width, height };
+}
+
+/**
+ * Draw a photo into a `W` × `H` raster at a drawn box (raster pixels), the
+ * rest transparent: resized, the visible part cut out and laid on a clear
+ * canvas. Returns a sharp pipeline of the result.
+ *
+ * @param {any} sharp
+ * @param {Uint8Array} bytes
+ * @param {number} W @param {number} H
+ * @param {{ x: number, y: number, width: number, height: number }} at - Raster pixels.
+ * @returns {Promise<any>}
+ */
+export async function drawAt(sharp, bytes, W, H, at) {
+  const rw = Math.max(1, Math.round(at.width));
+  const rh = Math.max(1, Math.round(at.height));
+  const ox = Math.round(at.x);
+  const oy = Math.round(at.y);
+  const left = Math.max(0, -ox), top = Math.max(0, -oy);
+  const width = Math.min(rw, W - ox) - left, height = Math.min(rh, H - oy) - top;
+  const canvas = sharp({ create: { width: W, height: H, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } });
+  if (width <= 0 || height <= 0) return sharp(await canvas.png().toBuffer());
+  const part = await sharp(bytes).rotate().ensureAlpha().resize(rw, rh, { fit: 'fill' }).extract({ left, top, width, height }).png().toBuffer();
+  return sharp(await canvas.composite([{ input: part, left: Math.max(0, ox), top: Math.max(0, oy) }]).png().toBuffer());
+}

package/src/layers.js

@@ -30,6 +30,7 @@ import { ink, dither, contour, waveform, tiles, rule } from './print.js';
 import { typeset, wantsType } from './type/index.js';
 import { recordLayout } from './type/layout-ref.js';
 import { shape, svg, table, barcode, perforation, tear, texture, mosaic, marks, outline, construction } from './layers/index.js';
+import { subjectFocus, focalBox, drawAt } from './layers/focal.js';
 import { pos, layerAttrs } from './layers/util.js';
 import { paint } from './paint/index.js';
 import { imageSize } from './lint/image-size.js';
@@ -423,7 +424,7 @@ export async function image(layer, ctx) {
   const focus = layer.focus ?? 'center';
   let bytes = typeof layer.src === 'string' || layer.src instanceof URL ? await readSource(layer.src) : await loadBytes(layer.src, 'image');
   let mime = imageMime(bytes);
-  let preserve = fit === 'stretch' ? 'none' : `${alignFor(focus)} ${fit === 'contain' ? 'meet' : 'slice'}`;
+  let preserve = fit === 'stretch' ? 'none' : `${alignFor(typeof focus === 'string' ? (focus === 'subject' ? 'top' : focus) : 'center')} ${fit === 'contain' ? 'meet' : 'slice'}`;
   let sharpBlurred = false;
 
   /** Source pixels and what was embedded, for lint. */
@@ -501,8 +502,13 @@ async function resample(ctx, bytes, box, fit, focus, layer) {
   if (cap && fit === 'stretch') { w = Math.min(w, sw); hgt = Math.min(hgt, sh); }
   w = Math.max(1, Math.round(w));
   hgt = Math.max(1, Math.round(hgt));
+  // A focus point ([x, y], or a cut-out's head) is centred in the box.
+  const head = focus === 'subject' ? await subjectFocus(sharp, bytes) : null;
+  const point = Array.isArray(focus) ? focus : head ? [head[0], 0] : null;
   const position = typeof focus === 'string' && ['attention', 'entropy'].includes(focus) ? focus : (POSITIONS[focus] ?? 'centre');
-  let img = sharp(bytes).rotate().resize(w, hgt, { fit: fit === 'stretch' ? 'fill' : fit, position, background: { r: 0, g: 0, b: 0, alpha: 0 } });
+  let img = point && fit !== 'stretch'
+    ? await drawAt(sharp, bytes, w, hgt, focalBox({ width: w, height: hgt }, sw, sh, fit, point, Boolean(meta.hasAlpha)))
+    : sharp(bytes).rotate().resize(w, hgt, { fit: fit === 'stretch' ? 'fill' : fit, position, background: { r: 0, g: 0, b: 0, alpha: 0 } });
   // Stretch the tones first, so a duotone spans both of its colours.
   if (layer.normalize ?? Boolean(layer.duotone || layer.grayscale)) img = img.normalise();
   // Blur here rather than in SVG: sharp clamps at the edges, where an SVG

package/src/version.js

@@ -1,4 +1,4 @@
 // Generated by scripts/generate.mjs from package.json. Do not edit.
 
 /** The package version, part of every cache key. */
-export const VERSION = '1.5.1';
+export const VERSION = '1.7.0';