@softure-ai/marketing-kit 0.17.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +54 -11
  3. package/dist/config/actions-schema.d.ts +14 -14
  4. package/dist/config/config.d.ts.map +1 -1
  5. package/dist/config/config.js +11 -1
  6. package/dist/config/config.js.map +1 -1
  7. package/dist/config/schema.d.ts +78 -70
  8. package/dist/config/schema.d.ts.map +1 -1
  9. package/dist/config/schema.js +25 -8
  10. package/dist/config/schema.js.map +1 -1
  11. package/dist/config/shot-steps.d.ts +16 -16
  12. package/dist/footage/clip-sound.d.ts +59 -4
  13. package/dist/footage/clip-sound.d.ts.map +1 -1
  14. package/dist/footage/clip-sound.js +58 -12
  15. package/dist/footage/clip-sound.js.map +1 -1
  16. package/dist/footage/compose.d.ts +17 -3
  17. package/dist/footage/compose.d.ts.map +1 -1
  18. package/dist/footage/compose.js +61 -17
  19. package/dist/footage/compose.js.map +1 -1
  20. package/dist/footage/declick.d.ts +49 -41
  21. package/dist/footage/declick.d.ts.map +1 -1
  22. package/dist/footage/declick.js +181 -92
  23. package/dist/footage/declick.js.map +1 -1
  24. package/dist/footage/film.d.ts +45 -2
  25. package/dist/footage/film.d.ts.map +1 -1
  26. package/dist/footage/film.js +23 -0
  27. package/dist/footage/film.js.map +1 -1
  28. package/dist/footage/isolate-ranges.d.ts +5 -0
  29. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  30. package/dist/footage/isolate-ranges.js +4 -2
  31. package/dist/footage/isolate-ranges.js.map +1 -1
  32. package/dist/footage/paid.d.ts +1 -1
  33. package/dist/footage/paid.d.ts.map +1 -1
  34. package/dist/footage/paid.js +3 -2
  35. package/dist/footage/paid.js.map +1 -1
  36. package/dist/footage/pipeline.d.ts +11 -0
  37. package/dist/footage/pipeline.d.ts.map +1 -1
  38. package/dist/footage/pipeline.js +28 -17
  39. package/dist/footage/pipeline.js.map +1 -1
  40. package/dist/footage/render.d.ts +5 -1
  41. package/dist/footage/render.d.ts.map +1 -1
  42. package/dist/footage/render.js +6 -2
  43. package/dist/footage/render.js.map +1 -1
  44. package/dist/index.d.ts +5 -5
  45. package/dist/index.d.ts.map +1 -1
  46. package/dist/index.js +5 -5
  47. package/dist/index.js.map +1 -1
  48. package/dist/og/character-map.d.ts +2 -1
  49. package/dist/og/character-map.d.ts.map +1 -1
  50. package/dist/og/character-map.js +7 -63
  51. package/dist/og/character-map.js.map +1 -1
  52. package/dist/og/font-file.d.ts +53 -0
  53. package/dist/og/font-file.d.ts.map +1 -0
  54. package/dist/og/font-file.js +153 -0
  55. package/dist/og/font-file.js.map +1 -0
  56. package/dist/og/font-tables.d.ts +25 -0
  57. package/dist/og/font-tables.d.ts.map +1 -0
  58. package/dist/og/font-tables.js +212 -0
  59. package/dist/og/font-tables.js.map +1 -0
  60. package/dist/og/index.d.ts +3 -1
  61. package/dist/og/index.d.ts.map +1 -1
  62. package/dist/og/index.js +2 -1
  63. package/dist/og/index.js.map +1 -1
  64. package/dist/og/photo-cover.d.ts +22 -0
  65. package/dist/og/photo-cover.d.ts.map +1 -1
  66. package/dist/og/photo-cover.js +27 -9
  67. package/dist/og/photo-cover.js.map +1 -1
  68. package/package.json +1 -1
  69. package/schema/marketing.schema.json +76 -23
  70. package/src/config/config.ts +10 -2
  71. package/src/config/schema.ts +24 -5
  72. package/src/footage/clip-sound.ts +95 -15
  73. package/src/footage/compose.ts +72 -17
  74. package/src/footage/declick.ts +172 -97
  75. package/src/footage/film.ts +54 -2
  76. package/src/footage/isolate-ranges.ts +9 -3
  77. package/src/footage/paid.ts +3 -3
  78. package/src/footage/pipeline.ts +41 -17
  79. package/src/footage/render.ts +7 -3
  80. package/src/index.ts +31 -5
  81. package/src/og/character-map.ts +8 -61
  82. package/src/og/font-file.ts +172 -0
  83. package/src/og/font-tables.ts +221 -0
  84. package/src/og/index.ts +14 -0
  85. package/src/og/photo-cover.ts +46 -11
@@ -0,0 +1,221 @@
1
+ import { brotliDecompressSync, inflateSync } from "node:zlib";
2
+
3
+ import { err, ok, type OgResult } from "./result.js";
4
+
5
+ /**
6
+ * The tables of a font file, by tag, for the formats an app may upload: TrueType and OpenType (sfnt), WOFF (each table
7
+ * zlib-compressed on its own) and WOFF2 (all tables in one Brotli stream). WOFF2 may transform `glyf`, `loca` and
8
+ * `hmtx`; those come back as stored, which is fine for the tables read here (`cmap`, `name`, `OS/2`, `head`, `fvar`
9
+ * are never transformed). Every read is bounds-checked, so a broken file is an error value, never an exception.
10
+ */
11
+
12
+ export type FontFileFormat = "ttf" | "otf" | "woff" | "woff2";
13
+
14
+ export interface FontTables {
15
+ format: FontFileFormat;
16
+ /** The format of the font inside a WOFF or WOFF2 wrapper (`ttf` or `otf`); the format itself for an sfnt. */
17
+ flavor: "ttf" | "otf";
18
+ get(tag: string): Buffer | undefined;
19
+ }
20
+
21
+ const TRUETYPE_SIGNATURES = new Set([0x00010000, 0x74727565 /* true */]);
22
+ const OPENTYPE_SIGNATURE = 0x4f54544f; // OTTO
23
+ const WOFF_SIGNATURE = 0x774f4646; // wOFF
24
+ const WOFF2_SIGNATURE = 0x774f4632; // wOF2
25
+ const COLLECTION_SIGNATURE = 0x74746366; // ttcf
26
+
27
+ /** More tables than any real font has; a larger count is a broken or hostile file. */
28
+ const MAX_TABLES = 512;
29
+ /** The largest decompressed WOFF2 font read (a CJK font is about 20 MB). */
30
+ const MAX_WOFF2_SIZE = 64 * 1024 * 1024;
31
+
32
+ /** The WOFF2 known-table tags, by their 6-bit index (WOFF2 spec, 5.1). */
33
+ const WOFF2_KNOWN_TAGS = [
34
+ "cmap", "head", "hhea", "hmtx", "maxp", "name", "OS/2", "post", "cvt ", "fpgm", "glyf", "loca", "prep", "CFF ", "VORG",
35
+ "EBDT", "EBLC", "gasp", "hdmx", "kern", "LTSH", "PCLT", "VDMX", "vhea", "vmtx", "BASE", "GDEF", "GPOS", "GSUB", "EBSC",
36
+ "JSTF", "MATH", "CBDT", "CBLC", "COLR", "CPAL", "SVG ", "sbix", "acnt", "avar", "bdat", "bloc", "bsln", "cvar", "fdsc",
37
+ "feat", "fmtx", "fvar", "gvar", "hsty", "just", "lcar", "mort", "morx", "opbd", "prop", "trak", "Zapf", "Silf", "Glat",
38
+ "Gloc", "Feat", "Sill",
39
+ ];
40
+
41
+ export class OutOfBounds extends Error {}
42
+
43
+ export function readUint8(data: Buffer, offset: number): number {
44
+ if (offset < 0 || offset + 1 > data.length) throw new OutOfBounds();
45
+ return data.readUInt8(offset);
46
+ }
47
+
48
+ export function readUint16(data: Buffer, offset: number): number {
49
+ if (offset < 0 || offset + 2 > data.length) throw new OutOfBounds();
50
+ return data.readUInt16BE(offset);
51
+ }
52
+
53
+ export function readInt16(data: Buffer, offset: number): number {
54
+ if (offset < 0 || offset + 2 > data.length) throw new OutOfBounds();
55
+ return data.readInt16BE(offset);
56
+ }
57
+
58
+ export function readUint32(data: Buffer, offset: number): number {
59
+ if (offset < 0 || offset + 4 > data.length) throw new OutOfBounds();
60
+ return data.readUInt32BE(offset);
61
+ }
62
+
63
+ export function readInt32(data: Buffer, offset: number): number {
64
+ if (offset < 0 || offset + 4 > data.length) throw new OutOfBounds();
65
+ return data.readInt32BE(offset);
66
+ }
67
+
68
+ export function slice(data: Buffer, offset: number, length: number): Buffer {
69
+ if (offset < 0 || length < 0 || offset + length > data.length) throw new OutOfBounds();
70
+ return data.subarray(offset, offset + length);
71
+ }
72
+
73
+ function readTag(data: Buffer, offset: number): string {
74
+ return slice(data, offset, 4).toString("latin1");
75
+ }
76
+
77
+ function toTables(format: FontFileFormat, flavor: "ttf" | "otf", tables: Map<string, Buffer>): FontTables {
78
+ return { format, flavor, get: (tag) => tables.get(tag) };
79
+ }
80
+
81
+ function getFlavor(signature: number): "ttf" | "otf" | null {
82
+ if (TRUETYPE_SIGNATURES.has(signature)) return "ttf";
83
+ if (signature === OPENTYPE_SIGNATURE) return "otf";
84
+ return null;
85
+ }
86
+
87
+ function readTableCount(data: Buffer, offset: number): OgResult<number> {
88
+ const count = readUint16(data, offset);
89
+ return count > MAX_TABLES ? err(`the font lists ${count} tables`) : ok(count);
90
+ }
91
+
92
+ function readSfnt(data: Buffer, flavor: "ttf" | "otf"): OgResult<FontTables> {
93
+ const count = readTableCount(data, 4);
94
+ if (!count.ok) return count;
95
+ const tables = new Map<string, Buffer>();
96
+ for (let index = 0; index < count.value; index++) {
97
+ const record = 12 + index * 16;
98
+ tables.set(readTag(data, record), slice(data, readUint32(data, record + 8), readUint32(data, record + 12)));
99
+ }
100
+ return ok(toTables(flavor, flavor, tables));
101
+ }
102
+
103
+ function readWoff(data: Buffer): OgResult<FontTables> {
104
+ const flavor = getFlavor(readUint32(data, 4));
105
+ if (flavor === null) return err("the WOFF file wraps neither a TrueType nor an OpenType font");
106
+ const count = readTableCount(data, 12);
107
+ if (!count.ok) return count;
108
+ const tables = new Map<string, Buffer>();
109
+ for (let index = 0; index < count.value; index++) {
110
+ const entry = 44 + index * 20;
111
+ const tag = readTag(data, entry);
112
+ const stored = slice(data, readUint32(data, entry + 4), readUint32(data, entry + 8));
113
+ const length = readUint32(data, entry + 12);
114
+ if (stored.length >= length) {
115
+ tables.set(tag, stored);
116
+ continue;
117
+ }
118
+ try {
119
+ tables.set(tag, inflateSync(stored, { maxOutputLength: Math.max(length, 1) }));
120
+ } catch {
121
+ return err(`the font's ${tag.trim()} table does not decompress`);
122
+ }
123
+ }
124
+ return ok(toTables("woff", flavor, tables));
125
+ }
126
+
127
+ /** A WOFF2 UIntBase128 at `offset`: the value and the offset after it, or null when it is malformed. */
128
+ function readBase128(data: Buffer, offset: number): { value: number; next: number } | null {
129
+ let value = 0;
130
+ for (let index = 0; index < 5; index++) {
131
+ const byte = readUint8(data, offset + index);
132
+ if (index === 0 && byte === 0x80) return null;
133
+ if (value > 0x01ffffff) return null;
134
+ value = value * 128 + (byte & 0x7f);
135
+ if ((byte & 0x80) === 0) return { value, next: offset + index + 1 };
136
+ }
137
+ return null;
138
+ }
139
+
140
+ interface Woff2Entry {
141
+ tag: string;
142
+ length: number;
143
+ }
144
+
145
+ function readWoff2Directory(data: Buffer, count: number): OgResult<{ entries: Woff2Entry[]; end: number }> {
146
+ const entries: Woff2Entry[] = [];
147
+ let offset = 48;
148
+ for (let index = 0; index < count; index++) {
149
+ const flags = readUint8(data, offset);
150
+ offset += 1;
151
+ const known = flags & 0x3f;
152
+ let tag: string;
153
+ if (known === 0x3f) {
154
+ tag = readTag(data, offset);
155
+ offset += 4;
156
+ } else {
157
+ const name = WOFF2_KNOWN_TAGS[known];
158
+ if (name === undefined) return err(`the WOFF2 table directory names an unknown table index ${known}`);
159
+ tag = name;
160
+ }
161
+ const original = readBase128(data, offset);
162
+ if (original === null) return err("the WOFF2 table directory is malformed");
163
+ offset = original.next;
164
+ const version = flags >> 6;
165
+ const isTransformed = tag === "glyf" || tag === "loca" ? version === 0 : version !== 0;
166
+ let length = original.value;
167
+ if (isTransformed) {
168
+ const transformed = readBase128(data, offset);
169
+ if (transformed === null) return err("the WOFF2 table directory is malformed");
170
+ offset = transformed.next;
171
+ length = transformed.value;
172
+ }
173
+ entries.push({ tag, length });
174
+ }
175
+ return ok({ entries, end: offset });
176
+ }
177
+
178
+ function readWoff2(data: Buffer): OgResult<FontTables> {
179
+ const flavorSignature = readUint32(data, 4);
180
+ if (flavorSignature === COLLECTION_SIGNATURE) return err("font collections are not read");
181
+ const flavor = getFlavor(flavorSignature);
182
+ if (flavor === null) return err("the WOFF2 file wraps neither a TrueType nor an OpenType font");
183
+ const count = readTableCount(data, 12);
184
+ if (!count.ok) return count;
185
+ const totalSfntSize = readUint32(data, 16);
186
+ const compressedSize = readUint32(data, 20);
187
+ const directory = readWoff2Directory(data, count.value);
188
+ if (!directory.ok) return directory;
189
+ const compressed = slice(data, directory.value.end, compressedSize);
190
+ const expected = directory.value.entries.reduce((sum, entry) => sum + entry.length, 0);
191
+ if (expected > MAX_WOFF2_SIZE || totalSfntSize > MAX_WOFF2_SIZE) return err("the WOFF2 font is larger than 64 MB unpacked");
192
+ let stream: Buffer;
193
+ try {
194
+ stream = brotliDecompressSync(compressed, { maxOutputLength: Math.max(expected, 1) });
195
+ } catch {
196
+ return err("the WOFF2 font data does not decompress");
197
+ }
198
+ const tables = new Map<string, Buffer>();
199
+ let offset = 0;
200
+ for (const entry of directory.value.entries) {
201
+ tables.set(entry.tag, slice(stream, offset, entry.length));
202
+ offset += entry.length;
203
+ }
204
+ return ok(toTables("woff2", flavor, tables));
205
+ }
206
+
207
+ /** Reads a font file's tables; the error says why it cannot be read. */
208
+ export function readFontTables(data: Buffer): OgResult<FontTables> {
209
+ try {
210
+ const signature = readUint32(data, 0);
211
+ const flavor = getFlavor(signature);
212
+ if (flavor !== null) return readSfnt(data, flavor);
213
+ if (signature === WOFF_SIGNATURE) return readWoff(data);
214
+ if (signature === WOFF2_SIGNATURE) return readWoff2(data);
215
+ if (signature === COLLECTION_SIGNATURE) return err("font collections are not read");
216
+ return err("the file is not a TrueType, OpenType, WOFF or WOFF2 font");
217
+ } catch (error) {
218
+ if (error instanceof OutOfBounds) return err("the font file is truncated or malformed");
219
+ throw error;
220
+ }
221
+ }
package/src/og/index.ts CHANGED
@@ -1,6 +1,17 @@
1
1
  // `@softure-ai/marketing-kit/og`: OG images from templates and data, for the CLI and for a thin Next
2
2
  // route. Nothing here loads Playwright, so a route can import it.
3
3
  export { loadCharacterMap, readCharacterMap, type CharacterMap } from "./character-map.js";
4
+ export {
5
+ FONT_USES,
6
+ findMissingCharacters,
7
+ readFontFileInfo,
8
+ type FontFileInfo,
9
+ type FontFileWeight,
10
+ type FontUnusableReason,
11
+ type FontUse,
12
+ type FontUseVerdict,
13
+ } from "./font-file.js";
14
+ export type { FontFileFormat } from "./font-tables.js";
4
15
  export { describeCharacter, findMissingGlyphs, selectSatoriFont, type MissingGlyphs } from "./glyphs.js";
5
16
  export { h, listNodes, type OgChild, type OgNode, type OgStyle } from "./element.js";
6
17
  export { OG_FONT_KINDS, OG_FONT_WEIGHTS, loadOgFonts, pickWeight, toFontFamilyCss, type OgFontFamily, type OgFontKind, type OgFontWeight, type OgFonts, type ReadFontFile, type SatoriFont } from "./fonts.js";
@@ -27,8 +38,11 @@ export {
27
38
  PHOTO_COVER_SIZE,
28
39
  getCoverBand,
29
40
  getCoverCaptionSize,
41
+ isPointUnderCoverText,
30
42
  renderPhotoCover,
31
43
  type CoverBand,
44
+ type CoverBox,
45
+ type CoverPoint,
32
46
  type PhotoCover,
33
47
  type PhotoCoverInput,
34
48
  type PhotoCoverLayout,
@@ -132,12 +132,30 @@ export interface PhotoCoverInput {
132
132
  id?: string;
133
133
  }
134
134
 
135
+ /** A box on the cover, in pixels: `left` and `top` included, `right` and `bottom` excluded. */
136
+ export interface CoverBox {
137
+ left: number;
138
+ top: number;
139
+ right: number;
140
+ bottom: number;
141
+ }
142
+
143
+ /** A point on the cover, in pixels from its top left corner. */
144
+ export interface CoverPoint {
145
+ x: number;
146
+ y: number;
147
+ }
148
+
135
149
  export interface PhotoCover {
136
150
  /** A baseline JPEG of exactly `width` × `height`, without an ICC profile (sRGB). */
137
151
  jpeg: Buffer;
138
152
  width: number;
139
153
  height: number;
140
154
  bytes: number;
155
+ /** The drawn text's bounds on the cover, its shadow included (the box the fit check measured); null for layout `photo`. */
156
+ textBox: CoverBox | null;
157
+ /** Where the focus point landed on the cover after the crop; off-centre when the photo's edge stops the shift. */
158
+ focusPoint: CoverPoint;
141
159
  }
142
160
 
143
161
  /** The text a cover draws, by layout. */
@@ -309,8 +327,8 @@ function checkTextGlyphs(tree: OgNode, fonts: OgFonts, text: CoverText): OgResul
309
327
  return err(`${sentences.join("; ")}. Use font files that cover them`);
310
328
  }
311
329
 
312
- /** The rows of `pixels` (RGBA, `width` wide) that hold anything drawn, or null when nothing is. */
313
- function findDrawnBox(pixels: Uint8Array, width: number, height: number): { top: number; bottom: number; left: number; right: number } | null {
330
+ /** The box of `pixels` (RGBA, `width` wide) that holds anything drawn (`right` and `bottom` excluded), or null when nothing is. */
331
+ function findDrawnBox(pixels: Uint8Array, width: number, height: number): CoverBox | null {
314
332
  let top = height;
315
333
  let bottom = -1;
316
334
  let left = width;
@@ -324,11 +342,11 @@ function findDrawnBox(pixels: Uint8Array, width: number, height: number): { top:
324
342
  right = Math.max(right, x);
325
343
  }
326
344
  }
327
- return bottom < 0 ? null : { top, bottom, left, right };
345
+ return bottom < 0 ? null : { left, top, right: right + 1, bottom: bottom + 1 };
328
346
  }
329
347
 
330
- /** The text as SVG and the rows it draws, or an error when it does not fit its part of the band. */
331
- async function layOutText(layout: TextLayout): Promise<OgResult<{ svg: string; top: number; bottom: number }>> {
348
+ /** The text as SVG and the box it draws, or an error when it does not fit its part of the band. */
349
+ async function layOutText(layout: TextLayout): Promise<OgResult<{ svg: string; box: CoverBox }>> {
332
350
  const tree = buildTextTree(layout);
333
351
  const glyphs = checkTextGlyphs(tree, layout.fonts, layout.text);
334
352
  if (!glyphs.ok) return glyphs;
@@ -348,14 +366,17 @@ async function layOutText(layout: TextLayout): Promise<OgResult<{ svg: string; t
348
366
  // The text keeps to the part of the band its layout names, so the photo's subject elsewhere stays clear.
349
367
  const region = LAYOUT_REGIONS[layout.text.layout];
350
368
  const rows = getRegionRows(band, region);
351
- const isInside = box.top >= rows.top && box.bottom < rows.bottom && box.left >= band.left && box.right < band.left + band.width;
369
+ const isInside = box.top >= rows.top && box.bottom <= rows.bottom && box.left >= band.left && box.right <= band.left + band.width;
352
370
  if (!isInside) {
353
371
  return err(`${name} ${isPlural ? "do" : "does"} not fit the ${region} of the centre 4:5 band (${String(band.width)}×${String(band.height)}); shorten ${isPlural ? "them" : "it"}`);
354
372
  }
355
- return ok({ svg, top: box.top, bottom: box.bottom });
373
+ return ok({ svg, box });
356
374
  }
357
375
 
358
- /** The scrim behind the text, as SVG: a gradient of the shade that follows the text's position; none for a pill (its box is its scrim). */
376
+ /**
377
+ * The scrim behind the text, as SVG: a gradient of the shade that follows the text's position; none for a pill (its
378
+ * box is its scrim). `text.top` is the text's first drawn row and `text.bottom` its last.
379
+ */
359
380
  function buildScrim(input: { size: readonly [number, number]; band: CoverBand; layout: CoverText["layout"]; text: { top: number; bottom: number }; shade: string }): string {
360
381
  const [width, height] = input.size;
361
382
  const { band, shade } = input;
@@ -418,7 +439,9 @@ export async function renderPhotoCover(input: PhotoCoverInput): Promise<OgResult
418
439
  const drawn = text.value === null ? null : await layOutText({ size, band, text: text.value, fonts: input.fonts, ink });
419
440
  if (drawn !== null && !drawn.ok) return err(`${name}: ${drawn.error}.`);
420
441
 
421
- const crop = getCoverCrop(getOrientedSize(info.value), size, options.focus);
442
+ const oriented = getOrientedSize(info.value);
443
+ const crop = getCoverCrop(oriented, size, options.focus);
444
+ const focusPoint = { x: crop.x + options.focus.x * oriented.width * crop.scale, y: crop.y + options.focus.y * oriented.height * crop.scale };
422
445
  const matrix = getOrientationMatrix(info.value.orientation, info.value.width, info.value.height).join(" ");
423
446
  const layers = [
424
447
  `<rect width="${String(width)}" height="${String(height)}" fill="${ink.shade}"/>`,
@@ -427,7 +450,7 @@ export async function renderPhotoCover(input: PhotoCoverInput): Promise<OgResult
427
450
  ];
428
451
  if (drawn !== null && text.value !== null) {
429
452
  layers.push(
430
- buildScrim({ size, band, layout: text.value.layout, text: drawn.value, shade: ink.shade }),
453
+ buildScrim({ size, band, layout: text.value.layout, text: { top: drawn.value.box.top, bottom: drawn.value.box.bottom - 1 }, shade: ink.shade }),
431
454
  `<image href="${toDataUri("image/svg+xml", drawn.value.svg)}" width="${String(width)}" height="${String(height)}"/>`,
432
455
  );
433
456
  }
@@ -435,8 +458,20 @@ export async function renderPhotoCover(input: PhotoCoverInput): Promise<OgResult
435
458
  try {
436
459
  const image = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } }).render();
437
460
  const encoded = jpeg.encode({ data: Buffer.from(image.pixels), width: image.width, height: image.height }, options.quality).data;
438
- return ok({ jpeg: encoded, width: image.width, height: image.height, bytes: encoded.length });
461
+ return ok({ jpeg: encoded, width: image.width, height: image.height, bytes: encoded.length, textBox: drawn === null ? null : { ...drawn.value.box }, focusPoint });
439
462
  } catch (error) {
440
463
  return err(`${name}: drawing the cover failed: ${error instanceof Error ? error.message : String(error)}.`);
441
464
  }
442
465
  }
466
+
467
+ /**
468
+ * Whether `point` lies under the cover's text: inside its `textBox` grown by `marginPx` on every side (0 by default).
469
+ * A cover without text (layout `photo`) covers no point. Use it with `focusPoint` to warn when the text hides the
470
+ * photo's subject.
471
+ */
472
+ export function isPointUnderCoverText(cover: Pick<PhotoCover, "textBox">, point: CoverPoint, marginPx = 0): boolean {
473
+ if (!Number.isFinite(marginPx) || marginPx < 0) throw new RangeError(`isPointUnderCoverText: the margin must be a finite number of pixels, 0 or more, not ${String(marginPx)}`);
474
+ const box = cover.textBox;
475
+ if (box === null) return false;
476
+ return point.x >= box.left - marginPx && point.x < box.right + marginPx && point.y >= box.top - marginPx && point.y < box.bottom + marginPx;
477
+ }