@softure-ai/marketing-kit 0.1.8 → 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.
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
 
@@ -55,8 +55,13 @@ export async function runAction(director: Director, action: SceneAction): Promis
55
55
  return director.tap(getLocator(page, action.target), action.after === undefined ? undefined : { after: action.after });
56
56
  case "type":
57
57
  return director.type(action.text, action.perChar === undefined ? undefined : { perChar: action.perChar });
58
+ case "press":
59
+ return director.press(action.key, {
60
+ ...(action.times === undefined ? {} : { times: action.times }),
61
+ ...(action.perKey === undefined ? {} : { perKey: action.perKey }),
62
+ });
58
63
  case "fill":
59
- return director.fill(action.input, action.value);
64
+ return director.fill(action.input, action.value, action.clear === undefined ? undefined : { clear: action.clear });
60
65
  case "blur":
61
66
  return director.blur();
62
67
  case "focus":
@@ -5,8 +5,9 @@ import { chromium, type Locator } from "playwright";
5
5
 
6
6
  import { fitScale, getGeometry, unionRect, type Rect } from "../compose/timeline.js";
7
7
  import type { ColorTheme } from "../config/colors.js";
8
- import { containsPhrase, sceneBeats, type CueName, type Director, type Film } from "../film.js";
8
+ import { sceneBeats, type Beat, type CueName, type Director, type Film } from "../film.js";
9
9
  import type { BeatVoice } from "../voice/voiceover.js";
10
+ import { describeCheckScreenFailure, describeSentenceFailure, findMissingPhrases, getCheckScreenPhrases } from "./screen-guard.js";
10
11
 
11
12
  /**
12
13
  * Recording of the real app **frame by frame**, with the page clock frozen.
@@ -26,6 +27,8 @@ export const FPS = 30;
26
27
  const DT = 1000 / FPS;
27
28
  /** Limit of one scene action: longer means the app looks different from what the scene expects. */
28
29
  const ACTION_TIMEOUT_MS = 5000;
30
+ /** How long one typed character or pressed key stays on screen before the next. */
31
+ const KEY_SECONDS = 0.13;
29
32
 
30
33
  export interface CameraCue {
31
34
  f: number;
@@ -96,7 +99,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
96
99
  mkdirSync(framesDir, { recursive: true });
97
100
 
98
101
  const voiceById = new Map(voices.map((voice) => [voice.id, voice]));
99
- const expectedBeats = sceneBeats(film).map((beat) => beat.id);
102
+ const sentenceById = new Map(sceneBeats(film).map((beat) => [beat.id, beat]));
103
+ const expectedBeats = [...sentenceById.keys()];
100
104
  const log: RecordingLog = {
101
105
  voiceoverKey: options.voiceoverKey,
102
106
  beatIds: expectedBeats,
@@ -157,7 +161,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
157
161
 
158
162
  let virtualMs = 0;
159
163
  let frame = 0;
160
- let current: { id: string; f0: number } | null = null;
164
+ /** The sentence being recorded; `isGuardChecked` once a checkScreen inside it checked its own phrases. */
165
+ let current: { id: string; f0: number; sentence: Beat; isGuardChecked: boolean } | null = null;
161
166
  let guardChecked = false;
162
167
 
163
168
  const where = (): string => (current === null ? "before the first sentence" : `sentence "${current.id}"`);
@@ -196,6 +201,10 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
196
201
  for (let i = 0, count = Math.round(seconds * FPS); i < count; i += 1) await shoot();
197
202
  }
198
203
 
204
+ async function readScreenText(): Promise<string> {
205
+ return (await page.locator(settings.screenGuardSelector).first().innerText()).replace(/\s+/g, " ");
206
+ }
207
+
199
208
  async function rectOf(target: Locator): Promise<Rect> {
200
209
  try {
201
210
  // "visible", not "attached": a hidden element has a 0×0 rectangle and a tap would miss.
@@ -249,13 +258,21 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
249
258
  );
250
259
  }
251
260
  const voice = voiceById.get(id);
252
- if (voice === undefined) throw new Error(`No voiceover for sentence "${id}".`);
253
- current = { id, f0: frame };
261
+ const sentence = sentenceById.get(id);
262
+ if (voice === undefined || sentence === undefined) throw new Error(`No voiceover for sentence "${id}".`);
263
+ const state = { id, f0: frame, sentence, isGuardChecked: false };
264
+ current = state;
254
265
  await actions();
255
266
  const minFrames = Math.round((voice.end - voice.start + (beatOptions?.pad ?? 0.35)) * FPS);
256
- const missing = minFrames - (frame - current.f0);
267
+ const missing = minFrames - (frame - state.f0);
257
268
  if (missing > 0) await hold(missing / FPS);
258
- log.beats.push({ id, f0: current.f0, f1: frame });
269
+ // The sentence's own phrases, on its last frame, unless a checkScreen inside it already checked them.
270
+ const phrases = sentence.screenGuard ?? [];
271
+ if (!state.isGuardChecked && phrases.length > 0) {
272
+ const absent = findMissingPhrases(await readScreenText(), phrases);
273
+ if (absent.length > 0) throw new ScreenGuardError(describeSentenceFailure(id, absent, filmPath));
274
+ }
275
+ log.beats.push({ id, f0: state.f0, f1: frame });
259
276
  },
260
277
 
261
278
  async until(word) {
@@ -290,11 +307,19 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
290
307
  for (const character of text) {
291
308
  log.keys.push(frame);
292
309
  await page.keyboard.type(character);
293
- await hold(typeOptions?.perChar ?? 0.13);
310
+ await hold(typeOptions?.perChar ?? KEY_SECONDS);
294
311
  }
295
312
  },
296
313
 
297
- async fill(name, value) {
314
+ async press(key, pressOptions) {
315
+ for (let i = 0, times = pressOptions?.times ?? 1; i < times; i += 1) {
316
+ log.keys.push(frame);
317
+ await page.keyboard.press(key);
318
+ await hold(pressOptions?.perKey ?? KEY_SECONDS);
319
+ }
320
+ },
321
+
322
+ async fill(name, value, fillOptions) {
298
323
  const input = page.locator(`input[name=${name}]`);
299
324
  await ensureVisible(input);
300
325
  const rect = await rectOf(input);
@@ -302,6 +327,19 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
302
327
  const scale = isDesktop ? Math.min(1.55, fitScale(geometry, rect)) : 1.55;
303
328
  log.camera.push({ f: frame, kind: "focus", rect, scale, whoosh: false });
304
329
  await director.tap(input, { after: 0.2 });
330
+ // A tap leaves the caret where the finger landed and selects nothing: typed keys would join the old value.
331
+ // An empty field presses nothing, so it records frame for frame as before.
332
+ if (fillOptions?.clear !== false && (await input.inputValue()) !== "") {
333
+ await director.press("ControlOrMeta+A");
334
+ await director.press("Backspace");
335
+ const left = await input.inputValue();
336
+ if (left !== "") {
337
+ throw new Error(
338
+ `${where()}: ${String(input)} still holds "${left}" after select all and Backspace; ` +
339
+ `the app puts a value back. Set "clear": false or fix the scene: ${filmPath}`,
340
+ );
341
+ }
342
+ }
305
343
  await director.type(value);
306
344
  },
307
345
 
@@ -341,16 +379,10 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
341
379
  },
342
380
 
343
381
  async checkScreen() {
344
- const text = (await page.locator(settings.screenGuardSelector).first().innerText()).replace(/\s+/g, " ");
345
- const missing = film.screenGuard.filter((phrase) => !containsPhrase(text, phrase));
346
- if (missing.length > 0) {
347
- throw new ScreenGuardError(
348
- `The screen does not say what the voiceover says: missing ${missing.map((p) => `"${p}"`).join(", ")}. ` +
349
- `The app counts from the recording day: if the voiceover was paid for on another day, pin that day in the video's ` +
350
- `"today" (or pass --today=YYYY-MM-DD); otherwise fix the sentences and phrases in ${filmPath}.`,
351
- );
352
- }
382
+ const missing = findMissingPhrases(await readScreenText(), getCheckScreenPhrases(film.screenGuard, current?.sentence ?? null));
383
+ if (missing.length > 0) throw new ScreenGuardError(describeCheckScreenFailure(missing, filmPath));
353
384
  guardChecked = true;
385
+ if (current !== null) current.isGuardChecked = true;
354
386
  },
355
387
  };
356
388
 
@@ -362,7 +394,9 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
362
394
  `The scene recorded ${log.beats.length} of ${expectedBeats.length} sentences; "${expectedBeats[log.beats.length]}" is missing.`,
363
395
  );
364
396
  }
365
- if (!guardChecked) throw new Error("The scene never called checkScreen(): a film without the screen guard could say what the screen does not show.");
397
+ if (!guardChecked && film.screenGuard.length > 0) {
398
+ throw new Error("The scene never called checkScreen(): the video's screenGuard phrases were never checked, so the film could say what the screen does not show.");
399
+ }
366
400
  if (log.stills[film.hook.still] === undefined) {
367
401
  throw new Error(`The scene did not save the opening frame "${film.hook.still}" (still).`);
368
402
  }
@@ -0,0 +1,37 @@
1
+ import { containsPhrase, type Beat } from "../film.js";
2
+
3
+ /**
4
+ * The screen guard's rules, apart from the browser: which phrases a check covers and what a failure says. The
5
+ * video's `screenGuard` is checked at every `checkScreen`; a sentence's own `screenGuard` at a `checkScreen` inside
6
+ * that sentence, or, without one, when the sentence ends, so each number is proven on screen while it is spoken.
7
+ */
8
+
9
+ /** The phrases a `checkScreen` covers: the video's, plus the current sentence's own (none before the first sentence). */
10
+ export function getCheckScreenPhrases(videoPhrases: readonly string[], sentence: Beat | null): string[] {
11
+ return [...videoPhrases, ...(sentence?.screenGuard ?? [])];
12
+ }
13
+
14
+ /** The phrases the screen's text does not contain as whole words, in their order. */
15
+ export function findMissingPhrases(text: string, phrases: readonly string[]): string[] {
16
+ return phrases.filter((phrase) => !containsPhrase(text, phrase));
17
+ }
18
+
19
+ const quote = (phrases: readonly string[]): string => phrases.map((phrase) => `"${phrase}"`).join(", ");
20
+
21
+ function describeFix(filmPath: string): string {
22
+ return (
23
+ `The app counts from the recording day: if the voiceover was paid for on another day, pin that day in the video's ` +
24
+ `"today" (or pass --today=YYYY-MM-DD); otherwise fix the sentences and phrases in ${filmPath}.`
25
+ );
26
+ }
27
+
28
+ export function describeCheckScreenFailure(missing: readonly string[], filmPath: string): string {
29
+ return `The screen does not say what the voiceover says: missing ${quote(missing)}. ${describeFix(filmPath)}`;
30
+ }
31
+
32
+ export function describeSentenceFailure(sentenceId: string, missing: readonly string[], filmPath: string): string {
33
+ return (
34
+ `Sentence "${sentenceId}" ended without its screenGuard phrases on screen: missing ${quote(missing)}. ` +
35
+ `Reveal them before the sentence ends, or check them where they show with a checkScreen inside the sentence. ${describeFix(filmPath)}`
36
+ );
37
+ }