@arraypress/covers 1.5.1 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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, 91 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.6.1",
   "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/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.6.1';