@softure-ai/marketing-kit 0.1.7 → 0.1.9

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 (129) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +107 -15
  3. package/dist/cli/main.js +84 -29
  4. package/dist/cli/main.js.map +1 -1
  5. package/dist/cli/og.d.ts +4 -1
  6. package/dist/cli/og.d.ts.map +1 -1
  7. package/dist/cli/og.js +15 -7
  8. package/dist/cli/og.js.map +1 -1
  9. package/dist/cli/options.d.ts +26 -2
  10. package/dist/cli/options.d.ts.map +1 -1
  11. package/dist/cli/options.js +97 -9
  12. package/dist/cli/options.js.map +1 -1
  13. package/dist/cli/voice.d.ts +14 -0
  14. package/dist/cli/voice.d.ts.map +1 -1
  15. package/dist/cli/voice.js +13 -0
  16. package/dist/cli/voice.js.map +1 -1
  17. package/dist/config/actions-schema.d.ts +21 -15
  18. package/dist/config/actions-schema.d.ts.map +1 -1
  19. package/dist/config/actions-schema.js +18 -3
  20. package/dist/config/actions-schema.js.map +1 -1
  21. package/dist/config/config.d.ts +2 -0
  22. package/dist/config/config.d.ts.map +1 -1
  23. package/dist/config/config.js +2 -2
  24. package/dist/config/config.js.map +1 -1
  25. package/dist/config/og-image-names.d.ts +7 -0
  26. package/dist/config/og-image-names.d.ts.map +1 -0
  27. package/dist/config/og-image-names.js +9 -0
  28. package/dist/config/og-image-names.js.map +1 -0
  29. package/dist/config/schema.d.ts +111 -16
  30. package/dist/config/schema.d.ts.map +1 -1
  31. package/dist/config/schema.js +77 -11
  32. package/dist/config/schema.js.map +1 -1
  33. package/dist/film.d.ts +20 -5
  34. package/dist/film.d.ts.map +1 -1
  35. package/dist/film.js.map +1 -1
  36. package/dist/index.d.ts +5 -3
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +5 -3
  39. package/dist/index.js.map +1 -1
  40. package/dist/og/index.d.ts +3 -3
  41. package/dist/og/index.d.ts.map +1 -1
  42. package/dist/og/index.js +3 -2
  43. package/dist/og/index.js.map +1 -1
  44. package/dist/og/render.d.ts +13 -0
  45. package/dist/og/render.d.ts.map +1 -1
  46. package/dist/og/render.js +31 -6
  47. package/dist/og/render.js.map +1 -1
  48. package/dist/og/templates/big-number.d.ts +7 -0
  49. package/dist/og/templates/big-number.d.ts.map +1 -0
  50. package/dist/og/templates/big-number.js +41 -0
  51. package/dist/og/templates/big-number.js.map +1 -0
  52. package/dist/og/templates/carousel.d.ts +5 -0
  53. package/dist/og/templates/carousel.d.ts.map +1 -0
  54. package/dist/og/templates/carousel.js +26 -0
  55. package/dist/og/templates/carousel.js.map +1 -0
  56. package/dist/og/templates/context.d.ts +11 -3
  57. package/dist/og/templates/context.d.ts.map +1 -1
  58. package/dist/og/templates/context.js +6 -0
  59. package/dist/og/templates/context.js.map +1 -1
  60. package/dist/og/templates/frame.d.ts +2 -2
  61. package/dist/og/templates/frame.d.ts.map +1 -1
  62. package/dist/og/templates/frame.js +2 -2
  63. package/dist/og/templates/frame.js.map +1 -1
  64. package/dist/og/templates/index.d.ts +8 -3
  65. package/dist/og/templates/index.d.ts.map +1 -1
  66. package/dist/og/templates/index.js +18 -5
  67. package/dist/og/templates/index.js.map +1 -1
  68. package/dist/og/templates/portrait.d.ts +22 -0
  69. package/dist/og/templates/portrait.d.ts.map +1 -0
  70. package/dist/og/templates/portrait.js +75 -0
  71. package/dist/og/templates/portrait.js.map +1 -0
  72. package/dist/og/templates/schemas.d.ts +28 -0
  73. package/dist/og/templates/schemas.d.ts.map +1 -1
  74. package/dist/og/templates/schemas.js +26 -0
  75. package/dist/og/templates/schemas.js.map +1 -1
  76. package/dist/record/actions.d.ts.map +1 -1
  77. package/dist/record/actions.js +6 -1
  78. package/dist/record/actions.js.map +1 -1
  79. package/dist/record/record.d.ts.map +1 -1
  80. package/dist/record/record.js +51 -17
  81. package/dist/record/record.js.map +1 -1
  82. package/dist/record/screen-guard.d.ts +13 -0
  83. package/dist/record/screen-guard.d.ts.map +1 -0
  84. package/dist/record/screen-guard.js +27 -0
  85. package/dist/record/screen-guard.js.map +1 -0
  86. package/dist/screenshot/gates.d.ts +6 -3
  87. package/dist/screenshot/gates.d.ts.map +1 -1
  88. package/dist/screenshot/gates.js +12 -3
  89. package/dist/screenshot/gates.js.map +1 -1
  90. package/dist/screenshot/screenshot.d.ts +17 -0
  91. package/dist/screenshot/screenshot.d.ts.map +1 -1
  92. package/dist/screenshot/screenshot.js +37 -6
  93. package/dist/screenshot/screenshot.js.map +1 -1
  94. package/dist/screenshot/storage-state.d.ts +9 -0
  95. package/dist/screenshot/storage-state.d.ts.map +1 -0
  96. package/dist/screenshot/storage-state.js +25 -0
  97. package/dist/screenshot/storage-state.js.map +1 -0
  98. package/dist/voice/placeholder.d.ts +35 -0
  99. package/dist/voice/placeholder.d.ts.map +1 -0
  100. package/dist/voice/placeholder.js +53 -0
  101. package/dist/voice/placeholder.js.map +1 -0
  102. package/package.json +2 -1
  103. package/schema/marketing.schema.json +392 -43
  104. package/src/cli/main.ts +80 -27
  105. package/src/cli/og.ts +14 -6
  106. package/src/cli/options.ts +109 -10
  107. package/src/cli/voice.ts +20 -0
  108. package/src/config/actions-schema.ts +18 -3
  109. package/src/config/config.ts +4 -3
  110. package/src/config/og-image-names.ts +7 -0
  111. package/src/config/schema.ts +91 -13
  112. package/src/film.ts +15 -5
  113. package/src/index.ts +7 -1
  114. package/src/og/index.ts +16 -2
  115. package/src/og/render.ts +36 -6
  116. package/src/og/templates/big-number.ts +44 -0
  117. package/src/og/templates/carousel.ts +27 -0
  118. package/src/og/templates/context.ts +16 -3
  119. package/src/og/templates/frame.ts +2 -2
  120. package/src/og/templates/index.ts +31 -9
  121. package/src/og/templates/portrait.ts +126 -0
  122. package/src/og/templates/schemas.ts +35 -0
  123. package/src/record/actions.ts +6 -1
  124. package/src/record/record.ts +53 -19
  125. package/src/record/screen-guard.ts +37 -0
  126. package/src/screenshot/gates.ts +13 -3
  127. package/src/screenshot/screenshot.ts +51 -11
  128. package/src/screenshot/storage-state.ts +24 -0
  129. package/src/voice/placeholder.ts +83 -0
@@ -13,12 +13,13 @@ import {
13
13
  type LayoutName,
14
14
  } from "../compose/timeline.js";
15
15
  import { MARKETING_LOCALES, type MarketingLocale } from "../messages/index.js";
16
- import { headlineChartDataSchema, headlineCtaDataSchema } from "../og/templates/schemas.js";
16
+ import { bigNumberDataSchema, carouselDataSchema, headlineChartDataSchema, headlineCtaDataSchema } from "../og/templates/schemas.js";
17
17
  import { CHANNEL_CODE_MAX_LENGTH, CHANNEL_CODE_PATTERN, DEFAULT_LINK_IN_BIO, PLATFORMS } from "../platforms.js";
18
18
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
19
19
  import { actionSchema, type SceneAction } from "./actions-schema.js";
20
20
  import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
21
21
  import { DAY_PATTERN, isCalendarDay } from "./day.js";
22
+ import { getOgImageNames } from "./og-image-names.js";
22
23
  import { getScreenshotNames } from "./screenshot-names.js";
23
24
 
24
25
  /**
@@ -243,12 +244,20 @@ const voiceSchema = z.strictObject({
243
244
  .default(60)
244
245
  .describe("Least seconds between two paid recordings (0-3600, default 60; 0 turns it off), counted from the newest file in cacheDir, so separate runs are spaced too."),
245
246
  cacheDir: relativePath.default("marketing/voiceover").describe("The paid voiceover cache (<key>.mp3 and <key>.json), relative to the folder of marketing.json; commit it."),
247
+ placeholder: z
248
+ .strictObject({
249
+ wordsPerSecond: z.number().min(0.5).max(6).default(2.5).describe("Words per second of the placeholder voiceover (0.5-6, default 2.5); match the real voice to rehearse the film's length."),
250
+ sentencePauseSeconds: z.number().min(0).max(3).default(0.5).describe("Silence after every sentence of the placeholder voiceover but the last (0-3 s, default 0.5)."),
251
+ })
252
+ .prefault({})
253
+ .describe("The free placeholder voiceover of --placeholder (a quiet tone, words at a fixed pace), to record and render a film before paying for its voiceover."),
246
254
  });
247
255
 
248
- type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined };
256
+ type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined; screenGuard?: string[] | undefined };
249
257
 
250
258
  interface SceneShape {
251
259
  beats: VideoBeat[];
260
+ screenGuard: string[];
252
261
  hook: { still: string; shots: { mark: string }[]; transition: string };
253
262
  sceneModule?: string | undefined;
254
263
  }
@@ -260,7 +269,7 @@ interface SceneShape {
260
269
  */
261
270
  function checkScene(video: SceneShape, context: z.RefinementCtx): void {
262
271
  const [opening, ...sceneBeats] = video.beats;
263
- for (const key of ["actions", "pad"] as const) {
272
+ for (const key of ["actions", "pad", "screenGuard"] as const) {
264
273
  if (opening?.[key] !== undefined) {
265
274
  context.addIssue({ code: "custom", path: ["beats", 0, key], message: "the opening sentence plays over the still; the scene starts at the second sentence" });
266
275
  }
@@ -299,7 +308,8 @@ function checkScene(video: SceneShape, context: z.RefinementCtx): void {
299
308
  video.hook.shots.forEach((shot, index) => {
300
309
  if (!marks.has(shot.mark)) context.addIssue({ code: "custom", path: ["hook", "shots", index, "mark"], message: `no "mark" action saves "${shot.mark}"` });
301
310
  });
302
- if (!hasCheckScreen) context.addIssue({ code: "custom", path: ["beats"], message: 'needs a "checkScreen" action: the screen guard must run before the film can say what the screen shows' });
311
+ // Only the video's list waits for a checkScreen; a sentence's own phrases are checked when it ends.
312
+ if (!hasCheckScreen && video.screenGuard.length > 0) context.addIssue({ code: "custom", path: ["beats"], message: 'needs a "checkScreen" action: the screen guard must run before the film can say what the screen shows' });
303
313
  }
304
314
 
305
315
  const videoSchema = z
@@ -337,6 +347,13 @@ const videoSchema = z
337
347
  .array(actionSchema)
338
348
  .optional()
339
349
  .describe("What happens on screen during the sentence, in order; required on every sentence after the first when the film has no sceneModule."),
350
+ screenGuard: z
351
+ .array(nonBlank)
352
+ .min(1, "a sentence's screen guard needs at least one phrase; leave it out instead")
353
+ .optional()
354
+ .describe(
355
+ "Phrases this sentence says that the screen must show while it is spoken: checked at a checkScreen inside the sentence, or when the sentence ends. Not on the first sentence.",
356
+ ),
340
357
  }),
341
358
  )
342
359
  .min(3, "a film needs at least three sentences: opening, scene, end card")
@@ -370,8 +387,10 @@ const videoSchema = z
370
387
  ),
371
388
  screenGuard: z
372
389
  .array(nonBlank)
373
- .min(1, "the screen guard needs at least one phrase")
374
- .describe("Phrases the voiceover says that the screen must show; a missing one stops the recording."),
390
+ .default([])
391
+ .describe(
392
+ "Phrases the voiceover says that the screen must show at every checkScreen; a missing one stops the recording. May be left out when the sentences carry their own screenGuard.",
393
+ ),
375
394
  endCard: z
376
395
  .strictObject({
377
396
  headline: nonEmpty.describe("The end card's headline."),
@@ -384,6 +403,9 @@ const videoSchema = z
384
403
  .describe("A TS module exporting scene(director), relative to the folder of marketing.json: what happens on screen, instead of beat actions."),
385
404
  })
386
405
  .superRefine((video, context) => {
406
+ if (video.screenGuard.length === 0 && !video.beats.some((beat) => beat.screenGuard !== undefined)) {
407
+ context.addIssue({ code: "custom", path: ["screenGuard"], message: "the screen guard needs at least one phrase, here or in a sentence's screenGuard" });
408
+ }
387
409
  checkScene(video, context);
388
410
  const seen = new Set<string>();
389
411
  video.beats.forEach((beat, index) => {
@@ -445,7 +467,7 @@ const socialSchema = z.strictObject({
445
467
  .describe("A paragraph after every post's caption, e.g. that the persona is an example and the voice is AI-generated; {persona} becomes the film's persona name. A post opts out with disclosure: false."),
446
468
  });
447
469
 
448
- const screenshotSchema = z.strictObject({
470
+ export const screenshotSchema = z.strictObject({
449
471
  id: id.describe("The screenshot's id: the file <output.dir>/screenshots/<id>.png."),
450
472
  path: pagePath.describe("The page of the app to capture, e.g. /pricing."),
451
473
  width: pixels(8000).describe("The browser viewport's width in CSS pixels."),
@@ -461,25 +483,70 @@ const screenshotSchema = z.strictObject({
461
483
  .refine((schemes) => new Set(schemes).size === schemes.length, "lists a scheme twice")
462
484
  .optional()
463
485
  .describe('Capture each listed scheme into its own <id>-<scheme>.png, e.g. ["light", "dark"]; without it, one <id>.png in app.colorScheme.'),
486
+ scrollTo: z
487
+ .number()
488
+ .int()
489
+ .min(0)
490
+ .optional()
491
+ .describe('Capture one viewport frame scrolled to this many CSS pixels from the top (e.g. to check scroll-driven motion, with motion: "no-preference"); refused when the page cannot scroll that far. Not with full.'),
492
+ waitMs: z.number().int().min(0).max(60_000).default(0).describe("Milliseconds to wait after the page loaded (and scrolled) before the phrase gate reads it, for animations to settle (0-60000, default 0)."),
493
+ storageState: relativePath
494
+ .optional()
495
+ .describe("A Playwright storage state (cookies and localStorage as JSON), relative to the folder of marketing.json, to capture a signed-in screen. It holds a session: keep it out of git."),
496
+ }).superRefine((entry, context) => {
497
+ if (entry.full && entry.scrollTo !== undefined) {
498
+ context.addIssue({ code: "custom", path: ["scrollTo"], message: "is one viewport frame at a scroll position; a full-page shot has none, so drop full or scrollTo" });
499
+ }
464
500
  });
465
501
 
466
- const ogImageBase = {
467
- id: id.describe("The image's id: the file <output.dir>/og/<id>.png."),
468
- size: z.tuple([pixels(4000), pixels(4000)]).default([1200, 630]).describe("The image size in pixels, [width, height]."),
469
- };
502
+ /** Named sizes of `ogImages[].size`: the share card and the three social formats. */
503
+ export const OG_SIZE_PRESETS = {
504
+ landscape: [1200, 630],
505
+ portrait: [1080, 1350],
506
+ square: [1080, 1080],
507
+ story: [1080, 1920],
508
+ } as const satisfies Record<string, readonly [number, number]>;
509
+
510
+ type OgSizePreset = keyof typeof OG_SIZE_PRESETS;
511
+
512
+ /** A preset name or `[width, height]`; the loaded config always holds the pair. */
513
+ const ogSize = (preset: OgSizePreset) =>
514
+ z
515
+ .union([z.tuple([pixels(4000), pixels(4000)]), z.enum(Object.keys(OG_SIZE_PRESETS) as [OgSizePreset, ...OgSizePreset[]])])
516
+ .transform((size): [number, number] => (typeof size === "string" ? [...OG_SIZE_PRESETS[size]] : size))
517
+ .default([...OG_SIZE_PRESETS[preset]])
518
+ .describe(
519
+ `The image size: "landscape" (1200×630), "portrait" (1080×1350), "square" (1080×1080), "story" (1080×1920) or [width, height] in pixels; "${preset}" by default.`,
520
+ );
521
+
522
+ const ogImageId = id.describe("The image's id: the file <output.dir>/og/<id>.png (a carousel writes <id>-1.png, <id>-2.png and so on).");
470
523
 
471
524
  /** One entry per template; `data` is the template's input, and values the app computes (charts) arrive precomputed. */
472
525
  const ogImageSchema = z.discriminatedUnion("template", [
473
526
  z.strictObject({
474
- ...ogImageBase,
527
+ id: ogImageId,
528
+ size: ogSize("landscape"),
475
529
  template: z.literal("headline-cta").describe("A headline with an optional eyebrow, call to action and tiles."),
476
530
  data: headlineCtaDataSchema.describe("The headline-cta template's input."),
477
531
  }),
478
532
  z.strictObject({
479
- ...ogImageBase,
533
+ id: ogImageId,
534
+ size: ogSize("landscape"),
480
535
  template: z.literal("headline-chart").describe("A headline over a chart the app computed, with optional tiles."),
481
536
  data: headlineChartDataSchema.describe("The headline-chart template's input."),
482
537
  }),
538
+ z.strictObject({
539
+ id: ogImageId,
540
+ size: ogSize("portrait"),
541
+ template: z.literal("big-number").describe("A portrait post whose number fills the frame, with the sentence that explains it, tiles, a call to action and a source line."),
542
+ data: bigNumberDataSchema.describe("The big-number template's input."),
543
+ }),
544
+ z.strictObject({
545
+ id: ogImageId,
546
+ size: ogSize("portrait"),
547
+ template: z.literal("carousel").describe("A numbered run of portrait slides sharing one look; each slide is its own file <id>-<n>.png."),
548
+ data: carouselDataSchema.describe("The carousel template's input."),
549
+ }),
483
550
  ]);
484
551
 
485
552
  /** When each sound effect plays; the descriptions of the `sfx` keys. */
@@ -611,6 +678,17 @@ export const marketingSchema = z
611
678
  });
612
679
  checkUnique("screenshots");
613
680
  checkUnique("ogImages");
681
+ const ogFileOwners = new Map<string, number>();
682
+ config.ogImages.forEach((entry, index) => {
683
+ for (const name of getOgImageNames(entry)) {
684
+ const owner = ogFileOwners.get(name);
685
+ // Two entries with one id are reported by checkUnique already.
686
+ if (owner !== undefined && owner !== index && config.ogImages[owner]?.id !== entry.id) {
687
+ context.addIssue({ code: "custom", path: ["ogImages", index, "id"], message: `writes og/${name}.png, as ogImages[${String(owner)}] does` });
688
+ }
689
+ ogFileOwners.set(name, owner ?? index);
690
+ }
691
+ });
614
692
  const fileOwners = new Map<string, number>();
615
693
  config.screenshots.forEach((entry, index) => {
616
694
  for (const name of getScreenshotNames(entry.id)) {
package/src/film.ts CHANGED
@@ -12,6 +12,11 @@ import type { LayoutOverride, Transition, VideoFormat, Viewport } from "./compos
12
12
  export interface Beat {
13
13
  id: string;
14
14
  text: string;
15
+ /**
16
+ * Phrases this sentence says that the screen must show while it is spoken: checked at a `checkScreen` inside the
17
+ * sentence, or when it ends. Never on the opening sentence.
18
+ */
19
+ screenGuard?: string[];
15
20
  }
16
21
 
17
22
  export interface Persona {
@@ -89,8 +94,8 @@ export interface FilmScript {
89
94
  /** The opening: its still, the camera shots over it, and how it hands over to the scene. */
90
95
  hook: { still: string; shots: HookShot[]; transition: Transition };
91
96
  /**
92
- * Phrases the voiceover says that the app's screen must show. If any is missing the recording
93
- * stops and the render never starts.
97
+ * Phrases the voiceover says that the app's screen must show at every `checkScreen`. If any is missing the
98
+ * recording stops and the render never starts. Empty when every phrase lives on its sentence (`Beat.screenGuard`).
94
99
  */
95
100
  screenGuard: string[];
96
101
  endCard: EndCard;
@@ -116,8 +121,13 @@ export interface Director {
116
121
  /** Touch the element on a phone, click it on a desktop. */
117
122
  tap(target: Locator, options?: { after?: number }): Promise<void>;
118
123
  type(text: string, options?: { perChar?: number }): Promise<void>;
119
- /** Tap the `input[name=…]` field, move the camera onto it and type the value. */
120
- fill(name: string, value: string): Promise<void>;
124
+ /** Press a key (a Playwright key name such as `Backspace` or `ControlOrMeta+A`) `times` times, holding `perKey` after each. */
125
+ press(key: string, options?: { times?: number; perKey?: number }): Promise<void>;
126
+ /**
127
+ * Tap the `input[name=…]` field, move the camera onto it and type the value. A value already in the field is
128
+ * selected and deleted first, on screen; `clear: false` types after it instead.
129
+ */
130
+ fill(name: string, value: string, options?: { clear?: boolean }): Promise<void>;
121
131
  blur(): Promise<void>;
122
132
  /** Camera on an element (or on the rectangle that encloses several). */
123
133
  focus(target: Locator | Locator[], options?: { scale?: number; height?: number }): Promise<void>;
@@ -129,7 +139,7 @@ export interface Director {
129
139
  still(name: string): Promise<void>;
130
140
  /** An event on the film's timeline: a sound effect or the persona card leaving. */
131
141
  cue(name: CueName): Promise<void>;
132
- /** The screen guard: check now, before the recording goes on. */
142
+ /** The screen guard: the video's phrases and the current sentence's, checked now, before the recording goes on. */
133
143
  checkScreen(): Promise<void>;
134
144
  }
135
145
 
package/src/index.ts CHANGED
@@ -87,6 +87,7 @@ export { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoice
87
87
  export { describeCharge, describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
88
88
  export { findLastRecordingTime, waitForPace, type PaceOptions } from "./voice/pace.js";
89
89
  export { describeVoiceoverBatch, produceVoiceovers, type VoiceoverBatchItem, type VoiceoverBatchResult } from "./voice/batch.js";
90
+ export { getPlaceholderKey, isPlaceholderKey, makePlaceholderWords, writePlaceholderVoiceover, type PlaceholderPace, type WritePlaceholderOptions } from "./voice/placeholder.js";
90
91
  export {
91
92
  BROWSER_BAR_HEIGHT,
92
93
  DEVICE_KINDS,
@@ -139,6 +140,8 @@ export {
139
140
  } from "./compose/compose.js";
140
141
  export {
141
142
  DEFAULT_OG_SIZE,
143
+ countOgSlides,
144
+ getDefaultOgSize,
142
145
  OG_TEMPLATE_IDS,
143
146
  getOgPalette,
144
147
  loadOgFonts,
@@ -155,13 +158,16 @@ export { createActionScene, getLocator, runAction, type LocatorSource } from "./
155
158
  export { FPS, ScreenGuardError, type BrowserSettings, type CameraCue, type RecordingLog } from "./record/record.js";
156
159
  export {
157
160
  getScreenshotFile,
161
+ takePageScreenshot,
158
162
  takeScreenshots,
159
163
  type ScreenshotBrowser,
160
164
  type ScreenshotEntry,
161
165
  type ScreenshotResult,
166
+ type TakePageScreenshotOptions,
162
167
  type TakeScreenshotsOptions,
163
168
  } from "./screenshot/screenshot.js";
164
- export { MIN_FAILING_STATUS, SCREENSHOT_GATES, findSizeFailure, findStatusFailure, type ScreenshotGate } from "./screenshot/gates.js";
169
+ export { MIN_FAILING_STATUS, SCREENSHOT_GATES, findScrollFailure, findSizeFailure, findStatusFailure, type ScreenshotGate } from "./screenshot/gates.js";
170
+ export { findStorageStateProblem } from "./screenshot/storage-state.js";
165
171
  export { getScreenshotNames, getScreenshotShots, type ScreenshotNaming, type ScreenshotShot } from "./config/screenshot-names.js";
166
172
  export {
167
173
  MARKETING_LOCALES,
package/src/og/index.ts CHANGED
@@ -9,6 +9,8 @@ export type { OgResult } from "./result.js";
9
9
  export {
10
10
  DEFAULT_OG_SIZE,
11
11
  buildOgTree,
12
+ countOgSlides,
13
+ getDefaultOgSize,
12
14
  renderConfiguredOgImage,
13
15
  renderOgImage,
14
16
  renderOgSvg,
@@ -17,6 +19,18 @@ export {
17
19
  type OgImageInput,
18
20
  } from "./render.js";
19
21
  export { OG_TEMPLATE_IDS, OG_TEMPLATES, isOgTemplateId, type OgTemplateId } from "./templates/index.js";
20
- export type { OgTemplateContext } from "./templates/context.js";
21
- export { CHART_TONES, headlineChartDataSchema, headlineCtaDataSchema, type ChartTone, type HeadlineChartData, type HeadlineCtaData } from "./templates/schemas.js";
22
+ export { PORTRAIT_BASE, getLayoutScale, type OgLayout, type OgTemplateContext } from "./templates/context.js";
23
+ export {
24
+ CHART_TONES,
25
+ bigNumberDataSchema,
26
+ carouselDataSchema,
27
+ headlineChartDataSchema,
28
+ headlineCtaDataSchema,
29
+ type BigNumberData,
30
+ type CarouselData,
31
+ type CarouselSlide,
32
+ type ChartTone,
33
+ type HeadlineChartData,
34
+ type HeadlineCtaData,
35
+ } from "./templates/schemas.js";
22
36
  export { loadMarketingConfig, type LoadConfigResult, type MarketingConfig } from "../config/config.js";
package/src/og/render.ts CHANGED
@@ -11,13 +11,19 @@ import { loadOgFonts, type OgFonts, type ReadFontFile } from "./fonts.js";
11
11
  import { describeCharacter, findMissingGlyphs, type MissingGlyphs } from "./glyphs.js";
12
12
  import { getOgPalette } from "./palette.js";
13
13
  import { err, ok, type OgResult } from "./result.js";
14
- import { BASE_WIDTH } from "./templates/context.js";
14
+ import { PORTRAIT_BASE, getLayoutScale } from "./templates/context.js";
15
15
  import { OG_TEMPLATE_IDS, OG_TEMPLATES, isOgTemplateId } from "./templates/index.js";
16
16
 
17
17
  /** Satori lays a tree out to SVG; resvg rasterises it. Neither reads the machine's fonts. */
18
18
 
19
+ /** The size of a landscape card (`headline-cta`, `headline-chart`) when none is given. */
19
20
  export const DEFAULT_OG_SIZE: readonly [number, number] = [1200, 630];
20
21
 
22
+ /** The size a template renders at when none is given: 1200×630 for a landscape card, 1080×1350 for a portrait post. */
23
+ export function getDefaultOgSize(template: string): readonly [number, number] {
24
+ return isOgTemplateId(template) && OG_TEMPLATES[template].layout === "portrait" ? PORTRAIT_BASE : DEFAULT_OG_SIZE;
25
+ }
26
+
21
27
  /** Everything about the brand a card shows. */
22
28
  export interface OgBrand {
23
29
  name: string;
@@ -30,6 +36,7 @@ export interface OgImageInput {
30
36
  template: string;
31
37
  /** The template's data, checked against its schema here. */
32
38
  data: unknown;
39
+ /** By default the template's own size (`getDefaultOgSize`). */
33
40
  size?: readonly [number, number];
34
41
  brand: OgBrand;
35
42
  fonts: OgFonts;
@@ -37,6 +44,8 @@ export interface OgImageInput {
37
44
  id?: string;
38
45
  /** Where `data` sits in the caller's JSON, for error paths; `["data"]` by default. */
39
46
  dataPath?: readonly PropertyKey[];
47
+ /** Which slide of a multi-slide template (`carousel`) to draw, 1-based; 1 by default. */
48
+ slide?: number;
40
49
  }
41
50
 
42
51
  /** At most this many characters are listed per text; the rest is counted. */
@@ -94,24 +103,42 @@ export function buildOgTree(input: OgImageInput): OgResult<OgNode> {
94
103
  const lines = parsed.error.issues.map((issue) => ` ${formatIssuePath([...dataPath, ...issue.path])}: ${issue.message}`);
95
104
  return err(`${describeCard(input)}: the data of template "${input.template}" is not valid:\n${lines.join("\n")}`);
96
105
  }
97
- const [width, height] = input.size ?? DEFAULT_OG_SIZE;
98
- const tree = template.build(parsed.data, {
106
+ const slide = input.slide ?? 1;
107
+ const slides = template.countSlides(parsed.data);
108
+ if (!Number.isInteger(slide) || slide < 1 || slide > slides) {
109
+ return err(`${describeCard(input)}: template "${input.template}" has ${String(slides)} slide${slides === 1 ? "" : "s"}; there is no slide ${String(slide)}.`);
110
+ }
111
+ const [width, height] = input.size ?? getDefaultOgSize(input.template);
112
+ const context = {
99
113
  width,
100
114
  height,
101
- scale: width / BASE_WIDTH,
115
+ scale: getLayoutScale(template.layout, width, height),
102
116
  palette: getOgPalette(input.brand.colors),
103
117
  fonts: { heading: input.fonts.heading, body: input.fonts.body },
104
118
  brand: { name: input.brand.name, logo: input.brand.logoSvg === null ? null : toDataUri(input.brand.logoSvg) },
105
- });
119
+ };
120
+ const tree = template.build(parsed.data, context, slide);
106
121
  const glyphs = checkGlyphs(input, tree, listStrings(parsed.data, dataPath));
107
122
  return glyphs.ok ? ok(tree) : glyphs;
108
123
  }
109
124
 
125
+ /**
126
+ * How many images the data of a template makes: the number of slides of a `carousel`, 1 for a single card. Invalid
127
+ * data or an unknown template is an error, as in `buildOgTree`.
128
+ */
129
+ export function countOgSlides(template: string, data: unknown): OgResult<number> {
130
+ if (!isOgTemplateId(template)) return err(`OG image: unknown template "${template}"; known: ${OG_TEMPLATE_IDS.join(", ")}.`);
131
+ const registered = OG_TEMPLATES[template];
132
+ const parsed = registered.schema.safeParse(data);
133
+ if (!parsed.success) return err(`OG image: the data of template "${template}" is not valid.`);
134
+ return ok(registered.countSlides(parsed.data));
135
+ }
136
+
110
137
  /** The card as SVG (Satori's output, text drawn as paths). */
111
138
  export async function renderOgSvg(input: OgImageInput): Promise<OgResult<string>> {
112
139
  const tree = buildOgTree(input);
113
140
  if (!tree.ok) return tree;
114
- const [width, height] = input.size ?? DEFAULT_OG_SIZE;
141
+ const [width, height] = input.size ?? getDefaultOgSize(input.template);
115
142
  try {
116
143
  // Satori is typed for React elements; it reads only `type` and `props`, which `OgNode` has.
117
144
  const svg = await satori(tree.value as unknown as Parameters<typeof satori>[0], { width, height, fonts: input.fonts.satoriFonts });
@@ -139,6 +166,8 @@ export interface ConfiguredOgImageOptions {
139
166
  id: string;
140
167
  /** Replaces the entry's data, e.g. values a route computes per request; checked like the config's. */
141
168
  data?: unknown;
169
+ /** Which slide of a `carousel` entry, 1-based; 1 by default. */
170
+ slide?: number;
142
171
  /** Reads font files; by default from disk. */
143
172
  readFile?: ReadFontFile;
144
173
  }
@@ -174,5 +203,6 @@ export async function renderConfiguredOgImage(options: ConfiguredOgImageOptions)
174
203
  fonts: fonts.value,
175
204
  id,
176
205
  dataPath: options.data === undefined ? ["ogImages", index, "data"] : ["data"],
206
+ slide: options.slide,
177
207
  });
178
208
  }
@@ -0,0 +1,44 @@
1
+ import { h } from "../element.js";
2
+ import type { OgTemplate } from "./context.js";
3
+ import { px, text } from "./frame.js";
4
+ import { portraitEyebrow, portraitFrame, portraitTiles } from "./portrait.js";
5
+ import type { BigNumberData } from "./schemas.js";
6
+
7
+ /** The number's size: the fewer characters, the bigger, so a short figure fills the post's width. */
8
+ export function bigNumberSize(value: string): number {
9
+ if (value.length <= 4) return 300;
10
+ if (value.length <= 6) return 220;
11
+ if (value.length <= 8) return 180;
12
+ if (value.length <= 10) return 150;
13
+ return 124;
14
+ }
15
+
16
+ /** One figure as the hero of a portrait post, the sentence that explains it, and up to two more figures. */
17
+ export const bigNumberTemplate: OgTemplate<BigNumberData> = {
18
+ build(data, context) {
19
+ const { palette } = context;
20
+ return portraitFrame(context, {
21
+ counter: null,
22
+ cta: data.cta,
23
+ source: data.source,
24
+ content: [
25
+ portraitEyebrow(context, data.eyebrow),
26
+ h(
27
+ "div",
28
+ {
29
+ style: {
30
+ ...text(context, context.fonts.heading, bigNumberSize(data.number), 700),
31
+ lineHeight: 1,
32
+ letterSpacing: -px(context, 4),
33
+ color: palette.foreground,
34
+ wordBreak: "break-word",
35
+ },
36
+ },
37
+ data.number,
38
+ ),
39
+ h("div", { style: { ...text(context, context.fonts.body, 48, 600), wordBreak: "break-word", lineHeight: 1.2, color: palette.foreground, marginTop: px(context, 36) } }, data.caption),
40
+ portraitTiles(context, data.tiles),
41
+ ],
42
+ });
43
+ },
44
+ };
@@ -0,0 +1,27 @@
1
+ import { h } from "../element.js";
2
+ import type { OgTemplate } from "./context.js";
3
+ import { px, text } from "./frame.js";
4
+ import { portraitEyebrow, portraitFrame, portraitHeadline, portraitTiles } from "./portrait.js";
5
+ import type { CarouselData } from "./schemas.js";
6
+
7
+ /** One slide of a numbered run: every slide shares the frame, the counter says where the reader is. */
8
+ export const carouselTemplate: OgTemplate<CarouselData> = {
9
+ build(data, context, slide) {
10
+ const current = data.slides[slide - 1];
11
+ // `buildOgTree` checks `slide` against `countSlides` before it calls `build`, so this is a bug.
12
+ if (current === undefined) throw new Error(`carousel: no slide ${String(slide)} of ${String(data.slides.length)}`);
13
+ return portraitFrame(context, {
14
+ counter: data.counter ? `${String(slide)}/${String(data.slides.length)}` : null,
15
+ cta: current.cta,
16
+ source: current.source,
17
+ content: [
18
+ portraitEyebrow(context, current.eyebrow),
19
+ portraitHeadline(context, current.headline),
20
+ current.body === undefined
21
+ ? null
22
+ : h("div", { style: { ...text(context, context.fonts.body, 40, 400), wordBreak: "break-word", lineHeight: 1.35, color: context.palette.muted, marginTop: px(context, 32) } }, current.body),
23
+ portraitTiles(context, current.tiles),
24
+ ],
25
+ });
26
+ },
27
+ };
@@ -6,7 +6,7 @@ import type { OgPalette } from "../palette.js";
6
6
  export interface OgTemplateContext {
7
7
  width: number;
8
8
  height: number;
9
- /** `width / 1200`: template sizes are written for a 1200-pixel-wide card and multiplied by this. */
9
+ /** Template sizes are written for the layout's base card and multiplied by this (see `getLayoutScale`). */
10
10
  scale: number;
11
11
  palette: OgPalette;
12
12
  fonts: { heading: OgFontFamily; body: OgFontFamily };
@@ -14,9 +14,22 @@ export interface OgTemplateContext {
14
14
  }
15
15
 
16
16
  export interface OgTemplate<Data> {
17
- /** Draws the card; `data` has passed the template's schema. */
18
- build(data: Data, context: OgTemplateContext): OgNode;
17
+ /** Draws the card; `data` has passed the template's schema. `slide` is 1-based; single cards have only slide 1. */
18
+ build(data: Data, context: OgTemplateContext, slide: number): OgNode;
19
19
  }
20
20
 
21
21
  export const BASE_WIDTH = 1200;
22
22
 
23
+ /**
24
+ * The card a template is written for. `landscape` templates (the 1200×630 share cards) scale by width alone, as
25
+ * they always did; `portrait` templates are written for a 1080×1350 post and scale by the limiting side, so a
26
+ * square or a story never overflows what the portrait fits.
27
+ */
28
+ export type OgLayout = "landscape" | "portrait";
29
+
30
+ export const PORTRAIT_BASE: readonly [number, number] = [1080, 1350];
31
+
32
+ export function getLayoutScale(layout: OgLayout, width: number, height: number): number {
33
+ if (layout === "landscape") return width / BASE_WIDTH;
34
+ return Math.min(width / PORTRAIT_BASE[0], height / PORTRAIT_BASE[1]);
35
+ }
@@ -2,12 +2,12 @@ import { pickWeight, toFontFamilyCss, type OgFontFamily, type OgFontWeight } fro
2
2
  import { h, type OgChild, type OgNode, type OgStyle } from "../element.js";
3
3
  import type { OgTemplateContext } from "./context.js";
4
4
 
5
- /** Text in a family (and its subset families) at a size written for the 1200-pixel card, in the loaded weight nearest `wish`. */
5
+ /** Text in a family (and its subset families) at a size written for the layout's base card, in the loaded weight nearest `wish`. */
6
6
  export function text(context: OgTemplateContext, family: OgFontFamily, size: number, wish: OgFontWeight): OgStyle {
7
7
  return { fontFamily: toFontFamilyCss(family), fontSize: Math.round(size * context.scale), fontWeight: pickWeight(family.weights, wish) };
8
8
  }
9
9
 
10
- /** A length written for the 1200-pixel card. */
10
+ /** A length written for the layout's base card. */
11
11
  export function px(context: OgTemplateContext, value: number): number {
12
12
  return Math.round(value * context.scale);
13
13
  }
@@ -1,25 +1,47 @@
1
1
  import type { z } from "zod";
2
2
 
3
3
  import type { OgNode } from "../element.js";
4
- import type { OgTemplateContext } from "./context.js";
4
+ import { bigNumberTemplate } from "./big-number.js";
5
+ import { carouselTemplate } from "./carousel.js";
6
+ import type { OgLayout, OgTemplateContext } from "./context.js";
5
7
  import { headlineChartTemplate } from "./headline-chart.js";
6
8
  import { headlineCtaTemplate } from "./headline-cta.js";
7
- import { headlineChartDataSchema, headlineCtaDataSchema } from "./schemas.js";
9
+ import { bigNumberDataSchema, carouselDataSchema, headlineChartDataSchema, headlineCtaDataSchema } from "./schemas.js";
8
10
 
9
- /** A template with its data schema; `build` takes data that passed it. */
11
+ /** A template with its data schema; `build` and `countSlides` take data that passed it. */
10
12
  interface RegisteredTemplate {
11
13
  schema: z.ZodType;
12
- build(data: unknown, context: OgTemplateContext): OgNode;
14
+ layout: OgLayout;
15
+ /** How many images the data makes; 1 for a single card. */
16
+ countSlides(data: unknown): number;
17
+ build(data: unknown, context: OgTemplateContext, slide: number): OgNode;
13
18
  }
14
19
 
15
- function register<Schema extends z.ZodType>(schema: Schema, template: { build(data: z.output<Schema>, context: OgTemplateContext): OgNode }): RegisteredTemplate {
16
- // `data` reaches `build` only after `schema` parsed it (see `buildOgTree`).
17
- return { schema, build: (data, context) => template.build(data as z.output<Schema>, context) };
20
+ interface TemplateDefinition<Data> {
21
+ layout: OgLayout;
22
+ build(data: Data, context: OgTemplateContext, slide: number): OgNode;
23
+ countSlides?(data: Data): number;
24
+ }
25
+
26
+ function register<Schema extends z.ZodType>(schema: Schema, template: TemplateDefinition<z.output<Schema>>): RegisteredTemplate {
27
+ // `data` reaches `build` and `countSlides` only after `schema` parsed it (see `buildOgTree`).
28
+ return {
29
+ schema,
30
+ layout: template.layout,
31
+ countSlides: (data) => template.countSlides?.(data as z.output<Schema>) ?? 1,
32
+ build: (data, context, slide) => template.build(data as z.output<Schema>, context, slide),
33
+ };
18
34
  }
19
35
 
20
36
  export const OG_TEMPLATES = {
21
- "headline-cta": register(headlineCtaDataSchema, headlineCtaTemplate),
22
- "headline-chart": register(headlineChartDataSchema, headlineChartTemplate),
37
+ "headline-cta": register(headlineCtaDataSchema, { layout: "landscape", build: (data, context, slide) => headlineCtaTemplate.build(data, context, slide) }),
38
+ "headline-chart": register(headlineChartDataSchema, { layout: "landscape", build: (data, context, slide) => headlineChartTemplate.build(data, context, slide) }),
39
+ "big-number": register(bigNumberDataSchema, { layout: "portrait", build: (data, context, slide) => bigNumberTemplate.build(data, context, slide) }),
40
+ carousel: register(carouselDataSchema, {
41
+ layout: "portrait",
42
+ build: (data, context, slide) => carouselTemplate.build(data, context, slide),
43
+ countSlides: (data) => data.slides.length,
44
+ }),
23
45
  } as const satisfies Record<string, RegisteredTemplate>;
24
46
 
25
47
  export type OgTemplateId = keyof typeof OG_TEMPLATES;