@softure-ai/marketing-kit 0.1.6 → 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 (135) hide show
  1. package/README.md +100 -17
  2. package/dist/cli/main.js +93 -33
  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 +29 -2
  9. package/dist/cli/options.d.ts.map +1 -1
  10. package/dist/cli/options.js +106 -14
  11. package/dist/cli/options.js.map +1 -1
  12. package/dist/cli/voice.d.ts +19 -0
  13. package/dist/cli/voice.d.ts.map +1 -1
  14. package/dist/cli/voice.js +37 -5
  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 +5 -0
  18. package/dist/config/config.d.ts.map +1 -1
  19. package/dist/config/config.js +2 -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 +106 -15
  26. package/dist/config/schema.d.ts.map +1 -1
  27. package/dist/config/schema.js +74 -7
  28. package/dist/config/schema.js.map +1 -1
  29. package/dist/index.d.ts +8 -4
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +8 -4
  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/posts/posts.d.ts +2 -1
  70. package/dist/posts/posts.d.ts.map +1 -1
  71. package/dist/posts/posts.js +1 -1
  72. package/dist/posts/posts.js.map +1 -1
  73. package/dist/screenshot/gates.d.ts +6 -3
  74. package/dist/screenshot/gates.d.ts.map +1 -1
  75. package/dist/screenshot/gates.js +12 -3
  76. package/dist/screenshot/gates.js.map +1 -1
  77. package/dist/screenshot/screenshot.d.ts +17 -0
  78. package/dist/screenshot/screenshot.d.ts.map +1 -1
  79. package/dist/screenshot/screenshot.js +37 -6
  80. package/dist/screenshot/screenshot.js.map +1 -1
  81. package/dist/screenshot/storage-state.d.ts +9 -0
  82. package/dist/screenshot/storage-state.d.ts.map +1 -0
  83. package/dist/screenshot/storage-state.js +25 -0
  84. package/dist/screenshot/storage-state.js.map +1 -0
  85. package/dist/voice/batch.d.ts +28 -0
  86. package/dist/voice/batch.d.ts.map +1 -0
  87. package/dist/voice/batch.js +46 -0
  88. package/dist/voice/batch.js.map +1 -0
  89. package/dist/voice/elevenlabs.d.ts.map +1 -1
  90. package/dist/voice/elevenlabs.js +11 -1
  91. package/dist/voice/elevenlabs.js.map +1 -1
  92. package/dist/voice/pace.d.ts +22 -0
  93. package/dist/voice/pace.d.ts.map +1 -0
  94. package/dist/voice/pace.js +39 -0
  95. package/dist/voice/pace.js.map +1 -0
  96. package/dist/voice/placeholder.d.ts +35 -0
  97. package/dist/voice/placeholder.d.ts.map +1 -0
  98. package/dist/voice/placeholder.js +53 -0
  99. package/dist/voice/placeholder.js.map +1 -0
  100. package/dist/voice/produce.d.ts +6 -0
  101. package/dist/voice/produce.d.ts.map +1 -1
  102. package/dist/voice/produce.js +13 -2
  103. package/dist/voice/produce.js.map +1 -1
  104. package/dist/voice/provider.d.ts +2 -0
  105. package/dist/voice/provider.d.ts.map +1 -1
  106. package/dist/voice/provider.js.map +1 -1
  107. package/package.json +1 -1
  108. package/schema/marketing.schema.json +359 -37
  109. package/src/cli/main.ts +88 -31
  110. package/src/cli/og.ts +14 -6
  111. package/src/cli/options.ts +118 -13
  112. package/src/cli/voice.ts +44 -6
  113. package/src/config/config.ts +7 -2
  114. package/src/config/og-image-names.ts +7 -0
  115. package/src/config/schema.ts +82 -8
  116. package/src/index.ts +10 -2
  117. package/src/og/index.ts +16 -2
  118. package/src/og/render.ts +36 -6
  119. package/src/og/templates/big-number.ts +44 -0
  120. package/src/og/templates/carousel.ts +27 -0
  121. package/src/og/templates/context.ts +16 -3
  122. package/src/og/templates/frame.ts +2 -2
  123. package/src/og/templates/index.ts +31 -9
  124. package/src/og/templates/portrait.ts +126 -0
  125. package/src/og/templates/schemas.ts +35 -0
  126. package/src/posts/posts.ts +3 -2
  127. package/src/screenshot/gates.ts +13 -3
  128. package/src/screenshot/screenshot.ts +51 -11
  129. package/src/screenshot/storage-state.ts +24 -0
  130. package/src/voice/batch.ts +65 -0
  131. package/src/voice/elevenlabs.ts +11 -1
  132. package/src/voice/pace.ts +55 -0
  133. package/src/voice/placeholder.ts +83 -0
  134. package/src/voice/produce.ts +15 -3
  135. package/src/voice/provider.ts +2 -0
package/src/cli/og.ts CHANGED
@@ -2,10 +2,14 @@ import { mkdirSync, writeFileSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
 
4
4
  import type { MarketingConfig } from "../config/config.js";
5
+ import { getOgImageNames } from "../config/og-image-names.js";
5
6
  import { renderConfiguredOgImage } from "../og/render.js";
6
7
  import { fail } from "./failure.js";
7
8
 
8
- /** `og [image]`: writes `<output.dir>/og/<id>.png` for every `ogImages` entry, or for the one named. */
9
+ /**
10
+ * `og [image]`: writes `<output.dir>/og/<id>.png` for every `ogImages` entry, or for the one named; a carousel
11
+ * writes one file per slide, `<id>-1.png`…`<id>-<n>.png`.
12
+ */
9
13
  export async function writeOgImages(config: MarketingConfig, imageId: string | null): Promise<void> {
10
14
  const entries = imageId === null ? config.ogImages : config.ogImages.filter((image) => image.id === imageId);
11
15
  if (config.ogImages.length === 0) fail(`no OG images: add entries to ogImages in ${config.file}.`);
@@ -15,10 +19,14 @@ export async function writeOgImages(config: MarketingConfig, imageId: string | n
15
19
  const dir = join(config.output.dir, "og");
16
20
  mkdirSync(dir, { recursive: true });
17
21
  for (const entry of entries) {
18
- const png = await renderConfiguredOgImage({ config, id: entry.id });
19
- if (!png.ok) fail(png.error);
20
- const path = join(dir, `${entry.id}.png`);
21
- writeFileSync(path, png.value);
22
- console.log(`✓ ${path} (${entry.size[0]}×${entry.size[1]}, ${entry.template})`);
22
+ const names = getOgImageNames(entry);
23
+ for (const [index, name] of names.entries()) {
24
+ const png = await renderConfiguredOgImage({ config, id: entry.id, slide: index + 1 });
25
+ if (!png.ok) fail(png.error);
26
+ const path = join(dir, `${name}.png`);
27
+ writeFileSync(path, png.value);
28
+ const slide = names.length > 1 ? `, slide ${String(index + 1)}/${String(names.length)}` : "";
29
+ console.log(`✓ ${path} (${String(entry.size[0])}×${String(entry.size[1])}, ${entry.template}${slide})`);
30
+ }
23
31
  }
24
32
  }
@@ -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,16 +12,28 @@ 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 {
20
28
  command: Exclude<Command, "og" | "shots">;
29
+ /** The first film named; the only one for every command but `voice`. */
21
30
  filmId: string;
31
+ /** Every film named, in order; `voice` takes several, the other commands one. */
32
+ filmIds: string[];
22
33
  /** `voice` really pays for the voiceover only with `--commit`. */
23
34
  isCommit: boolean;
35
+ /** `--placeholder`: record and render on the free placeholder voiceover instead of the paid one. */
36
+ isPlaceholder: boolean;
24
37
  /** The day the app counts from; overrides the video's `today` for one run. */
25
38
  today?: string;
26
39
  /** Another address of the recorded page. */
@@ -39,8 +52,9 @@ export interface OgOptions {
39
52
  }
40
53
 
41
54
  /** `shots [<id>]`: every `screenshots` entry, or the one named. */
42
- export interface ShotsOptions {
55
+ export interface EntryShotsOptions {
43
56
  command: "shots";
57
+ mode: "entries";
44
58
  /** One `screenshots` entry; without it, every entry. */
45
59
  shotId?: string;
46
60
  /** Another address of the app; each entry's path resolves against it. */
@@ -48,6 +62,23 @@ export interface ShotsOptions {
48
62
  configPath: string;
49
63
  }
50
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
+
51
82
  export type CliOptions = FilmOptions | OgOptions | ShotsOptions;
52
83
 
53
84
  export type ReadOptionsResult = { ok: true; options: CliOptions } | { ok: false; error: string };
@@ -55,14 +86,17 @@ export type ReadOptionsResult = { ok: true; options: CliOptions } | { ok: false;
55
86
  export const USAGE = [
56
87
  `Usage: softure-marketing <command> <film> [--config=${DEFAULT_CONFIG_FILE}]`,
57
88
  "",
58
- " all <film> voiceover from the cache -> recording -> render -> post copy",
59
- " voice <film> [--commit] voiceover; without --commit it only counts the characters",
60
- " record <film> [--today=YYYY-MM-DD] [--url=...] --today overrides the video's \"today\"",
61
- " render <film> [--quality=draft|standard|high]",
89
+ " all <film> [--placeholder] voiceover from the cache -> recording -> render -> post copy",
90
+ " voice <film>... [--commit] voiceovers in order; without --commit it only counts the characters",
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",
62
94
  " preview <film> open the composition in the hyperframes preview",
63
95
  " posts <film> post copy for the configured platforms",
64
96
  " og [image] OG images (PNG) of every ogImages entry, or of the one named",
65
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",
66
100
  ].join("\n");
67
101
 
68
102
  function isCommand(value: string | undefined): value is Command {
@@ -88,7 +122,8 @@ export function readOptions(argv: string[]): ReadOptionsResult {
88
122
  continue;
89
123
  }
90
124
  if (!KNOWN_FLAGS.includes(name)) {
91
- 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(", ")}.` };
92
127
  }
93
128
  flags.set(name, match[2] ?? "true");
94
129
  }
@@ -96,10 +131,15 @@ export function readOptions(argv: string[]): ReadOptionsResult {
96
131
  if (configPath === "true" || configPath.length === 0) return { ok: false, error: `--config needs a path, e.g. --config=${DEFAULT_CONFIG_FILE}.` };
97
132
  if (command === "og") return readOgOptions(positional, flags, configPath);
98
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}.` };
99
136
  const filmId = positional[0];
100
137
  if (filmId === undefined) return { ok: false, error: `name the film, e.g. softure-marketing ${command} <film>.` };
101
- if (positional.length > 1) return { ok: false, error: `one film at a time, got ${positional.join(", ")}.` };
102
- if (!FILM_ID.test(filmId)) return { ok: false, error: `film name "${filmId}": lowercase letters, digits and hyphens only.` };
138
+ if (positional.length > 1 && command !== "voice") return { ok: false, error: `one film at a time, got ${positional.join(", ")}; only voice takes several.` };
139
+ const badId = positional.find((id) => !FILM_ID.test(id));
140
+ if (badId !== undefined) return { ok: false, error: `film name "${badId}": lowercase letters, digits and hyphens only.` };
141
+ const repeated = positional.find((id, index) => positional.indexOf(id) !== index);
142
+ if (repeated !== undefined) return { ok: false, error: `film "${repeated}" is named twice.` };
103
143
  const today = flags.get("today");
104
144
  if (today !== undefined && !isCalendarDay(today)) return { ok: false, error: `--today=${today}: expected a real day as YYYY-MM-DD.` };
105
145
  const quality = flags.get("quality");
@@ -111,9 +151,14 @@ export function readOptions(argv: string[]): ReadOptionsResult {
111
151
  }
112
152
  const url = flags.get("url");
113
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
+ }
114
159
  return {
115
160
  ok: true,
116
- options: { command, filmId, isCommit: commit === "true", today, url, quality, configPath },
161
+ options: { command, filmId, filmIds: positional, isCommit: commit === "true", isPlaceholder: placeholder === "true", today, url, quality, configPath },
117
162
  };
118
163
  }
119
164
 
@@ -132,6 +177,7 @@ function isHttpAddress(value: string): boolean {
132
177
  }
133
178
 
134
179
  function readShotsOptions(positional: string[], flags: Map<string, string>, configPath: string): ReadOptionsResult {
180
+ if (flags.has("page")) return readPageShotOptions(positional, flags, configPath);
135
181
  const unknown = [...flags.keys()].find((flag) => !SHOTS_FLAGS.includes(flag));
136
182
  if (unknown !== undefined) return { ok: false, error: `--${unknown} does not apply to shots. Known: ${SHOTS_FLAGS.map((flag) => `--${flag}`).join(", ")}.` };
137
183
  if (positional.length > 1) return { ok: false, error: `one screenshot at a time, got ${positional.join(", ")}; without an id, shots takes them all.` };
@@ -140,7 +186,66 @@ function readShotsOptions(positional: string[], flags: Map<string, string>, conf
140
186
  const url = flags.get("url");
141
187
  if (url === "true") return { ok: false, error: "--url needs an address, e.g. --url=http://localhost:3000." };
142
188
  if (url !== undefined && !isHttpAddress(url)) return { ok: false, error: `--url=${url}: expected an address such as http://localhost:3000.` };
143
- 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 } };
144
249
  }
145
250
 
146
251
  /** The day a recording starts its page clock at, and where it came from. */
package/src/cli/voice.ts CHANGED
@@ -1,10 +1,13 @@
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";
5
6
  import { getVoiceoverPaths as getCachePaths, readCachedVoiceover, type Voiceover, type VoiceoverPaths } from "../voice/cache.js";
6
- import { produceVoiceover as produce } from "../voice/produce.js";
7
+ import { describeVoiceoverBatch, produceVoiceovers as produceBatch } from "../voice/batch.js";
8
+ import { produceVoiceover as produce, type ProduceVoiceoverOptions } from "../voice/produce.js";
7
9
  import type { TtsInput } from "../voice/provider.js";
10
+ import { getPlaceholderKey, writePlaceholderVoiceover } from "../voice/placeholder.js";
8
11
  import { createTtsProvider } from "../voice/providers.js";
9
12
  import { voiceoverText } from "../voice/voiceover.js";
10
13
  import { fail } from "./failure.js";
@@ -35,19 +38,54 @@ export function requireVoiceover(config: MarketingConfig, film: Film): Voiceover
35
38
  return cached.value;
36
39
  }
37
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
+
38
48
  /**
39
- * The voiceover from the cache, or a paid recording from the configured provider with `--commit`.
40
- * Without `--commit` it prints the cost estimate, spends nothing and returns null.
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.
41
51
  */
42
- export async function produceVoiceover(config: MarketingConfig, film: Film, isCommit: boolean): Promise<Voiceover | null> {
43
- const result = await produce({
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
+
59
+ function getProduceOptions(config: MarketingConfig, film: Film, isCommit: boolean): ProduceVoiceoverOptions {
60
+ return {
44
61
  cacheDir: config.voice.cacheDir,
45
62
  input: getTtsInput(film),
46
63
  videoId: film.id,
47
64
  provider: createTtsProvider(config.voice.provider, { env: process.env }),
48
65
  isCommit,
66
+ pace: { minIntervalSeconds: config.voice.minIntervalSeconds },
49
67
  log: (line) => console.log(line),
50
- });
68
+ };
69
+ }
70
+
71
+ /**
72
+ * The voiceover from the cache, or a paid recording from the configured provider with `--commit`.
73
+ * Without `--commit` it prints the cost estimate, spends nothing and returns null.
74
+ */
75
+ export async function produceVoiceover(config: MarketingConfig, film: Film, isCommit: boolean): Promise<Voiceover | null> {
76
+ const result = await produce(getProduceOptions(config, film, isCommit));
51
77
  if (!result.ok) fail(result.error);
52
78
  return result.value.kind === "dry-run" ? null : result.value.voiceover;
53
79
  }
80
+
81
+ /**
82
+ * `voice <film>...`: the films' voiceovers in order, paid calls spaced by `voice.minIntervalSeconds`. The first
83
+ * failure stops the batch; the summary names what was recorded, where it stopped and what was never sent.
84
+ */
85
+ export async function produceVoiceovers(config: MarketingConfig, films: Film[], isCommit: boolean): Promise<void> {
86
+ const result = await produceBatch(films.map((film) => ({ id: film.id, options: getProduceOptions(config, film, isCommit) })));
87
+ if (films.length > 1) console.log(["", ...describeVoiceoverBatch(result)].join("\n"));
88
+ if (result.failed === null) return;
89
+ if (films.length > 1) fail(`the batch stopped at ${result.failed.id}; ${result.notAttempted.length} ${result.notAttempted.length === 1 ? "film was" : "films were"} not sent. See above.`);
90
+ fail(result.failed.error);
91
+ }
@@ -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";
@@ -41,6 +42,8 @@ export interface PlatformChannel {
41
42
 
42
43
  export interface VideoPost {
43
44
  caption: string;
45
+ /** `social.disclosure` with the persona's name; null or absent when none is configured or the post opts out. */
46
+ disclosure?: string | null;
44
47
  hashtags: string[];
45
48
  /** The configured platforms in `PLATFORMS` order, with this video's codes. */
46
49
  channels: PlatformChannel[];
@@ -94,7 +97,7 @@ export interface MarketingConfig {
94
97
  hideSelectors: string[];
95
98
  screenGuardSelector: string;
96
99
  };
97
- voice: { provider: "elevenlabs"; cacheDir: string };
100
+ voice: { provider: "elevenlabs"; cacheDir: string; minIntervalSeconds: number; placeholder: PlaceholderPace };
98
101
  videos: VideoConfig[];
99
102
  social: { linkTemplate: string } | null;
100
103
  screenshots: MarketingJson["screenshots"];
@@ -162,6 +165,8 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
162
165
  ? null
163
166
  : {
164
167
  caption: post.caption,
168
+ disclosure:
169
+ post.disclosure && data.social?.disclosure !== undefined ? data.social.disclosure.replaceAll("{persona}", video.persona.name).trim() : null,
165
170
  hashtags: post.hashtags,
166
171
  channels: PLATFORMS.flatMap((platform) => {
167
172
  const channel = platforms[platform];
@@ -218,7 +223,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
218
223
  hideSelectors: data.app.hideSelectors,
219
224
  screenGuardSelector: data.app.screenGuardSelector,
220
225
  },
221
- voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir) },
226
+ voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds, placeholder: data.voice.placeholder },
222
227
  videos: resolveVideos(data, at),
223
228
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
224
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
  /**
@@ -236,7 +237,20 @@ const voiceSchema = z.strictObject({
236
237
  .regex(LANGUAGE_PATTERN, "must be an ISO 639 language code such as en")
237
238
  .describe("ISO 639 code the voice speaks (en, pl); part of the voiceover cache key."),
238
239
  tempo: tempo.default(1).describe("Speed-up (0.8-1.3) applied at build time, not in the API, so the paid cache stays valid."),
240
+ minIntervalSeconds: z
241
+ .number()
242
+ .min(0)
243
+ .max(3600)
244
+ .default(60)
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."),
239
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."),
240
254
  });
241
255
 
242
256
  type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined };
@@ -425,6 +439,7 @@ const socialSchema = z.strictObject({
425
439
  video: id.describe("The id of the film in videos this post is for."),
426
440
  caption: z.string().describe("The post's text."),
427
441
  hashtags: z.array(z.string()).default([]).describe("Hashtags appended to the caption."),
442
+ disclosure: z.boolean().default(true).describe("Whether social.disclosure follows this post's caption (default true)."),
428
443
  codes: z
429
444
  .partialRecord(z.enum(PLATFORMS), channelCode.describe("The platform's channel code for this film."))
430
445
  .optional()
@@ -433,9 +448,12 @@ const socialSchema = z.strictObject({
433
448
  )
434
449
  .default([])
435
450
  .describe("Post copy per film; a film without a post gets no posts.md."),
451
+ disclosure: nonBlank
452
+ .optional()
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."),
436
454
  });
437
455
 
438
- const screenshotSchema = z.strictObject({
456
+ export const screenshotSchema = z.strictObject({
439
457
  id: id.describe("The screenshot's id: the file <output.dir>/screenshots/<id>.png."),
440
458
  path: pagePath.describe("The page of the app to capture, e.g. /pricing."),
441
459
  width: pixels(8000).describe("The browser viewport's width in CSS pixels."),
@@ -451,25 +469,70 @@ const screenshotSchema = z.strictObject({
451
469
  .refine((schemes) => new Set(schemes).size === schemes.length, "lists a scheme twice")
452
470
  .optional()
453
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
+ }
454
486
  });
455
487
 
456
- const ogImageBase = {
457
- id: id.describe("The image's id: the file <output.dir>/og/<id>.png."),
458
- size: z.tuple([pixels(4000), pixels(4000)]).default([1200, 630]).describe("The image size in pixels, [width, height]."),
459
- };
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).");
460
509
 
461
510
  /** One entry per template; `data` is the template's input, and values the app computes (charts) arrive precomputed. */
462
511
  const ogImageSchema = z.discriminatedUnion("template", [
463
512
  z.strictObject({
464
- ...ogImageBase,
513
+ id: ogImageId,
514
+ size: ogSize("landscape"),
465
515
  template: z.literal("headline-cta").describe("A headline with an optional eyebrow, call to action and tiles."),
466
516
  data: headlineCtaDataSchema.describe("The headline-cta template's input."),
467
517
  }),
468
518
  z.strictObject({
469
- ...ogImageBase,
519
+ id: ogImageId,
520
+ size: ogSize("landscape"),
470
521
  template: z.literal("headline-chart").describe("A headline over a chart the app computed, with optional tiles."),
471
522
  data: headlineChartDataSchema.describe("The headline-chart template's input."),
472
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
+ }),
473
536
  ]);
474
537
 
475
538
  /** When each sound effect plays; the descriptions of the `sfx` keys. */
@@ -601,6 +664,17 @@ export const marketingSchema = z
601
664
  });
602
665
  checkUnique("screenshots");
603
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
+ });
604
678
  const fileOwners = new Map<string, number>();
605
679
  config.screenshots.forEach((entry, index) => {
606
680
  for (const name of getScreenshotNames(entry.id)) {
package/src/index.ts CHANGED
@@ -84,7 +84,10 @@ export { ELEVENLABS_API_KEY_ENV, ELEVENLABS_PROVIDER_ID, createElevenLabsProvide
84
84
  export { createFakeTtsProvider, type FakeTtsOptions, type FakeTtsProvider } from "./voice/fake.js";
85
85
  export { createTtsProvider, type CreateTtsProviderOptions, type TtsProviderId } from "./voice/providers.js";
86
86
  export { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover, type VoiceoverPaths } from "./voice/cache.js";
87
- export { describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
87
+ export { describeCharge, describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
88
+ export { findLastRecordingTime, waitForPace, type PaceOptions } from "./voice/pace.js";
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";
88
91
  export {
89
92
  BROWSER_BAR_HEIGHT,
90
93
  DEVICE_KINDS,
@@ -137,6 +140,8 @@ export {
137
140
  } from "./compose/compose.js";
138
141
  export {
139
142
  DEFAULT_OG_SIZE,
143
+ countOgSlides,
144
+ getDefaultOgSize,
140
145
  OG_TEMPLATE_IDS,
141
146
  getOgPalette,
142
147
  loadOgFonts,
@@ -153,13 +158,16 @@ export { createActionScene, getLocator, runAction, type LocatorSource } from "./
153
158
  export { FPS, ScreenGuardError, type BrowserSettings, type CameraCue, type RecordingLog } from "./record/record.js";
154
159
  export {
155
160
  getScreenshotFile,
161
+ takePageScreenshot,
156
162
  takeScreenshots,
157
163
  type ScreenshotBrowser,
158
164
  type ScreenshotEntry,
159
165
  type ScreenshotResult,
166
+ type TakePageScreenshotOptions,
160
167
  type TakeScreenshotsOptions,
161
168
  } from "./screenshot/screenshot.js";
162
- 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";
163
171
  export { getScreenshotNames, getScreenshotShots, type ScreenshotNaming, type ScreenshotShot } from "./config/screenshot-names.js";
164
172
  export {
165
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";