@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
package/src/cli/main.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import { existsSync, mkdirSync, writeFileSync } from "node:fs";
3
- import { join } from "node:path";
3
+ import { join, resolve } from "node:path";
4
4
 
5
5
  import { findMissingFiles, formatConfigIssues, loadMarketingConfig, type MarketingConfig } from "../config/config.js";
6
6
  import { getGeometry, getLayoutName } from "../compose/timeline.js";
@@ -11,19 +11,21 @@ import { recordFilm, ScreenGuardError, type RecordingLog } from "../record/recor
11
11
  import { findMachineProblem } from "../render/preflight.js";
12
12
  import { runHyperframes } from "../render/hyperframes.js";
13
13
  import { renderFilm } from "../render/render.js";
14
- import { takeScreenshots, type ScreenshotEntry } from "../screenshot/screenshot.js";
14
+ import { takePageScreenshot, takeScreenshots, type ScreenshotBrowser, type ScreenshotEntry, type ScreenshotResult } from "../screenshot/screenshot.js";
15
+ import { findStorageStateProblem } from "../screenshot/storage-state.js";
16
+ import { isPlaceholderKey } from "../voice/placeholder.js";
15
17
  import { splitIntoBeats } from "../voice/voiceover.js";
16
18
  import { CliFailure, fail } from "./failure.js";
17
19
  import { loadFilm, type LoadedFilm } from "./films.js";
18
20
  import { writeOgImages } from "./og.js";
19
- import { getRecordingDay, readOptions, type FilmOptions, type ShotsOptions } from "./options.js";
21
+ import { getRecordingDay, readOptions, type EntryShotsOptions, type FilmOptions, type PageShotsOptions } from "./options.js";
20
22
  import { ensureServer } from "./server.js";
21
- import { getVoiceoverPaths, produceVoiceover, produceVoiceovers, readJson, requireVoiceover } from "./voice.js";
23
+ import { getFilmVoiceover, produceVoiceover, produceVoiceovers, readJson } from "./voice.js";
22
24
 
23
25
  /**
24
26
  * `softure-marketing`: the only way into the films.
25
27
  *
26
- * all <film> voiceover from the cache -> recording -> render -> post copy
28
+ * all <film> [--placeholder] voiceover from the cache (or the free placeholder) -> recording -> render -> post copy
27
29
  * voice <film>... [--commit] voiceovers in order (paid only with --commit), spaced and stopped at the first error
28
30
  * record <film> [--today=YYYY-MM-DD] [--url=...] (--today overrides the video's today)
29
31
  * render <film> [--quality=draft|standard|high]
@@ -31,6 +33,7 @@ import { getVoiceoverPaths, produceVoiceover, produceVoiceovers, readJson, requi
31
33
  * posts <film>
32
34
  * og [image]
33
35
  * shots [<id>] [--url=...]
36
+ * shots --page=<url> --out=<file.png> --expect=<phrase> [...]
34
37
  */
35
38
 
36
39
  const getBuildDir = (config: MarketingConfig, film: LoadedFilm) => join(config.output.buildDir, film.id);
@@ -44,7 +47,8 @@ function preflight(config: MarketingConfig, film: LoadedFilm, needsRender: boole
44
47
  }
45
48
 
46
49
  async function record(config: MarketingConfig, film: LoadedFilm, options: FilmOptions): Promise<RecordingLog> {
47
- const voiceover = requireVoiceover(config, film);
50
+ const { voiceover, key, isPlaceholder } = getFilmVoiceover(config, film, { isPlaceholder: options.isPlaceholder, buildDir: getBuildDir(config, film) });
51
+ if (isPlaceholder) console.log(`voiceover: the placeholder (a tone, ${config.voice.placeholder.wordsPerSecond} words a second); nothing paid, render it with --placeholder.`);
48
52
  const voices = splitIntoBeats(voiceover.words, film.beats, film.voice.tempo);
49
53
  const server = await ensureServer(config, film, options.url);
50
54
  mkdirSync(getBuildDir(config, film), { recursive: true });
@@ -57,7 +61,7 @@ async function record(config: MarketingConfig, film: LoadedFilm, options: FilmOp
57
61
  url: server.url,
58
62
  outDir: getBuildDir(config, film),
59
63
  voices,
60
- voiceoverKey: getVoiceoverPaths(config, film).key,
64
+ voiceoverKey: key,
61
65
  today: recordingDay.day ?? undefined,
62
66
  filmPath: film.scenePath,
63
67
  executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH || undefined,
@@ -103,14 +107,21 @@ function render(config: MarketingConfig, film: LoadedFilm, options: FilmOptions)
103
107
  if (!existsSync(logPath)) fail(`no recording: run softure-marketing record ${film.id} first.`);
104
108
  // Our own file, written by `recordFilm`; the two fields that tie it to the script are checked below.
105
109
  const log = readJson(logPath) as RecordingLog;
106
- const voiceover = requireVoiceover(config, film);
110
+ // A recording follows the timings of the voiceover it was made on, so a placeholder recording never renders
111
+ // with the paid voiceover, nor the reverse.
112
+ if (isPlaceholderKey(log.voiceoverKey) !== options.isPlaceholder) {
113
+ if (options.isPlaceholder) fail(`the recording was made on the paid voiceover: run softure-marketing record ${film.id} --placeholder, or render without --placeholder.`);
114
+ fail(`the recording was made on the placeholder voiceover: run softure-marketing record ${film.id} for the paid one, or render with --placeholder.`);
115
+ }
116
+ const { voiceover, key } = getFilmVoiceover(config, film, { isPlaceholder: options.isPlaceholder, buildDir: dir });
107
117
  // The recording must match the script; otherwise the action times belong to another voiceover or
108
118
  // other sentences, and the film would come out silently out of sync.
109
119
  const beatIds = sceneBeats(film).map((beat) => beat.id);
110
- if (log.voiceoverKey !== getVoiceoverPaths(config, film).key || log.beatIds?.join(",") !== beatIds.join(",")) {
111
- fail(`the recording does not match the current script (the sentences or the voiceover changed): run softure-marketing record ${film.id}.`);
120
+ if (log.voiceoverKey !== key || log.beatIds?.join(",") !== beatIds.join(",")) {
121
+ fail(`the recording does not match the current script (the sentences or the voiceover changed): run softure-marketing record ${film.id}${options.isPlaceholder ? " --placeholder" : ""}.`);
112
122
  }
113
- const output = join(getOutDir(config, film), `${film.id}.mp4`);
123
+ // A rehearsal never takes the place of the real film.
124
+ const output = join(getOutDir(config, film), options.isPlaceholder ? `${film.id}.placeholder.mp4` : `${film.id}.mp4`);
114
125
  const seconds = renderFilm({
115
126
  film,
116
127
  log,
@@ -146,8 +157,57 @@ function selectScreenshots(config: MarketingConfig, shotId: string | undefined):
146
157
  fail(`no screenshot "${shotId}" in ${config.file}; known: ${config.screenshots.map((entry) => entry.id).join(", ") || "none"}.`);
147
158
  }
148
159
 
149
- async function shots(config: MarketingConfig, options: ShotsOptions): Promise<void> {
150
- const entries = selectScreenshots(config, options.shotId);
160
+ /** The entries with their storage state as an absolute path, each checked before the browser starts. */
161
+ function resolveStorageStates(config: MarketingConfig, entries: [ScreenshotEntry, ...ScreenshotEntry[]]): [ScreenshotEntry, ...ScreenshotEntry[]] {
162
+ const [first, ...rest] = entries.map((entry) => {
163
+ if (entry.storageState === undefined) return entry;
164
+ const path = resolve(config.root, entry.storageState);
165
+ const problem = findStorageStateProblem(path);
166
+ if (problem !== null) fail(`screenshot "${entry.id}": ${problem}.`);
167
+ return { ...entry, storageState: path };
168
+ });
169
+ // The map keeps the length of a non-empty tuple.
170
+ return [first as ScreenshotEntry, ...rest];
171
+ }
172
+
173
+ function getScreenshotBrowser(config: MarketingConfig): ScreenshotBrowser {
174
+ return { colorScheme: config.app.colorScheme, locale: config.brand.locale, timezone: config.brand.timezone, hideSelectors: config.app.hideSelectors };
175
+ }
176
+
177
+ /** Prints each result and fails when any shot was refused. */
178
+ function reportScreenshots(results: ScreenshotResult[]): void {
179
+ for (const result of results) {
180
+ if (result.ok) console.log(`✓ ${result.file} (${(result.bytes / 1000).toFixed(0)} kB)`);
181
+ else console.error(`✗ ${result.name}: ${result.message}`);
182
+ }
183
+ const failed = results.filter((result) => !result.ok).length;
184
+ if (failed > 0) fail(`${failed} of ${results.length} screenshots failed their gates; see above.`);
185
+ }
186
+
187
+ /** `shots --page`: one page anywhere; the app is not started, and the storage state resolves from the current directory. */
188
+ async function pageShot(config: MarketingConfig, options: PageShotsOptions): Promise<void> {
189
+ let { entry } = options;
190
+ if (entry.storageState !== undefined) {
191
+ const path = resolve(entry.storageState);
192
+ const problem = findStorageStateProblem(path);
193
+ if (problem !== null) fail(`--auth: ${problem}.`);
194
+ entry = { ...entry, storageState: path };
195
+ }
196
+ const file = resolve(options.out);
197
+ console.log(`screenshot: ${options.page}.`);
198
+ const result = await takePageScreenshot({
199
+ entry,
200
+ url: options.page,
201
+ file,
202
+ scheme: options.scheme,
203
+ browser: getScreenshotBrowser(config),
204
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH || undefined,
205
+ });
206
+ reportScreenshots([result]);
207
+ }
208
+
209
+ async function shots(config: MarketingConfig, options: EntryShotsOptions): Promise<void> {
210
+ const entries = resolveStorageStates(config, selectScreenshots(config, options.shotId));
151
211
  const [first] = entries;
152
212
  const target = { url: new URL(first.path, config.app.baseUrl).href, ownUrl: `http://localhost:${config.app.port}${first.path}` };
153
213
  const server = await ensureServer(config, target, options.url === undefined ? undefined : new URL(first.path, options.url).href);
@@ -160,22 +220,12 @@ async function shots(config: MarketingConfig, options: ShotsOptions): Promise<vo
160
220
  baseUrl: server.url,
161
221
  outDir,
162
222
  executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH || undefined,
163
- browser: {
164
- colorScheme: config.app.colorScheme,
165
- locale: config.brand.locale,
166
- timezone: config.brand.timezone,
167
- hideSelectors: config.app.hideSelectors,
168
- },
223
+ browser: getScreenshotBrowser(config),
169
224
  });
170
225
  } finally {
171
226
  server.stop();
172
227
  }
173
- for (const result of results) {
174
- if (result.ok) console.log(`✓ ${result.file} (${(result.bytes / 1000).toFixed(0)} kB)`);
175
- else console.error(`✗ ${result.name}: ${result.message}`);
176
- }
177
- const failed = results.filter((result) => !result.ok).length;
178
- if (failed > 0) fail(`${failed} of ${results.length} screenshots failed their gates; see above.`);
228
+ reportScreenshots(results);
179
229
  }
180
230
 
181
231
  async function main(argv: string[]): Promise<void> {
@@ -190,7 +240,8 @@ async function main(argv: string[]): Promise<void> {
190
240
  return;
191
241
  }
192
242
  if (options.command === "shots") {
193
- await shots(config, options);
243
+ if (options.mode === "page") await pageShot(config, options);
244
+ else await shots(config, options);
194
245
  return;
195
246
  }
196
247
  if (options.command === "voice") {
@@ -223,7 +274,9 @@ async function main(argv: string[]): Promise<void> {
223
274
  }
224
275
  case "all": {
225
276
  preflight(config, film, true);
226
- if ((await produceVoiceover(config, film, false)) === null) fail("no voiceover; see the message above.");
277
+ if (!options.isPlaceholder && (await produceVoiceover(config, film, false)) === null) {
278
+ fail(`no voiceover; see the message above. To rehearse the film for free: softure-marketing all ${film.id} --placeholder.`);
279
+ }
227
280
  await record(config, film, options);
228
281
  render(config, film, options);
229
282
  return;
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,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,
@@ -96,7 +96,7 @@ export const ARIA_ROLES = [
96
96
 
97
97
  export type AriaRole = (typeof ARIA_ROLES)[number];
98
98
 
99
- export const ACTION_NAMES = ["wide", "tap", "type", "fill", "blur", "focus", "bring", "mark", "still", "cue", "hold", "until", "checkScreen"] as const;
99
+ export const ACTION_NAMES = ["wide", "tap", "type", "press", "fill", "blur", "focus", "bring", "mark", "still", "cue", "hold", "until", "checkScreen"] as const;
100
100
 
101
101
  export type ActionName = (typeof ACTION_NAMES)[number];
102
102
 
@@ -104,6 +104,8 @@ const LOCATOR_KINDS = ["role", "text", "label", "testId", "css"] as const;
104
104
  const REGEX_FLAGS_PATTERN = /^(?!.*(.).*\1)[imsu]*$/;
105
105
  /** The Director types into `input[name=…]` unquoted, so the name must be a CSS identifier. */
106
106
  const INPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
107
+ /** A Playwright key name, modifiers joined with `+`; Playwright itself refuses a name it does not know. */
108
+ const KEY_PATTERN = /^\S+$/;
107
109
 
108
110
  function compiles(source: string, flags: string): boolean {
109
111
  try {
@@ -205,9 +207,22 @@ export const actionSchema = z.discriminatedUnion("do", [
205
207
  perChar: seconds.optional().describe("Seconds per key (0-10, default 0.13)."),
206
208
  }),
207
209
  z.strictObject({
208
- do: z.literal("fill").describe("Taps input[name=<input>], moves the camera onto it and types the value."),
210
+ do: z.literal("press").describe("Presses a key on the focused element, e.g. Backspace, Enter or ControlOrMeta+A."),
211
+ key: z
212
+ .string()
213
+ .regex(KEY_PATTERN, "must be a key name such as Backspace, Enter or ControlOrMeta+A")
214
+ .describe("A Playwright key name; modifiers joined with +, ControlOrMeta for the platform's shortcut key."),
215
+ times: z.number().int().min(1).max(50).optional().describe("How many times the key is pressed (1-50, default 1)."),
216
+ perKey: seconds.optional().describe("Seconds held after each press (0-10, default 0.13)."),
217
+ }),
218
+ z.strictObject({
219
+ do: z.literal("fill").describe("Taps input[name=<input>], moves the camera onto it, deletes a value already there and types the value."),
209
220
  input: z.string().regex(INPUT_NAME_PATTERN, "must be an input name such as age or returnRate").describe("The name attribute of the input, e.g. age."),
210
221
  value: z.string().describe("The text typed into the input."),
222
+ clear: z
223
+ .boolean()
224
+ .optional()
225
+ .describe("Select and delete a value already in the input before typing, on screen (default true); false types after it."),
211
226
  }),
212
227
  z.strictObject({ do: z.literal("blur").describe("Takes the focus off the active element.") }),
213
228
  z.strictObject({
@@ -243,7 +258,7 @@ export const actionSchema = z.discriminatedUnion("do", [
243
258
  do: z.literal("until").describe("Waits until the voiceover says a word of the current sentence."),
244
259
  word: nonEmpty.describe("A word of this sentence, punctuation ignored."),
245
260
  }),
246
- z.strictObject({ do: z.literal("checkScreen").describe("Runs the screen guard now: every screenGuard phrase must be on screen.") }),
261
+ z.strictObject({ do: z.literal("checkScreen").describe("Runs the screen guard now: the video's screenGuard phrases and the current sentence's must be on screen.") }),
247
262
  ]);
248
263
 
249
264
  export type SceneAction = z.output<typeof actionSchema>;
@@ -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"];
@@ -144,7 +145,7 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
144
145
  language: data.voice.language,
145
146
  tempo: video.voice?.tempo ?? data.voice.tempo,
146
147
  },
147
- beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text })),
148
+ beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text, ...(beat.screenGuard === undefined ? {} : { screenGuard: beat.screenGuard }) })),
148
149
  hook: video.hook,
149
150
  screenGuard: video.screenGuard,
150
151
  today: video.today ?? null,
@@ -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
+ }