@softure-ai/marketing-kit 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +111 -8
  3. package/dist/cli/main.js +42 -6
  4. package/dist/cli/main.js.map +1 -1
  5. package/dist/config/actions-schema.d.ts +7 -1
  6. package/dist/config/actions-schema.d.ts.map +1 -1
  7. package/dist/config/actions-schema.js +18 -3
  8. package/dist/config/actions-schema.js.map +1 -1
  9. package/dist/config/config.d.ts +2 -0
  10. package/dist/config/config.d.ts.map +1 -1
  11. package/dist/config/config.js +2 -1
  12. package/dist/config/config.js.map +1 -1
  13. package/dist/config/placeholders.d.ts +32 -0
  14. package/dist/config/placeholders.d.ts.map +1 -0
  15. package/dist/config/placeholders.js +41 -0
  16. package/dist/config/placeholders.js.map +1 -0
  17. package/dist/config/schema.d.ts +2214 -1
  18. package/dist/config/schema.d.ts.map +1 -1
  19. package/dist/config/schema.js +93 -4
  20. package/dist/config/schema.js.map +1 -1
  21. package/dist/config/shot-steps.d.ts +637 -0
  22. package/dist/config/shot-steps.d.ts.map +1 -0
  23. package/dist/config/shot-steps.js +44 -0
  24. package/dist/config/shot-steps.js.map +1 -0
  25. package/dist/film.d.ts +20 -5
  26. package/dist/film.d.ts.map +1 -1
  27. package/dist/film.js.map +1 -1
  28. package/dist/record/actions.d.ts +3 -10
  29. package/dist/record/actions.d.ts.map +1 -1
  30. package/dist/record/actions.js +13 -24
  31. package/dist/record/actions.js.map +1 -1
  32. package/dist/record/locator.d.ts +10 -0
  33. package/dist/record/locator.d.ts.map +1 -0
  34. package/dist/record/locator.js +24 -0
  35. package/dist/record/locator.js.map +1 -0
  36. package/dist/record/record.d.ts.map +1 -1
  37. package/dist/record/record.js +51 -17
  38. package/dist/record/record.js.map +1 -1
  39. package/dist/record/screen-guard.d.ts +13 -0
  40. package/dist/record/screen-guard.d.ts.map +1 -0
  41. package/dist/record/screen-guard.js +27 -0
  42. package/dist/record/screen-guard.js.map +1 -0
  43. package/dist/screenshot/gates.d.ts +46 -5
  44. package/dist/screenshot/gates.d.ts.map +1 -1
  45. package/dist/screenshot/gates.js +41 -5
  46. package/dist/screenshot/gates.js.map +1 -1
  47. package/dist/screenshot/prepare.d.ts +18 -0
  48. package/dist/screenshot/prepare.d.ts.map +1 -0
  49. package/dist/screenshot/prepare.js +60 -0
  50. package/dist/screenshot/prepare.js.map +1 -0
  51. package/dist/screenshot/screenshot.d.ts +9 -2
  52. package/dist/screenshot/screenshot.d.ts.map +1 -1
  53. package/dist/screenshot/screenshot.js +86 -7
  54. package/dist/screenshot/screenshot.js.map +1 -1
  55. package/dist/screenshot/shot-texts.d.ts +26 -0
  56. package/dist/screenshot/shot-texts.d.ts.map +1 -0
  57. package/dist/screenshot/shot-texts.js +55 -0
  58. package/dist/screenshot/shot-texts.js.map +1 -0
  59. package/dist/screenshot/sign-in.d.ts +34 -0
  60. package/dist/screenshot/sign-in.d.ts.map +1 -0
  61. package/dist/screenshot/sign-in.js +66 -0
  62. package/dist/screenshot/sign-in.js.map +1 -0
  63. package/dist/screenshot/steps.d.ts +12 -0
  64. package/dist/screenshot/steps.d.ts.map +1 -0
  65. package/dist/screenshot/steps.js +38 -0
  66. package/dist/screenshot/steps.js.map +1 -0
  67. package/package.json +3 -2
  68. package/schema/marketing.schema.json +1893 -18
  69. package/src/cli/main.ts +40 -6
  70. package/src/config/actions-schema.ts +18 -3
  71. package/src/config/config.ts +4 -1
  72. package/src/config/placeholders.ts +60 -0
  73. package/src/config/schema.ts +104 -5
  74. package/src/config/shot-steps.ts +58 -0
  75. package/src/film.ts +15 -5
  76. package/src/record/actions.ts +11 -32
  77. package/src/record/locator.ts +37 -0
  78. package/src/record/record.ts +53 -19
  79. package/src/record/screen-guard.ts +37 -0
  80. package/src/screenshot/gates.ts +60 -5
  81. package/src/screenshot/prepare.ts +64 -0
  82. package/src/screenshot/screenshot.ts +89 -8
  83. package/src/screenshot/shot-texts.ts +72 -0
  84. package/src/screenshot/sign-in.ts +91 -0
  85. package/src/screenshot/steps.ts +44 -0
package/src/cli/main.ts CHANGED
@@ -12,12 +12,14 @@ import { findMachineProblem } from "../render/preflight.js";
12
12
  import { runHyperframes } from "../render/hyperframes.js";
13
13
  import { renderFilm } from "../render/render.js";
14
14
  import { takePageScreenshot, takeScreenshots, type ScreenshotBrowser, type ScreenshotEntry, type ScreenshotResult } from "../screenshot/screenshot.js";
15
+ import { findPlaceholders } from "../config/placeholders.js";
16
+ import { runPrepare } from "../screenshot/prepare.js";
17
+ import { findUnsetVariable, resolveShotTexts, usesData, type ShotTexts } from "../screenshot/shot-texts.js";
15
18
  import { findStorageStateProblem } from "../screenshot/storage-state.js";
16
19
  import { isPlaceholderKey } from "../voice/placeholder.js";
17
20
  import { splitIntoBeats } from "../voice/voiceover.js";
18
21
  import { CliFailure, fail } from "./failure.js";
19
22
  import { loadFilm, type LoadedFilm } from "./films.js";
20
- import { writeOgImages } from "./og.js";
21
23
  import { getRecordingDay, readOptions, type EntryShotsOptions, type FilmOptions, type PageShotsOptions } from "./options.js";
22
24
  import { ensureServer } from "./server.js";
23
25
  import { getFilmVoiceover, produceVoiceover, produceVoiceovers, readJson } from "./voice.js";
@@ -206,21 +208,50 @@ async function pageShot(config: MarketingConfig, options: PageShotsOptions): Pro
206
208
  reportScreenshots([result]);
207
209
  }
208
210
 
211
+ /**
212
+ * The run's texts with `{env:…}` and `{data:…}` replaced. `signIn.prepare` runs only when an entry is signed in or
213
+ * reads its data, after the app answers; its output and the resolved values are never printed.
214
+ */
215
+ function prepareShotTexts(config: MarketingConfig, texts: ShotTexts, baseUrl: string): ShotTexts {
216
+ const needsPrepare = config.signIn?.prepare !== undefined && (texts.signIn !== null || usesData(texts));
217
+ let data: Record<string, string> | null = null;
218
+ if (needsPrepare && config.signIn?.prepare !== undefined) {
219
+ const [program, ...args] = config.signIn.prepare;
220
+ console.log(`prepare: ${config.signIn.prepare.join(" ")}.`);
221
+ // The schema requires at least one element.
222
+ const prepared = runPrepare([program as string, ...args], { cwd: config.root, baseUrl: new URL(baseUrl).origin });
223
+ if (!prepared.ok) fail(`${prepared.error}.`);
224
+ data = prepared.data;
225
+ }
226
+ const resolved = resolveShotTexts(texts, { env: process.env, data });
227
+ if (!resolved.ok) fail(`${resolved.error}.`);
228
+ return resolved.texts;
229
+ }
230
+
209
231
  async function shots(config: MarketingConfig, options: EntryShotsOptions): Promise<void> {
210
- const entries = resolveStorageStates(config, selectScreenshots(config, options.shotId));
211
- const [first] = entries;
212
- const target = { url: new URL(first.path, config.app.baseUrl).href, ownUrl: `http://localhost:${config.app.port}${first.path}` };
213
- const server = await ensureServer(config, target, options.url === undefined ? undefined : new URL(first.path, options.url).href);
232
+ const selected = resolveStorageStates(config, selectScreenshots(config, options.shotId));
233
+ const isSignedIn = selected.some((entry) => entry.signedIn);
234
+ const texts: ShotTexts = { entries: selected, signIn: isSignedIn ? config.signIn : null };
235
+ // Before the app starts or the account is seeded: a variable the shell lacks costs nothing to report.
236
+ const unset = findUnsetVariable(texts, process.env);
237
+ if (unset !== null) fail(`{env:${unset}} is not set in the environment; marketing.json reads it for the screenshots.`);
238
+ // The page that tells whether the app answers: the first path without a placeholder (a path such as
239
+ // /accounts/{data:id} would answer 404 before the preparation), else the root.
240
+ const probePath = selected.map((entry) => entry.path).find((path) => findPlaceholders(path).length === 0) ?? "/";
241
+ const target = { url: new URL(probePath, config.app.baseUrl).href, ownUrl: `http://localhost:${config.app.port}${probePath}` };
242
+ const server = await ensureServer(config, target, options.url === undefined ? undefined : new URL(probePath, options.url).href);
214
243
  const outDir = join(config.output.dir, "screenshots");
215
244
  let results;
216
245
  try {
217
- console.log(`screenshots: ${entries.length} from ${new URL(server.url).origin}.`);
246
+ const { entries, signIn } = prepareShotTexts(config, texts, server.url);
247
+ console.log(`screenshots: ${entries.length} from ${new URL(server.url).origin}${signIn === null ? "" : `, signed in at ${signIn.path}`}.`);
218
248
  results = await takeScreenshots({
219
249
  entries,
220
250
  baseUrl: server.url,
221
251
  outDir,
222
252
  executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH || undefined,
223
253
  browser: getScreenshotBrowser(config),
254
+ ...(signIn === null ? {} : { signIn }),
224
255
  });
225
256
  } finally {
226
257
  server.stop();
@@ -236,6 +267,9 @@ async function main(argv: string[]): Promise<void> {
236
267
  if (!loaded.ok) fail(loaded.error);
237
268
  const { config } = loaded;
238
269
  if (options.command === "og") {
270
+ // Loaded here, not at the top: satori is the only consumer, and a broken satori release must not take down the
271
+ // other commands (#254).
272
+ const { writeOgImages } = await import("./og.js");
239
273
  await writeOgImages(config, options.imageId);
240
274
  return;
241
275
  }
@@ -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>;
@@ -101,6 +101,8 @@ export interface MarketingConfig {
101
101
  videos: VideoConfig[];
102
102
  social: { linkTemplate: string } | null;
103
103
  screenshots: MarketingJson["screenshots"];
104
+ /** How `shots` signs in for `signedIn` entries; null without a `signIn` block. */
105
+ signIn: NonNullable<MarketingJson["signIn"]> | null;
104
106
  ogImages: MarketingJson["ogImages"];
105
107
  sfx: Partial<Record<SfxEvent, string>>;
106
108
  output: { dir: string; buildDir: string; quality: Quality };
@@ -145,7 +147,7 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
145
147
  language: data.voice.language,
146
148
  tempo: video.voice?.tempo ?? data.voice.tempo,
147
149
  },
148
- beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text })),
150
+ beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text, ...(beat.screenGuard === undefined ? {} : { screenGuard: beat.screenGuard }) })),
149
151
  hook: video.hook,
150
152
  screenGuard: video.screenGuard,
151
153
  today: video.today ?? null,
@@ -227,6 +229,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
227
229
  videos: resolveVideos(data, at),
228
230
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
229
231
  screenshots: data.screenshots,
232
+ signIn: data.signIn ?? null,
230
233
  ogImages: data.ogImages,
231
234
  sfx: Object.fromEntries(SFX_EVENTS.flatMap((event) => (data.sfx[event] === undefined ? [] : [[event, at(data.sfx[event])]]))),
232
235
  output: { dir: at(data.output.dir), buildDir: at(data.output.buildDir), quality: data.output.quality },
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Placeholders in the text of a screenshot or of the sign-in: `{env:NAME}` reads the environment (a password stays
3
+ * out of marketing.json), `{data:key}` reads what `signIn.prepare` printed (a value of the seeded account, so the
4
+ * phrase gate proves the frame shows that account). Pure: the CLI supplies both sources.
5
+ */
6
+
7
+ export const PLACEHOLDER_KINDS = ["env", "data"] as const;
8
+
9
+ export type PlaceholderKind = (typeof PLACEHOLDER_KINDS)[number];
10
+
11
+ export interface Placeholder {
12
+ kind: PlaceholderKind;
13
+ key: string;
14
+ }
15
+
16
+ /** `{env:NAME}` or `{data:key}`; the key is an identifier, so a brace in ordinary text never matches by accident. */
17
+ const PLACEHOLDER_PATTERN = /\{(env|data):([A-Za-z_][A-Za-z0-9_]*)\}/g;
18
+ /** Any `{word:…}` that looks like a placeholder, to refuse a misspelt kind instead of leaving it in the text. */
19
+ const PLACEHOLDER_LIKE_PATTERN = /\{[A-Za-z]+:[^{}\s]*\}/g;
20
+ const WHOLE_PLACEHOLDER_PATTERN = /^\{(?:env|data):[A-Za-z_][A-Za-z0-9_]*\}$/;
21
+
22
+ export function findPlaceholders(text: string): Placeholder[] {
23
+ return [...text.matchAll(PLACEHOLDER_PATTERN)].map((match) => ({ kind: match[1] as PlaceholderKind, key: match[2] ?? "" }));
24
+ }
25
+
26
+ /** The first `{kind:…}` whose kind or key is not a placeholder this kit knows, or null. */
27
+ export function findMalformedPlaceholder(text: string): string | null {
28
+ for (const match of text.matchAll(PLACEHOLDER_LIKE_PATTERN)) {
29
+ if (!WHOLE_PLACEHOLDER_PATTERN.test(match[0])) return match[0];
30
+ }
31
+ return null;
32
+ }
33
+
34
+ export interface PlaceholderSources {
35
+ env: Readonly<Record<string, string | undefined>>;
36
+ /** What `signIn.prepare` printed; null when it did not run. */
37
+ data: Readonly<Record<string, string>> | null;
38
+ }
39
+
40
+ export type ResolveResult = { ok: true; value: string } | { ok: false; error: string };
41
+
42
+ /**
43
+ * The text with every placeholder replaced; `encode` applies to the inserted values only (a page path). An unset
44
+ * variable or a key the preparation did not print is an error naming the placeholder, never its value.
45
+ */
46
+ export function resolvePlaceholders(text: string, sources: PlaceholderSources, encode: (value: string) => string = (value) => value): ResolveResult {
47
+ for (const { kind, key } of findPlaceholders(text)) {
48
+ if (kind === "env" && (sources.env[key] === undefined || sources.env[key] === "")) {
49
+ return { ok: false, error: `{env:${key}} is not set in the environment` };
50
+ }
51
+ if (kind === "data" && sources.data === null) return { ok: false, error: `{data:${key}} needs signIn.prepare, which did not run` };
52
+ if (kind === "data" && !Object.hasOwn(sources.data ?? {}, key)) {
53
+ return { ok: false, error: `{data:${key}} is not in what signIn.prepare printed (keys: ${Object.keys(sources.data ?? {}).join(", ") || "none"})` };
54
+ }
55
+ }
56
+ const value = text.replace(PLACEHOLDER_PATTERN, (_match, kind: PlaceholderKind, key: string) =>
57
+ encode(kind === "env" ? (sources.env[key] ?? "") : (sources.data?.[key] ?? "")),
58
+ );
59
+ return { ok: true, value };
60
+ }
@@ -20,7 +20,9 @@ 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
22
  import { getOgImageNames } from "./og-image-names.js";
23
+ import { findMalformedPlaceholder, findPlaceholders } from "./placeholders.js";
23
24
  import { getScreenshotNames } from "./screenshot-names.js";
25
+ import { cropSchema, shotStepSchema } from "./shot-steps.js";
24
26
 
25
27
  /**
26
28
  * `marketing.json`: everything product-specific about a project's marketing material. One zod schema
@@ -253,10 +255,11 @@ const voiceSchema = z.strictObject({
253
255
  .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."),
254
256
  });
255
257
 
256
- type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined };
258
+ type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?: SceneAction[] | undefined; screenGuard?: string[] | undefined };
257
259
 
258
260
  interface SceneShape {
259
261
  beats: VideoBeat[];
262
+ screenGuard: string[];
260
263
  hook: { still: string; shots: { mark: string }[]; transition: string };
261
264
  sceneModule?: string | undefined;
262
265
  }
@@ -268,7 +271,7 @@ interface SceneShape {
268
271
  */
269
272
  function checkScene(video: SceneShape, context: z.RefinementCtx): void {
270
273
  const [opening, ...sceneBeats] = video.beats;
271
- for (const key of ["actions", "pad"] as const) {
274
+ for (const key of ["actions", "pad", "screenGuard"] as const) {
272
275
  if (opening?.[key] !== undefined) {
273
276
  context.addIssue({ code: "custom", path: ["beats", 0, key], message: "the opening sentence plays over the still; the scene starts at the second sentence" });
274
277
  }
@@ -307,7 +310,8 @@ function checkScene(video: SceneShape, context: z.RefinementCtx): void {
307
310
  video.hook.shots.forEach((shot, index) => {
308
311
  if (!marks.has(shot.mark)) context.addIssue({ code: "custom", path: ["hook", "shots", index, "mark"], message: `no "mark" action saves "${shot.mark}"` });
309
312
  });
310
- if (!hasCheckScreen) context.addIssue({ code: "custom", path: ["beats"], message: 'needs a "checkScreen" action: the screen guard must run before the film can say what the screen shows' });
313
+ // Only the video's list waits for a checkScreen; a sentence's own phrases are checked when it ends.
314
+ if (!hasCheckScreen && video.screenGuard.length > 0) context.addIssue({ code: "custom", path: ["beats"], message: 'needs a "checkScreen" action: the screen guard must run before the film can say what the screen shows' });
311
315
  }
312
316
 
313
317
  const videoSchema = z
@@ -345,6 +349,13 @@ const videoSchema = z
345
349
  .array(actionSchema)
346
350
  .optional()
347
351
  .describe("What happens on screen during the sentence, in order; required on every sentence after the first when the film has no sceneModule."),
352
+ screenGuard: z
353
+ .array(nonBlank)
354
+ .min(1, "a sentence's screen guard needs at least one phrase; leave it out instead")
355
+ .optional()
356
+ .describe(
357
+ "Phrases this sentence says that the screen must show while it is spoken: checked at a checkScreen inside the sentence, or when the sentence ends. Not on the first sentence.",
358
+ ),
348
359
  }),
349
360
  )
350
361
  .min(3, "a film needs at least three sentences: opening, scene, end card")
@@ -378,8 +389,10 @@ const videoSchema = z
378
389
  ),
379
390
  screenGuard: z
380
391
  .array(nonBlank)
381
- .min(1, "the screen guard needs at least one phrase")
382
- .describe("Phrases the voiceover says that the screen must show; a missing one stops the recording."),
392
+ .default([])
393
+ .describe(
394
+ "Phrases the voiceover says that the screen must show at every checkScreen; a missing one stops the recording. May be left out when the sentences carry their own screenGuard.",
395
+ ),
383
396
  endCard: z
384
397
  .strictObject({
385
398
  headline: nonEmpty.describe("The end card's headline."),
@@ -392,6 +405,9 @@ const videoSchema = z
392
405
  .describe("A TS module exporting scene(director), relative to the folder of marketing.json: what happens on screen, instead of beat actions."),
393
406
  })
394
407
  .superRefine((video, context) => {
408
+ if (video.screenGuard.length === 0 && !video.beats.some((beat) => beat.screenGuard !== undefined)) {
409
+ context.addIssue({ code: "custom", path: ["screenGuard"], message: "the screen guard needs at least one phrase, here or in a sentence's screenGuard" });
410
+ }
395
411
  checkScene(video, context);
396
412
  const seen = new Set<string>();
397
413
  video.beats.forEach((beat, index) => {
@@ -479,12 +495,81 @@ export const screenshotSchema = z.strictObject({
479
495
  storageState: relativePath
480
496
  .optional()
481
497
  .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."),
498
+ signedIn: z.boolean().default(false).describe("Capture signed in through the signIn block: shots signs in once per run and keeps the session in memory. Not with storageState."),
499
+ steps: z
500
+ .array(shotStepSchema)
501
+ .default([])
502
+ .describe("Done in order after the page loaded, before any gate reads it, e.g. a click that opens a collapsed section; a failing step refuses the shot."),
503
+ crop: cropSchema
504
+ .optional()
505
+ .describe("Capture one element at a fixed aspect ratio (e.g. 4:3 around a chart) instead of the viewport: as wide as the element, from its top edge. Not with full or scrollTo."),
482
506
  }).superRefine((entry, context) => {
483
507
  if (entry.full && entry.scrollTo !== undefined) {
484
508
  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
509
  }
510
+ if (entry.crop !== undefined && entry.full) context.addIssue({ code: "custom", path: ["crop"], message: "frames one element; a full-page shot has no element to frame, so drop full or crop" });
511
+ if (entry.crop !== undefined && entry.scrollTo !== undefined) {
512
+ context.addIssue({ code: "custom", path: ["crop"], message: "places the frame on its element; scrollTo would place it too, so drop one of them" });
513
+ }
514
+ if (entry.signedIn && entry.storageState !== undefined) {
515
+ context.addIssue({ code: "custom", path: ["signedIn"], message: "signs in through signIn; storageState is another session, so drop one of them" });
516
+ }
517
+ checkPlaceholderText(entry.path, ["path"], context);
518
+ checkPlaceholderText(entry.expect, ["expect"], context);
519
+ entry.steps.forEach((step, index) => {
520
+ if (step.do === "fill") checkPlaceholderText(step.value, ["steps", index, "value"], context);
521
+ });
486
522
  });
487
523
 
524
+ /** Refuses `{kind:…}` text that is not `{env:NAME}` or `{data:key}`, so a misspelt placeholder never reaches the page. */
525
+ function checkPlaceholderText(text: string, path: (string | number)[], context: z.RefinementCtx): void {
526
+ const malformed = findMalformedPlaceholder(text);
527
+ if (malformed !== null) context.addIssue({ code: "custom", path, message: `${malformed} is not a placeholder: use {env:NAME} or {data:key}` });
528
+ }
529
+
530
+ /** Every text of the sign-in and the screenshots that may hold `{data:key}`, with its path in marketing.json. */
531
+ function listPlaceholderTexts(config: { signIn?: SignInConfig | undefined; screenshots: ScreenshotConfig[] }): { text: string; path: (string | number)[] }[] {
532
+ const texts: { text: string; path: (string | number)[] }[] = [];
533
+ const addSteps = (steps: readonly ShotStepConfig[], prefix: (string | number)[]) =>
534
+ steps.forEach((step, index) => {
535
+ if (step.do === "fill") texts.push({ text: step.value, path: [...prefix, "steps", index, "value"] });
536
+ });
537
+ if (config.signIn !== undefined) {
538
+ addSteps(config.signIn.steps, ["signIn"]);
539
+ texts.push({ text: config.signIn.expect, path: ["signIn", "expect"] });
540
+ }
541
+ config.screenshots.forEach((entry, index) => {
542
+ texts.push({ text: entry.path, path: ["screenshots", index, "path"] }, { text: entry.expect, path: ["screenshots", index, "expect"] });
543
+ addSteps(entry.steps, ["screenshots", index]);
544
+ });
545
+ return texts;
546
+ }
547
+
548
+ type ScreenshotConfig = z.output<typeof screenshotSchema>;
549
+ type ShotStepConfig = z.output<typeof shotStepSchema>;
550
+
551
+ export const signInSchema = z
552
+ .strictObject({
553
+ prepare: z
554
+ .array(nonEmpty)
555
+ .min(1)
556
+ .optional()
557
+ .describe(
558
+ "A command (arguments, no shell, run in the folder of marketing.json once the app answers, with MARKETING_BASE_URL set) that creates and seeds the account; its last line of output is a JSON object of strings or numbers, read as {data:key}. Its output is not printed.",
559
+ ),
560
+ path: pagePath.describe("The sign-in page, e.g. /login."),
561
+ steps: z.array(shotStepSchema).min(1, "needs at least one step").describe("What signs in on that page: fill the e-mail and password ({env:NAME} or {data:key}), click the button."),
562
+ expect: nonBlank.describe("A phrase only a signed-in page shows, within 15 s of the last step; without it the sign-in fails and so does every signedIn screenshot."),
563
+ })
564
+ .superRefine((signIn, context) => {
565
+ checkPlaceholderText(signIn.expect, ["expect"], context);
566
+ signIn.steps.forEach((step, index) => {
567
+ if (step.do === "fill") checkPlaceholderText(step.value, ["steps", index, "value"], context);
568
+ });
569
+ });
570
+
571
+ type SignInConfig = z.output<typeof signInSchema>;
572
+
488
573
  /** Named sizes of `ogImages[].size`: the share card and the three social formats. */
489
574
  export const OG_SIZE_PRESETS = {
490
575
  landscape: [1200, 630],
@@ -633,6 +718,9 @@ export const marketingSchema = z
633
718
  videos: z.array(videoSchema).min(1, "needs at least one video").describe("The films, at least one."),
634
719
  social: socialSchema.optional().describe("Post copy for the films: the link, the platforms and their channel codes."),
635
720
  screenshots: z.array(screenshotSchema).default([]).describe("Screenshots taken by softure-marketing shots."),
721
+ signIn: signInSchema
722
+ .optional()
723
+ .describe("How softure-marketing shots signs in for the screenshots with signedIn: true, and the optional command that prepares the account."),
636
724
  ogImages: z.array(ogImageSchema).default([]).describe("Open Graph images rendered by softure-marketing og."),
637
725
  layout: layoutSchema
638
726
  .optional()
@@ -685,6 +773,17 @@ export const marketingSchema = z
685
773
  fileOwners.set(name, owner ?? index);
686
774
  }
687
775
  });
776
+ config.screenshots.forEach((entry, index) => {
777
+ if (entry.signedIn && config.signIn === undefined) {
778
+ context.addIssue({ code: "custom", path: ["screenshots", index, "signedIn"], message: "needs a signIn block that says how to sign in" });
779
+ }
780
+ });
781
+ if (config.signIn?.prepare === undefined) {
782
+ for (const { text, path } of listPlaceholderTexts(config)) {
783
+ const data = findPlaceholders(text).find((placeholder) => placeholder.kind === "data");
784
+ if (data !== undefined) context.addIssue({ code: "custom", path, message: `{data:${data.key}} needs signIn.prepare, the command that prints the data` });
785
+ }
786
+ }
688
787
  const videoIds = new Set(config.videos.map((video) => video.id));
689
788
  const posted = new Set<string>();
690
789
  config.social?.posts.forEach((post, index) => {
@@ -0,0 +1,58 @@
1
+ import { z } from "zod";
2
+
3
+ import { locatorSchema } from "./actions-schema.js";
4
+
5
+ /**
6
+ * What a screenshot does on the page before it is judged: the sign-in form (`signIn.steps`) and an entry's own
7
+ * `steps` (open a collapsed section). Plain Playwright calls on a locator, with no camera and no timing: a screenshot
8
+ * records nothing in between. `crop` frames one element at a fixed aspect ratio instead of the viewport.
9
+ */
10
+
11
+ /** A Playwright key name, modifiers joined with `+`; Playwright itself refuses a name it does not know. */
12
+ const KEY_PATTERN = /^\S+$/;
13
+ /** `W:H` with whole numbers from 1 to 9999, e.g. `4:3`. */
14
+ export const ASPECT_PATTERN = /^[1-9]\d{0,3}:[1-9]\d{0,3}$/;
15
+
16
+ const target = locatorSchema.describe("The element, as a locator descriptor with exactly one of role, text, label, testId, css.");
17
+
18
+ export const shotStepSchema = z.discriminatedUnion("do", [
19
+ z.strictObject({
20
+ do: z.literal("fill").describe("Replaces the value of an input, e.g. the e-mail of the sign-in form."),
21
+ target,
22
+ value: z.string().describe("The value; {env:NAME} and {data:key} are replaced. Never printed, so a password may go here as {env:NAME}."),
23
+ }),
24
+ z.strictObject({
25
+ do: z.literal("click").describe("Clicks the element, e.g. the submit button or a collapsed section's summary."),
26
+ target,
27
+ }),
28
+ z.strictObject({
29
+ do: z.literal("check").describe("Ticks a checkbox or radio button, e.g. the terms of a sign-up form."),
30
+ target,
31
+ }),
32
+ z.strictObject({
33
+ do: z.literal("press").describe("Presses a key on the focused element, e.g. Enter."),
34
+ key: z.string().regex(KEY_PATTERN, "must be a key name such as Enter or Escape").describe("A Playwright key name; modifiers joined with +."),
35
+ }),
36
+ ]);
37
+
38
+ export type ShotStep = z.output<typeof shotStepSchema>;
39
+
40
+ export interface Aspect {
41
+ width: number;
42
+ height: number;
43
+ }
44
+
45
+ export const cropSchema = z.strictObject({
46
+ target: locatorSchema.describe("The element framed: exactly one match (nth picks one of several)."),
47
+ aspect: z
48
+ .string()
49
+ .regex(ASPECT_PATTERN, "must be W:H with whole numbers, e.g. 4:3")
50
+ .transform((value): Aspect => {
51
+ const [width, height] = value.split(":").map(Number);
52
+ return { width: width ?? 1, height: height ?? 1 };
53
+ })
54
+ .describe("The frame's width to height, e.g. 4:3: as wide as the element (plus padding), from its top edge down."),
55
+ padding: z.number().int().min(0).max(200).default(0).describe("CSS pixels of the page around the element on the left, right and top (0-200, default 0)."),
56
+ });
57
+
58
+ export type Crop = z.output<typeof cropSchema>;
package/src/film.ts CHANGED
@@ -12,6 +12,11 @@ import type { LayoutOverride, Transition, VideoFormat, Viewport } from "./compos
12
12
  export interface Beat {
13
13
  id: string;
14
14
  text: string;
15
+ /**
16
+ * Phrases this sentence says that the screen must show while it is spoken: checked at a `checkScreen` inside the
17
+ * sentence, or when it ends. Never on the opening sentence.
18
+ */
19
+ screenGuard?: string[];
15
20
  }
16
21
 
17
22
  export interface Persona {
@@ -89,8 +94,8 @@ export interface FilmScript {
89
94
  /** The opening: its still, the camera shots over it, and how it hands over to the scene. */
90
95
  hook: { still: string; shots: HookShot[]; transition: Transition };
91
96
  /**
92
- * Phrases the voiceover says that the app's screen must show. If any is missing the recording
93
- * stops and the render never starts.
97
+ * Phrases the voiceover says that the app's screen must show at every `checkScreen`. If any is missing the
98
+ * recording stops and the render never starts. Empty when every phrase lives on its sentence (`Beat.screenGuard`).
94
99
  */
95
100
  screenGuard: string[];
96
101
  endCard: EndCard;
@@ -116,8 +121,13 @@ export interface Director {
116
121
  /** Touch the element on a phone, click it on a desktop. */
117
122
  tap(target: Locator, options?: { after?: number }): Promise<void>;
118
123
  type(text: string, options?: { perChar?: number }): Promise<void>;
119
- /** Tap the `input[name=…]` field, move the camera onto it and type the value. */
120
- fill(name: string, value: string): Promise<void>;
124
+ /** Press a key (a Playwright key name such as `Backspace` or `ControlOrMeta+A`) `times` times, holding `perKey` after each. */
125
+ press(key: string, options?: { times?: number; perKey?: number }): Promise<void>;
126
+ /**
127
+ * Tap the `input[name=…]` field, move the camera onto it and type the value. A value already in the field is
128
+ * selected and deleted first, on screen; `clear: false` types after it instead.
129
+ */
130
+ fill(name: string, value: string, options?: { clear?: boolean }): Promise<void>;
121
131
  blur(): Promise<void>;
122
132
  /** Camera on an element (or on the rectangle that encloses several). */
123
133
  focus(target: Locator | Locator[], options?: { scale?: number; height?: number }): Promise<void>;
@@ -129,7 +139,7 @@ export interface Director {
129
139
  still(name: string): Promise<void>;
130
140
  /** An event on the film's timeline: a sound effect or the persona card leaving. */
131
141
  cue(name: CueName): Promise<void>;
132
- /** The screen guard: check now, before the recording goes on. */
142
+ /** The screen guard: the video's phrases and the current sentence's, checked now, before the recording goes on. */
133
143
  checkScreen(): Promise<void>;
134
144
  }
135
145
 
@@ -1,46 +1,20 @@
1
- import type { Locator, Page } from "playwright";
1
+ import type { Locator } from "playwright";
2
2
 
3
- import type { LocatorDescriptor, SceneAction, TextMatch } from "../config/actions-schema.js";
3
+ import type { LocatorDescriptor, SceneAction } from "../config/actions-schema.js";
4
4
  import type { ActionBeat } from "../config/config.js";
5
5
  import { formatIssuePath } from "../config/issues.js";
6
6
  import type { Director, Scene } from "../film.js";
7
+ import { getLocator, type LocatorSource } from "./locator.js";
7
8
  import { ScreenGuardError } from "./record.js";
8
9
 
10
+ export { getLocator, type LocatorSource };
11
+
9
12
  /**
10
13
  * Beat `actions` from `marketing.json`, played on the Director: each descriptor becomes a Playwright
11
14
  * locator and each action the Director call of the same name. An action that fails names its JSON
12
15
  * path, so the author knows which entry of the config to fix.
13
16
  */
14
17
 
15
- /** The part of a page that builds locators. */
16
- export type LocatorSource = Pick<Page, "getByRole" | "getByText" | "getByLabel" | "getByTestId" | "locator">;
17
-
18
- function toMatcher(match: TextMatch): string | RegExp {
19
- return typeof match === "string" ? match : new RegExp(match.regex, match.flags);
20
- }
21
-
22
- export function getLocator(page: LocatorSource, descriptor: LocatorDescriptor): Locator {
23
- const locator = buildLocator(page, descriptor);
24
- return descriptor.nth === null ? locator : locator.nth(descriptor.nth);
25
- }
26
-
27
- function buildLocator(page: LocatorSource, descriptor: LocatorDescriptor): Locator {
28
- switch (descriptor.kind) {
29
- case "role":
30
- return descriptor.name === null
31
- ? page.getByRole(descriptor.role)
32
- : page.getByRole(descriptor.role, { name: toMatcher(descriptor.name), ...(descriptor.exact ? { exact: true } : {}) });
33
- case "text":
34
- return page.getByText(toMatcher(descriptor.text), descriptor.exact ? { exact: true } : undefined);
35
- case "label":
36
- return page.getByLabel(toMatcher(descriptor.label), descriptor.exact ? { exact: true } : undefined);
37
- case "testId":
38
- return page.getByTestId(descriptor.testId);
39
- case "css":
40
- return descriptor.hasText === null ? page.locator(descriptor.css) : page.locator(descriptor.css, { hasText: toMatcher(descriptor.hasText) });
41
- }
42
- }
43
-
44
18
  function getLocators(page: LocatorSource, target: LocatorDescriptor | LocatorDescriptor[]): Locator | Locator[] {
45
19
  return Array.isArray(target) ? target.map((descriptor) => getLocator(page, descriptor)) : getLocator(page, target);
46
20
  }
@@ -55,8 +29,13 @@ export async function runAction(director: Director, action: SceneAction): Promis
55
29
  return director.tap(getLocator(page, action.target), action.after === undefined ? undefined : { after: action.after });
56
30
  case "type":
57
31
  return director.type(action.text, action.perChar === undefined ? undefined : { perChar: action.perChar });
32
+ case "press":
33
+ return director.press(action.key, {
34
+ ...(action.times === undefined ? {} : { times: action.times }),
35
+ ...(action.perKey === undefined ? {} : { perKey: action.perKey }),
36
+ });
58
37
  case "fill":
59
- return director.fill(action.input, action.value);
38
+ return director.fill(action.input, action.value, action.clear === undefined ? undefined : { clear: action.clear });
60
39
  case "blur":
61
40
  return director.blur();
62
41
  case "focus":
@@ -0,0 +1,37 @@
1
+ import type { Locator, Page } from "playwright";
2
+
3
+ import type { LocatorDescriptor, TextMatch } from "../config/actions-schema.js";
4
+
5
+ /**
6
+ * A locator descriptor from `marketing.json` as a Playwright locator: the beats' actions and the screenshots'
7
+ * steps and crops find elements the same way.
8
+ */
9
+
10
+ /** The part of a page that builds locators. */
11
+ export type LocatorSource = Pick<Page, "getByRole" | "getByText" | "getByLabel" | "getByTestId" | "locator">;
12
+
13
+ function toMatcher(match: TextMatch): string | RegExp {
14
+ return typeof match === "string" ? match : new RegExp(match.regex, match.flags);
15
+ }
16
+
17
+ export function getLocator(page: LocatorSource, descriptor: LocatorDescriptor): Locator {
18
+ const locator = buildLocator(page, descriptor);
19
+ return descriptor.nth === null ? locator : locator.nth(descriptor.nth);
20
+ }
21
+
22
+ function buildLocator(page: LocatorSource, descriptor: LocatorDescriptor): Locator {
23
+ switch (descriptor.kind) {
24
+ case "role":
25
+ return descriptor.name === null
26
+ ? page.getByRole(descriptor.role)
27
+ : page.getByRole(descriptor.role, { name: toMatcher(descriptor.name), ...(descriptor.exact ? { exact: true } : {}) });
28
+ case "text":
29
+ return page.getByText(toMatcher(descriptor.text), descriptor.exact ? { exact: true } : undefined);
30
+ case "label":
31
+ return page.getByLabel(toMatcher(descriptor.label), descriptor.exact ? { exact: true } : undefined);
32
+ case "testId":
33
+ return page.getByTestId(descriptor.testId);
34
+ case "css":
35
+ return descriptor.hasText === null ? page.locator(descriptor.css) : page.locator(descriptor.css, { hasText: toMatcher(descriptor.hasText) });
36
+ }
37
+ }