@softure-ai/marketing-kit 0.1.7 → 0.1.8

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 (107) hide show
  1. package/README.md +79 -11
  2. package/dist/cli/main.js +84 -29
  3. package/dist/cli/main.js.map +1 -1
  4. package/dist/cli/og.d.ts +4 -1
  5. package/dist/cli/og.d.ts.map +1 -1
  6. package/dist/cli/og.js +15 -7
  7. package/dist/cli/og.js.map +1 -1
  8. package/dist/cli/options.d.ts +26 -2
  9. package/dist/cli/options.d.ts.map +1 -1
  10. package/dist/cli/options.js +97 -9
  11. package/dist/cli/options.js.map +1 -1
  12. package/dist/cli/voice.d.ts +14 -0
  13. package/dist/cli/voice.d.ts.map +1 -1
  14. package/dist/cli/voice.js +13 -0
  15. package/dist/cli/voice.js.map +1 -1
  16. package/dist/config/actions-schema.d.ts +14 -14
  17. package/dist/config/config.d.ts +2 -0
  18. package/dist/config/config.d.ts.map +1 -1
  19. package/dist/config/config.js +1 -1
  20. package/dist/config/config.js.map +1 -1
  21. package/dist/config/og-image-names.d.ts +7 -0
  22. package/dist/config/og-image-names.d.ts.map +1 -0
  23. package/dist/config/og-image-names.js +9 -0
  24. package/dist/config/og-image-names.js.map +1 -0
  25. package/dist/config/schema.d.ts +103 -15
  26. package/dist/config/schema.d.ts.map +1 -1
  27. package/dist/config/schema.js +64 -7
  28. package/dist/config/schema.js.map +1 -1
  29. package/dist/index.d.ts +5 -3
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +5 -3
  32. package/dist/index.js.map +1 -1
  33. package/dist/og/index.d.ts +3 -3
  34. package/dist/og/index.d.ts.map +1 -1
  35. package/dist/og/index.js +3 -2
  36. package/dist/og/index.js.map +1 -1
  37. package/dist/og/render.d.ts +13 -0
  38. package/dist/og/render.d.ts.map +1 -1
  39. package/dist/og/render.js +31 -6
  40. package/dist/og/render.js.map +1 -1
  41. package/dist/og/templates/big-number.d.ts +7 -0
  42. package/dist/og/templates/big-number.d.ts.map +1 -0
  43. package/dist/og/templates/big-number.js +41 -0
  44. package/dist/og/templates/big-number.js.map +1 -0
  45. package/dist/og/templates/carousel.d.ts +5 -0
  46. package/dist/og/templates/carousel.d.ts.map +1 -0
  47. package/dist/og/templates/carousel.js +26 -0
  48. package/dist/og/templates/carousel.js.map +1 -0
  49. package/dist/og/templates/context.d.ts +11 -3
  50. package/dist/og/templates/context.d.ts.map +1 -1
  51. package/dist/og/templates/context.js +6 -0
  52. package/dist/og/templates/context.js.map +1 -1
  53. package/dist/og/templates/frame.d.ts +2 -2
  54. package/dist/og/templates/frame.d.ts.map +1 -1
  55. package/dist/og/templates/frame.js +2 -2
  56. package/dist/og/templates/frame.js.map +1 -1
  57. package/dist/og/templates/index.d.ts +8 -3
  58. package/dist/og/templates/index.d.ts.map +1 -1
  59. package/dist/og/templates/index.js +18 -5
  60. package/dist/og/templates/index.js.map +1 -1
  61. package/dist/og/templates/portrait.d.ts +22 -0
  62. package/dist/og/templates/portrait.d.ts.map +1 -0
  63. package/dist/og/templates/portrait.js +75 -0
  64. package/dist/og/templates/portrait.js.map +1 -0
  65. package/dist/og/templates/schemas.d.ts +28 -0
  66. package/dist/og/templates/schemas.d.ts.map +1 -1
  67. package/dist/og/templates/schemas.js +26 -0
  68. package/dist/og/templates/schemas.js.map +1 -1
  69. package/dist/screenshot/gates.d.ts +6 -3
  70. package/dist/screenshot/gates.d.ts.map +1 -1
  71. package/dist/screenshot/gates.js +12 -3
  72. package/dist/screenshot/gates.js.map +1 -1
  73. package/dist/screenshot/screenshot.d.ts +17 -0
  74. package/dist/screenshot/screenshot.d.ts.map +1 -1
  75. package/dist/screenshot/screenshot.js +37 -6
  76. package/dist/screenshot/screenshot.js.map +1 -1
  77. package/dist/screenshot/storage-state.d.ts +9 -0
  78. package/dist/screenshot/storage-state.d.ts.map +1 -0
  79. package/dist/screenshot/storage-state.js +25 -0
  80. package/dist/screenshot/storage-state.js.map +1 -0
  81. package/dist/voice/placeholder.d.ts +35 -0
  82. package/dist/voice/placeholder.d.ts.map +1 -0
  83. package/dist/voice/placeholder.js +53 -0
  84. package/dist/voice/placeholder.js.map +1 -0
  85. package/package.json +1 -1
  86. package/schema/marketing.schema.json +343 -37
  87. package/src/cli/main.ts +80 -27
  88. package/src/cli/og.ts +14 -6
  89. package/src/cli/options.ts +109 -10
  90. package/src/cli/voice.ts +20 -0
  91. package/src/config/config.ts +3 -2
  92. package/src/config/og-image-names.ts +7 -0
  93. package/src/config/schema.ts +72 -8
  94. package/src/index.ts +7 -1
  95. package/src/og/index.ts +16 -2
  96. package/src/og/render.ts +36 -6
  97. package/src/og/templates/big-number.ts +44 -0
  98. package/src/og/templates/carousel.ts +27 -0
  99. package/src/og/templates/context.ts +16 -3
  100. package/src/og/templates/frame.ts +2 -2
  101. package/src/og/templates/index.ts +31 -9
  102. package/src/og/templates/portrait.ts +126 -0
  103. package/src/og/templates/schemas.ts +35 -0
  104. package/src/screenshot/gates.ts +13 -3
  105. package/src/screenshot/screenshot.ts +51 -11
  106. package/src/screenshot/storage-state.ts +24 -0
  107. package/src/voice/placeholder.ts +83 -0
@@ -1,5 +1,6 @@
1
+ import { COLOR_THEMES, type ColorTheme } from "../config/colors.js";
1
2
  import { isCalendarDay } from "../config/day.js";
2
- import { DEFAULT_CONFIG_FILE, QUALITIES, type Quality } from "../config/schema.js";
3
+ import { DEFAULT_CONFIG_FILE, QUALITIES, screenshotSchema, type MarketingJson, type Quality } from "../config/schema.js";
3
4
 
4
5
  /**
5
6
  * `softure-marketing <command> <film> [flags]` (and `og [image]`, `shots [<id>]`): argument parsing, kept apart from
@@ -11,9 +12,16 @@ export const COMMANDS = ["all", "voice", "record", "render", "preview", "posts",
11
12
 
12
13
  export type Command = (typeof COMMANDS)[number];
13
14
 
14
- const KNOWN_FLAGS = ["commit", "today", "url", "quality", "config"];
15
- /** `shots` takes no film, so only the address and the config apply. */
15
+ const FILM_FLAGS = ["commit", "today", "url", "quality", "config", "placeholder"];
16
+ /** The commands that can run on the placeholder voiceover: the ones that record or render a film. */
17
+ const PLACEHOLDER_COMMANDS: readonly Command[] = ["all", "record", "render"];
18
+ /** `shots` of the configured entries takes no film, so only the address and the config apply. */
16
19
  const SHOTS_FLAGS = ["url", "config"];
20
+ /** `shots --page`: one page anywhere, its settings as flags; the same names as the entry's fields where they fit. */
21
+ const PAGE_FLAGS = ["page", "out", "expect", "width", "height", "scale", "full", "scroll", "wait", "motion", "scheme", "auth", "minbytes", "config"];
22
+ const KNOWN_FLAGS = [...new Set([...FILM_FLAGS, ...SHOTS_FLAGS, ...PAGE_FLAGS])];
23
+ /** The viewport of an ad-hoc shot without --width/--height: a common laptop screen (FIRE's screenshot script). */
24
+ export const PAGE_SHOT_VIEWPORT = { width: 1440, height: 900 } as const;
17
25
  const FILM_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
18
26
 
19
27
  export interface FilmOptions {
@@ -24,6 +32,8 @@ export interface FilmOptions {
24
32
  filmIds: string[];
25
33
  /** `voice` really pays for the voiceover only with `--commit`. */
26
34
  isCommit: boolean;
35
+ /** `--placeholder`: record and render on the free placeholder voiceover instead of the paid one. */
36
+ isPlaceholder: boolean;
27
37
  /** The day the app counts from; overrides the video's `today` for one run. */
28
38
  today?: string;
29
39
  /** Another address of the recorded page. */
@@ -42,8 +52,9 @@ export interface OgOptions {
42
52
  }
43
53
 
44
54
  /** `shots [<id>]`: every `screenshots` entry, or the one named. */
45
- export interface ShotsOptions {
55
+ export interface EntryShotsOptions {
46
56
  command: "shots";
57
+ mode: "entries";
47
58
  /** One `screenshots` entry; without it, every entry. */
48
59
  shotId?: string;
49
60
  /** Another address of the app; each entry's path resolves against it. */
@@ -51,6 +62,23 @@ export interface ShotsOptions {
51
62
  configPath: string;
52
63
  }
53
64
 
65
+ /** `shots --page=<url> --out=<file> --expect=<phrase>`: one page anywhere, behind the same gates. */
66
+ export interface PageShotsOptions {
67
+ command: "shots";
68
+ mode: "page";
69
+ /** The page itself, not a base address. */
70
+ page: string;
71
+ /** The PNG to write, relative to the current directory. */
72
+ out: string;
73
+ /** The shot's settings in the shape of a `screenshots` entry (`id` "page", `path` "/"; `storageState` as given). */
74
+ entry: MarketingJson["screenshots"][number];
75
+ /** `--scheme`; without it, `app.colorScheme`. */
76
+ scheme?: ColorTheme;
77
+ configPath: string;
78
+ }
79
+
80
+ export type ShotsOptions = EntryShotsOptions | PageShotsOptions;
81
+
54
82
  export type CliOptions = FilmOptions | OgOptions | ShotsOptions;
55
83
 
56
84
  export type ReadOptionsResult = { ok: true; options: CliOptions } | { ok: false; error: string };
@@ -58,14 +86,17 @@ export type ReadOptionsResult = { ok: true; options: CliOptions } | { ok: false;
58
86
  export const USAGE = [
59
87
  `Usage: softure-marketing <command> <film> [--config=${DEFAULT_CONFIG_FILE}]`,
60
88
  "",
61
- " all <film> voiceover from the cache -> recording -> render -> post copy",
89
+ " all <film> [--placeholder] voiceover from the cache -> recording -> render -> post copy",
62
90
  " voice <film>... [--commit] voiceovers in order; without --commit it only counts the characters",
63
- " record <film> [--today=YYYY-MM-DD] [--url=...] --today overrides the video's \"today\"",
64
- " render <film> [--quality=draft|standard|high]",
91
+ " record <film> [--today=YYYY-MM-DD] [--url=...] [--placeholder] --today overrides the video's \"today\"",
92
+ " render <film> [--quality=draft|standard|high] [--placeholder]",
93
+ " --placeholder: a free tone voiceover at a fixed pace instead of the paid one, to rehearse a film",
65
94
  " preview <film> open the composition in the hyperframes preview",
66
95
  " posts <film> post copy for the configured platforms",
67
96
  " og [image] OG images (PNG) of every ogImages entry, or of the one named",
68
97
  " shots [<id>] [--url=...] the screenshots entries (or one), each behind its quality gates",
98
+ " shots --page=<url> --out=<file.png> --expect=<phrase> [--width --height --scale --full --scroll --wait",
99
+ " --motion --scheme --auth --minbytes] one page anywhere, behind the same gates; the app is not started",
69
100
  ].join("\n");
70
101
 
71
102
  function isCommand(value: string | undefined): value is Command {
@@ -91,7 +122,8 @@ export function readOptions(argv: string[]): ReadOptionsResult {
91
122
  continue;
92
123
  }
93
124
  if (!KNOWN_FLAGS.includes(name)) {
94
- return { ok: false, error: `unknown flag --${name}. Known: ${KNOWN_FLAGS.map((flag) => `--${flag}`).join(", ")}.` };
125
+ const known = command === "shots" ? [...SHOTS_FLAGS, ...PAGE_FLAGS.filter((flag) => !SHOTS_FLAGS.includes(flag))] : FILM_FLAGS;
126
+ return { ok: false, error: `unknown flag --${name}. Known: ${known.map((flag) => `--${flag}`).join(", ")}.` };
95
127
  }
96
128
  flags.set(name, match[2] ?? "true");
97
129
  }
@@ -99,6 +131,8 @@ export function readOptions(argv: string[]): ReadOptionsResult {
99
131
  if (configPath === "true" || configPath.length === 0) return { ok: false, error: `--config needs a path, e.g. --config=${DEFAULT_CONFIG_FILE}.` };
100
132
  if (command === "og") return readOgOptions(positional, flags, configPath);
101
133
  if (command === "shots") return readShotsOptions(positional, flags, configPath);
134
+ const notForFilms = [...flags.keys()].find((flag) => !FILM_FLAGS.includes(flag));
135
+ if (notForFilms !== undefined) return { ok: false, error: `--${notForFilms} applies to shots only, not to ${command}.` };
102
136
  const filmId = positional[0];
103
137
  if (filmId === undefined) return { ok: false, error: `name the film, e.g. softure-marketing ${command} <film>.` };
104
138
  if (positional.length > 1 && command !== "voice") return { ok: false, error: `one film at a time, got ${positional.join(", ")}; only voice takes several.` };
@@ -117,9 +151,14 @@ export function readOptions(argv: string[]): ReadOptionsResult {
117
151
  }
118
152
  const url = flags.get("url");
119
153
  if (url === "true") return { ok: false, error: "--url needs an address, e.g. --url=http://localhost:3000/calculator." };
154
+ const placeholder = flags.get("placeholder");
155
+ if (placeholder !== undefined && placeholder !== "true") return { ok: false, error: `--placeholder takes no value (got "${placeholder}").` };
156
+ if (placeholder !== undefined && !PLACEHOLDER_COMMANDS.includes(command)) {
157
+ return { ok: false, error: `--placeholder applies to ${PLACEHOLDER_COMMANDS.join(", ")}: the commands that record or render a film, not ${command}.` };
158
+ }
120
159
  return {
121
160
  ok: true,
122
- options: { command, filmId, filmIds: positional, isCommit: commit === "true", today, url, quality, configPath },
161
+ options: { command, filmId, filmIds: positional, isCommit: commit === "true", isPlaceholder: placeholder === "true", today, url, quality, configPath },
123
162
  };
124
163
  }
125
164
 
@@ -138,6 +177,7 @@ function isHttpAddress(value: string): boolean {
138
177
  }
139
178
 
140
179
  function readShotsOptions(positional: string[], flags: Map<string, string>, configPath: string): ReadOptionsResult {
180
+ if (flags.has("page")) return readPageShotOptions(positional, flags, configPath);
141
181
  const unknown = [...flags.keys()].find((flag) => !SHOTS_FLAGS.includes(flag));
142
182
  if (unknown !== undefined) return { ok: false, error: `--${unknown} does not apply to shots. Known: ${SHOTS_FLAGS.map((flag) => `--${flag}`).join(", ")}.` };
143
183
  if (positional.length > 1) return { ok: false, error: `one screenshot at a time, got ${positional.join(", ")}; without an id, shots takes them all.` };
@@ -146,7 +186,66 @@ function readShotsOptions(positional: string[], flags: Map<string, string>, conf
146
186
  const url = flags.get("url");
147
187
  if (url === "true") return { ok: false, error: "--url needs an address, e.g. --url=http://localhost:3000." };
148
188
  if (url !== undefined && !isHttpAddress(url)) return { ok: false, error: `--url=${url}: expected an address such as http://localhost:3000.` };
149
- return { ok: true, options: { command: "shots", shotId, url, configPath } };
189
+ return { ok: true, options: { command: "shots", mode: "entries", shotId, url, configPath } };
190
+ }
191
+
192
+ /** The flag each field of an ad-hoc shot comes from, so a schema issue names what the user typed. */
193
+ const PAGE_FIELD_FLAGS: Record<string, string> = {
194
+ expect: "expect",
195
+ width: "width",
196
+ height: "height",
197
+ scale: "scale",
198
+ full: "full",
199
+ scrollTo: "scroll",
200
+ waitMs: "wait",
201
+ motion: "motion",
202
+ storageState: "auth",
203
+ minBytes: "minbytes",
204
+ };
205
+
206
+ /** A number flag as written, or the text itself, so the schema reports it ("expected number, received string"). */
207
+ function readNumber(value: string | undefined): number | string | undefined {
208
+ if (value === undefined) return undefined;
209
+ const number = Number(value);
210
+ return value.trim().length > 0 && Number.isFinite(number) ? number : value;
211
+ }
212
+
213
+ function readPageShotOptions(positional: string[], flags: Map<string, string>, configPath: string): ReadOptionsResult {
214
+ const unknown = [...flags.keys()].find((flag) => !PAGE_FLAGS.includes(flag));
215
+ if (unknown !== undefined) return { ok: false, error: `--${unknown} does not apply to shots --page. Known: ${PAGE_FLAGS.map((flag) => `--${flag}`).join(", ")}.` };
216
+ if (positional.length > 0) return { ok: false, error: `shots --page takes no screenshot id, got ${positional.join(", ")}.` };
217
+ const valued = [...flags.entries()].find(([name, value]) => name !== "full" && value === "true");
218
+ if (valued !== undefined) return { ok: false, error: `--${valued[0]} needs a value, e.g. --${valued[0]}=<value>.` };
219
+ const page = flags.get("page") ?? "";
220
+ if (!isHttpAddress(page)) return { ok: false, error: `--page=${page}: expected the page's http(s) address, e.g. https://example.com/pricing.` };
221
+ const out = flags.get("out");
222
+ if (out === undefined || !out.toLowerCase().endsWith(".png")) return { ok: false, error: "shots --page needs --out=<file.png>, the screenshot to write." };
223
+ if (!flags.has("expect")) return { ok: false, error: 'shots --page needs --expect=<phrase>: a phrase the page must show, so an error page is never kept as the screenshot.' };
224
+ const full = flags.get("full");
225
+ if (full !== undefined && full !== "true") return { ok: false, error: `--full takes no value (got "${full}").` };
226
+ const schemeFlag = flags.get("scheme");
227
+ const scheme = COLOR_THEMES.find((theme) => theme === schemeFlag);
228
+ if (schemeFlag !== undefined && scheme === undefined) return { ok: false, error: `--scheme=${schemeFlag}: expected ${COLOR_THEMES.join(" | ")}.` };
229
+ const parsed = screenshotSchema.safeParse({
230
+ id: "page",
231
+ path: "/",
232
+ expect: flags.get("expect"),
233
+ width: readNumber(flags.get("width")) ?? PAGE_SHOT_VIEWPORT.width,
234
+ height: readNumber(flags.get("height")) ?? PAGE_SHOT_VIEWPORT.height,
235
+ scale: readNumber(flags.get("scale")),
236
+ full: full === "true",
237
+ scrollTo: readNumber(flags.get("scroll")),
238
+ waitMs: readNumber(flags.get("wait")),
239
+ motion: flags.get("motion"),
240
+ storageState: flags.get("auth"),
241
+ minBytes: readNumber(flags.get("minbytes")),
242
+ });
243
+ if (!parsed.success) {
244
+ const [issue] = parsed.error.issues;
245
+ const field = String(issue?.path[0] ?? "");
246
+ return { ok: false, error: `--${PAGE_FIELD_FLAGS[field] ?? field}: ${issue?.message ?? "invalid"}.` };
247
+ }
248
+ return { ok: true, options: { command: "shots", mode: "page", page, out, entry: parsed.data, scheme, configPath } };
150
249
  }
151
250
 
152
251
  /** The day a recording starts its page clock at, and where it came from. */
package/src/cli/voice.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
2
3
 
3
4
  import type { MarketingConfig } from "../config/config.js";
4
5
  import type { Film } from "../film.js";
@@ -6,6 +7,7 @@ import { getVoiceoverPaths as getCachePaths, readCachedVoiceover, type Voiceover
6
7
  import { describeVoiceoverBatch, produceVoiceovers as produceBatch } from "../voice/batch.js";
7
8
  import { produceVoiceover as produce, type ProduceVoiceoverOptions } from "../voice/produce.js";
8
9
  import type { TtsInput } from "../voice/provider.js";
10
+ import { getPlaceholderKey, writePlaceholderVoiceover } from "../voice/placeholder.js";
9
11
  import { createTtsProvider } from "../voice/providers.js";
10
12
  import { voiceoverText } from "../voice/voiceover.js";
11
13
  import { fail } from "./failure.js";
@@ -36,6 +38,24 @@ export function requireVoiceover(config: MarketingConfig, film: Film): Voiceover
36
38
  return cached.value;
37
39
  }
38
40
 
41
+ /** The voiceover a recording or a render uses, and the key its log carries. */
42
+ export interface FilmVoiceover {
43
+ voiceover: Voiceover;
44
+ key: string;
45
+ isPlaceholder: boolean;
46
+ }
47
+
48
+ /**
49
+ * The paid voiceover from the cache, or with `--placeholder` a free one written into `<buildDir>/placeholder/` (never
50
+ * into the cache, where it would be a hit for the real key). Its key is marked, so the two never mix in one film.
51
+ */
52
+ export function getFilmVoiceover(config: MarketingConfig, film: Film, options: { isPlaceholder: boolean; buildDir: string }): FilmVoiceover {
53
+ const { key } = getVoiceoverPaths(config, film);
54
+ if (!options.isPlaceholder) return { voiceover: requireVoiceover(config, film), key, isPlaceholder: false };
55
+ const voiceover = writePlaceholderVoiceover({ dir: join(options.buildDir, "placeholder"), sentences: film.beats, pace: config.voice.placeholder });
56
+ return { voiceover, key: getPlaceholderKey(key), isPlaceholder: true };
57
+ }
58
+
39
59
  function getProduceOptions(config: MarketingConfig, film: Film, isCommit: boolean): ProduceVoiceoverOptions {
40
60
  return {
41
61
  cacheDir: config.voice.cacheDir,
@@ -5,6 +5,7 @@ import { getLayoutName } from "../compose/timeline.js";
5
5
  import type { Device, FilmScript } from "../film.js";
6
6
  import type { MarketingLocale } from "../messages/index.js";
7
7
  import { DEFAULT_LINK_IN_BIO, PLATFORMS, type Platform } from "../platforms.js";
8
+ import type { PlaceholderPace } from "../voice/placeholder.js";
8
9
  import type { SceneAction } from "./actions-schema.js";
9
10
  import { resolveBrandColors } from "./brand.js";
10
11
  import type { BrandColors, ColorTheme } from "./colors.js";
@@ -96,7 +97,7 @@ export interface MarketingConfig {
96
97
  hideSelectors: string[];
97
98
  screenGuardSelector: string;
98
99
  };
99
- voice: { provider: "elevenlabs"; cacheDir: string; minIntervalSeconds: number };
100
+ voice: { provider: "elevenlabs"; cacheDir: string; minIntervalSeconds: number; placeholder: PlaceholderPace };
100
101
  videos: VideoConfig[];
101
102
  social: { linkTemplate: string } | null;
102
103
  screenshots: MarketingJson["screenshots"];
@@ -222,7 +223,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
222
223
  hideSelectors: data.app.hideSelectors,
223
224
  screenGuardSelector: data.app.screenGuardSelector,
224
225
  },
225
- voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds },
226
+ voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds, placeholder: data.voice.placeholder },
226
227
  videos: resolveVideos(data, at),
227
228
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
228
229
  screenshots: data.screenshots,
@@ -0,0 +1,7 @@
1
+ /** The files an `ogImages` entry writes under `<output.dir>/og/`, without `.png`: `<id>`, or `<id>-1`…`<id>-N` for a carousel. */
2
+ export function getOgImageNames(entry: { id: string; template: string; data: unknown }): string[] {
3
+ if (entry.template !== "carousel") return [entry.id];
4
+ const slides = (entry.data as { slides?: unknown } | null)?.slides;
5
+ const count = Array.isArray(slides) ? slides.length : 0;
6
+ return Array.from({ length: count }, (_, index) => `${entry.id}-${String(index + 1)}`);
7
+ }
@@ -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,6 +244,13 @@ 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
256
  type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined };
@@ -445,7 +453,7 @@ const socialSchema = z.strictObject({
445
453
  .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
454
  });
447
455
 
448
- const screenshotSchema = z.strictObject({
456
+ export const screenshotSchema = z.strictObject({
449
457
  id: id.describe("The screenshot's id: the file <output.dir>/screenshots/<id>.png."),
450
458
  path: pagePath.describe("The page of the app to capture, e.g. /pricing."),
451
459
  width: pixels(8000).describe("The browser viewport's width in CSS pixels."),
@@ -461,25 +469,70 @@ const screenshotSchema = z.strictObject({
461
469
  .refine((schemes) => new Set(schemes).size === schemes.length, "lists a scheme twice")
462
470
  .optional()
463
471
  .describe('Capture each listed scheme into its own <id>-<scheme>.png, e.g. ["light", "dark"]; without it, one <id>.png in app.colorScheme.'),
472
+ scrollTo: z
473
+ .number()
474
+ .int()
475
+ .min(0)
476
+ .optional()
477
+ .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.'),
478
+ 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)."),
479
+ storageState: relativePath
480
+ .optional()
481
+ .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."),
482
+ }).superRefine((entry, context) => {
483
+ if (entry.full && entry.scrollTo !== undefined) {
484
+ 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" });
485
+ }
464
486
  });
465
487
 
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
- };
488
+ /** Named sizes of `ogImages[].size`: the share card and the three social formats. */
489
+ export const OG_SIZE_PRESETS = {
490
+ landscape: [1200, 630],
491
+ portrait: [1080, 1350],
492
+ square: [1080, 1080],
493
+ story: [1080, 1920],
494
+ } as const satisfies Record<string, readonly [number, number]>;
495
+
496
+ type OgSizePreset = keyof typeof OG_SIZE_PRESETS;
497
+
498
+ /** A preset name or `[width, height]`; the loaded config always holds the pair. */
499
+ const ogSize = (preset: OgSizePreset) =>
500
+ z
501
+ .union([z.tuple([pixels(4000), pixels(4000)]), z.enum(Object.keys(OG_SIZE_PRESETS) as [OgSizePreset, ...OgSizePreset[]])])
502
+ .transform((size): [number, number] => (typeof size === "string" ? [...OG_SIZE_PRESETS[size]] : size))
503
+ .default([...OG_SIZE_PRESETS[preset]])
504
+ .describe(
505
+ `The image size: "landscape" (1200×630), "portrait" (1080×1350), "square" (1080×1080), "story" (1080×1920) or [width, height] in pixels; "${preset}" by default.`,
506
+ );
507
+
508
+ 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
509
 
471
510
  /** One entry per template; `data` is the template's input, and values the app computes (charts) arrive precomputed. */
472
511
  const ogImageSchema = z.discriminatedUnion("template", [
473
512
  z.strictObject({
474
- ...ogImageBase,
513
+ id: ogImageId,
514
+ size: ogSize("landscape"),
475
515
  template: z.literal("headline-cta").describe("A headline with an optional eyebrow, call to action and tiles."),
476
516
  data: headlineCtaDataSchema.describe("The headline-cta template's input."),
477
517
  }),
478
518
  z.strictObject({
479
- ...ogImageBase,
519
+ id: ogImageId,
520
+ size: ogSize("landscape"),
480
521
  template: z.literal("headline-chart").describe("A headline over a chart the app computed, with optional tiles."),
481
522
  data: headlineChartDataSchema.describe("The headline-chart template's input."),
482
523
  }),
524
+ z.strictObject({
525
+ id: ogImageId,
526
+ size: ogSize("portrait"),
527
+ 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."),
528
+ data: bigNumberDataSchema.describe("The big-number template's input."),
529
+ }),
530
+ z.strictObject({
531
+ id: ogImageId,
532
+ size: ogSize("portrait"),
533
+ template: z.literal("carousel").describe("A numbered run of portrait slides sharing one look; each slide is its own file <id>-<n>.png."),
534
+ data: carouselDataSchema.describe("The carousel template's input."),
535
+ }),
483
536
  ]);
484
537
 
485
538
  /** When each sound effect plays; the descriptions of the `sfx` keys. */
@@ -611,6 +664,17 @@ export const marketingSchema = z
611
664
  });
612
665
  checkUnique("screenshots");
613
666
  checkUnique("ogImages");
667
+ const ogFileOwners = new Map<string, number>();
668
+ config.ogImages.forEach((entry, index) => {
669
+ for (const name of getOgImageNames(entry)) {
670
+ const owner = ogFileOwners.get(name);
671
+ // Two entries with one id are reported by checkUnique already.
672
+ if (owner !== undefined && owner !== index && config.ogImages[owner]?.id !== entry.id) {
673
+ context.addIssue({ code: "custom", path: ["ogImages", index, "id"], message: `writes og/${name}.png, as ogImages[${String(owner)}] does` });
674
+ }
675
+ ogFileOwners.set(name, owner ?? index);
676
+ }
677
+ });
614
678
  const fileOwners = new Map<string, number>();
615
679
  config.screenshots.forEach((entry, index) => {
616
680
  for (const name of getScreenshotNames(entry.id)) {
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
+ };