@softure-ai/marketing-kit 0.29.0 → 0.31.0

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 (40) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +15 -1
  3. package/dist/footage/draft-boxes.d.ts +3 -1
  4. package/dist/footage/draft-boxes.d.ts.map +1 -1
  5. package/dist/footage/draft-boxes.js +3 -2
  6. package/dist/footage/draft-boxes.js.map +1 -1
  7. package/dist/footage/draft-overlays.d.ts.map +1 -1
  8. package/dist/footage/draft-overlays.js +191 -41
  9. package/dist/footage/draft-overlays.js.map +1 -1
  10. package/dist/footage/edl.d.ts +27 -0
  11. package/dist/footage/edl.d.ts.map +1 -1
  12. package/dist/footage/overlay-html.d.ts +8 -0
  13. package/dist/footage/overlay-html.d.ts.map +1 -1
  14. package/dist/footage/overlay-html.js +127 -29
  15. package/dist/footage/overlay-html.js.map +1 -1
  16. package/dist/footage/overlay-motion.d.ts +107 -0
  17. package/dist/footage/overlay-motion.d.ts.map +1 -0
  18. package/dist/footage/overlay-motion.js +129 -0
  19. package/dist/footage/overlay-motion.js.map +1 -0
  20. package/dist/footage/overlay-schema.d.ts +63 -2
  21. package/dist/footage/overlay-schema.d.ts.map +1 -1
  22. package/dist/footage/overlay-schema.js +70 -5
  23. package/dist/footage/overlay-schema.js.map +1 -1
  24. package/dist/footage/overlays.d.ts +16 -1
  25. package/dist/footage/overlays.d.ts.map +1 -1
  26. package/dist/footage/overlays.js +43 -12
  27. package/dist/footage/overlays.js.map +1 -1
  28. package/dist/index.d.ts +3 -2
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +3 -2
  31. package/dist/index.js.map +1 -1
  32. package/package.json +1 -1
  33. package/schema/edl.schema.json +82 -1
  34. package/src/footage/draft-boxes.ts +7 -3
  35. package/src/footage/draft-overlays.ts +224 -42
  36. package/src/footage/overlay-html.ts +148 -27
  37. package/src/footage/overlay-motion.ts +157 -0
  38. package/src/footage/overlay-schema.ts +90 -5
  39. package/src/footage/overlays.ts +70 -16
  40. package/src/index.ts +22 -0
@@ -2,6 +2,18 @@ import type { BrandColors } from "../config/colors.js";
2
2
  import { escapeHtml } from "../compose/html.js";
3
3
  import { getCornerRadiusCss, getStyleBorderCss, getStyleShadowCss, type BrandStyle } from "./brand-style.js";
4
4
  import type { OverlayEntrance } from "./overlay-schema.js";
5
+ import {
6
+ PIN_DROP_SECONDS,
7
+ PIN_DROP_SHARE,
8
+ PIN_TITLE_LEAD,
9
+ UNDERLINE_EM,
10
+ UNDERLINE_SECONDS,
11
+ getEntranceMotion,
12
+ getExitMotion,
13
+ getWipeHalves,
14
+ type OverlayEntranceMotion,
15
+ type OverlayMotionOffset,
16
+ } from "./overlay-motion.js";
5
17
  import {
6
18
  OVERLAY_LINE_HEIGHT,
7
19
  OVERLAY_LIST_LINE_HEIGHT,
@@ -10,6 +22,8 @@ import {
10
22
  SEARCH_BAR_PADDING_EM,
11
23
  formatOverlayNumber,
12
24
  getOverlayPadding,
25
+ getPlaceCardPinRow,
26
+ getPlaceCardPinSize,
13
27
  getTitleContentBox,
14
28
  type ResolvedOverlay,
15
29
  } from "./overlays.js";
@@ -22,8 +36,8 @@ import {
22
36
  * `lt-soft-pill` (the lower third's scale-pop pill, dot and settling text), `marker-highlight` (the stroke drawn over
23
37
  * its target), `hw-arrow` (the drawn-on arrow whose head arrives last) and `push-in` (the eased camera push, in
24
38
  * `composeFootage`). They are rewritten for the kit's frame, timeline and brand tokens: see the package's NOTICE. The
25
- * entrances (`fade`, `slide`, `type`, `none`), the typed search field, the counting number and the drawn pin are the
26
- * kit's own, eased without overshoot.
39
+ * entrances and exits (`overlay-motion.ts`), the typed search field, the counting number and the drawn pin are the
40
+ * kit's own, eased without overshoot: nothing grows past its size.
27
41
  */
28
42
 
29
43
  /** The seconds an overlay takes to leave, ending with its clip. */
@@ -98,6 +112,15 @@ function getOverlayCss(colors: OverlayColors, fonts: { heading: string; interfac
98
112
  `.ov-date:not(.right) .ov-card{align-items:flex-start}`,
99
113
  `.ov-date .ov-sub{font-weight:600;margin-top:0}`,
100
114
  `.ty .ch{opacity:0}`,
115
+ // A wipe's accent panel over its card, the keyword's underline, a dropped pin, and the parts that come in later.
116
+ `.ov-card{position:relative}`,
117
+ `.ov-wipe{position:absolute;inset:0;border-radius:inherit;background:${colors.accent};transform-origin:100% 50%}`,
118
+ `.ov-ul{position:absolute;height:${UNDERLINE_EM.height}em;border-radius:${UNDERLINE_EM.height / 2}em;background:${colors.accent};transform:scaleX(0);transform-origin:0% 50%}`,
119
+ `.ov-pinrow{display:flex;justify-content:center}`,
120
+ `.ov-stack.left .ov-pinrow{justify-content:flex-start}`,
121
+ `.st li,.pd .ov-pinrow svg,.pl .ov-line,.sd .ov-sub{opacity:0}`,
122
+ // An underlined keyword keeps only its drawn bar: the card's own accent edge would be a second line under it.
123
+ `.ov-keyword.ul .ov-card{border-bottom-color:transparent}`,
101
124
  // The brand's style (after the kinds' own rules, so it wins over them; the search bar stays a pill).
102
125
  ...(style === undefined
103
126
  ? []
@@ -162,12 +185,55 @@ function getCardStyle(overlay: ResolvedOverlay, colors: OverlayColors, scale = 1
162
185
  return style === "" ? "" : ` style="${style}"`;
163
186
  }
164
187
 
165
- /** The entrance tweens of a card: fade, slide, a typed card's fade, or nothing. */
166
- function getEntranceTweens(target: string, entrance: OverlayEntrance, start: number): string[] {
167
- if (entrance === "none") return [];
168
- if (entrance === "slide") return [`tl.fromTo("${target}", { opacity: 0, y: 28 }, { opacity: 1, y: 0, duration: 0.5, ease: "power3.out", immediateRender: false }, ${start});`];
169
- const duration = entrance === "type" ? 0.25 : 0.4;
170
- return [`tl.fromTo("${target}", { opacity: 0 }, { opacity: 1, duration: ${duration}, ease: "power2.out", immediateRender: false }, ${start});`];
188
+ /** The GSAP properties of a motion offset: only what differs from rest, in a fixed order. */
189
+ function toTweenVars(offset: OverlayMotionOffset): string[] {
190
+ return [
191
+ `opacity: ${offset.opacity}`,
192
+ ...(offset.scale === 1 ? [] : [`scale: ${offset.scale}`]),
193
+ ...(offset.y === 0 ? [] : [`y: ${offset.y}`]),
194
+ ...(offset.blur === 0 ? [] : [`filter: "blur(${offset.blur}px)"`]),
195
+ ];
196
+ }
197
+
198
+ /** The same properties at rest: opacity 1, scale 1, in place, sharp. */
199
+ function toRestVars(offset: OverlayMotionOffset): string[] {
200
+ return [`opacity: 1`, ...(offset.scale === 1 ? [] : [`scale: 1`]), ...(offset.y === 0 ? [] : [`y: 0`]), ...(offset.blur === 0 ? [] : [`filter: "blur(0px)"`])];
201
+ }
202
+
203
+ /** The entrance tweens of a card (`target`): tweened from its offset, a wipe (its panel `wipe`), or nothing. */
204
+ function getMotionTweens(target: string, motion: OverlayEntranceMotion, start: number, wipe?: string): string[] {
205
+ if (motion.kind === "none") return [];
206
+ if (motion.kind === "wipe") {
207
+ // The card grows from the left under the accent panel, then the panel slides off to the right over the card and its text.
208
+ const halves = getWipeHalves(motion.seconds);
209
+ return [
210
+ `tl.fromTo("${target}", { clipPath: "inset(0% 100% 0% 0%)" }, { clipPath: "inset(0% 0% 0% 0%)", duration: ${halves.grow}, ease: "${motion.ease}", immediateRender: false }, ${start});`,
211
+ `tl.fromTo("${wipe ?? `${target} .ov-wipe`}", { scaleX: 1 }, { scaleX: 0, duration: ${halves.reveal}, ease: "${motion.ease}", immediateRender: false }, ${r3(start + halves.grow)});`,
212
+ ];
213
+ }
214
+ return [`tl.fromTo("${target}", { ${toTweenVars(motion.from).join(", ")} }, { ${[...toRestVars(motion.from), `duration: ${motion.seconds}`, `ease: "${motion.ease}"`, "immediateRender: false"].join(", ")} }, ${start});`];
215
+ }
216
+
217
+ /** The entrance tweens of a card by its named entrance (fade, slide, type, pop, rise, blur, wipe, or none). */
218
+ function getEntranceTweens(target: string, entrance: OverlayEntrance, start: number, look: { easing?: "smooth" | "snappy"; frame?: { width: number; height: number } } = {}): string[] {
219
+ return getMotionTweens(target, getEntranceMotion(entrance, look.easing ?? "smooth", look.frame ?? { width: 1080, height: 1920 }), start);
220
+ }
221
+
222
+ /** The seconds an overlay's entrance takes, so what comes after it (an underline) starts once it is in. */
223
+ function getEntranceSeconds(entrance: OverlayEntrance | null, overlay: ResolvedOverlay, frame: { width: number; height: number }): number {
224
+ if (entrance === null) return 0.45;
225
+ const motion = getEntranceMotion(entrance, overlay.kind === "punch_in" ? "smooth" : (overlay.easing ?? "smooth"), frame);
226
+ return motion.kind === "none" ? 0 : motion.seconds;
227
+ }
228
+
229
+ /** The exit tweens of an overlay's `target`, ending with its clip: its own (`own`, the kind's), tweened, wiped off, or none. */
230
+ function getExitTweens(target: string, overlay: Exclude<ResolvedOverlay, { kind: "punch_in" }>, frame: { width: number; height: number }, own: string): string[] {
231
+ const motion = getExitMotion({ exit: overlay.exit ?? "auto", entrance: overlay.entrance, easing: overlay.easing ?? "smooth", frame });
232
+ if (motion.kind === "none") return [];
233
+ if (motion.kind === "own") return [own];
234
+ const at = r3(overlay.end - motion.seconds);
235
+ if (motion.kind === "wipe") return [`tl.to("${target}", { clipPath: "inset(0% 0% 0% 100%)", duration: ${motion.seconds}, ease: "${motion.ease}" }, ${at});`];
236
+ return [`tl.to("${target}", { ${[...toTweenVars(motion.from), `duration: ${motion.seconds}`, `ease: "${motion.ease}"`].join(", ")} }, ${at});`];
171
237
  }
172
238
 
173
239
  /** The typing tweens: each character of `#<id>` shown at its time. */
@@ -195,28 +261,48 @@ function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lowe
195
261
  const isTyped = overlay.typing !== null && overlay.kind !== "list";
196
262
  const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;align-items:${overlay.kind === "lower_third" ? "flex-end" : "flex-start"}`;
197
263
  const text = overlay.kind === "list" ? "" : isTyped ? toTypedHtml(overlay.text) : escapeHtml(overlay.text);
264
+ const wipe = overlay.entrance === "wipe" ? `<i class="ov-wipe" id="${id}w"></i>` : "";
265
+ const underline = overlay.kind === "keyword" && overlay.underline === true ? `<i class="ov-ul" id="${id}u" style="${getUnderlineStyle(overlay)}"></i>` : "";
266
+ const staggered = overlay.kind === "list" ? overlay.itemStarts : undefined;
198
267
  const body =
199
268
  overlay.kind === "list"
200
- ? `<ul class="ov-card"${cardStyle}>${overlay.items.map((item, i) => `<li id="${id}i${i}"><i class="ov-dot"${dotStyle}></i>${escapeHtml(item)}</li>`).join("")}</ul>`
201
- : `<div class="ov-card"${cardStyle}>${overlay.kind === "lower_third" ? `<i class="ov-dot" id="${id}d"${dotStyle}></i>` : ""}<span id="${id}t">${text}</span></div>`;
202
- out.html.push(clipDiv(overlay, id, `ov ov-${overlay.kind.replace("_", "-")}${side === "right" ? " right" : ""}${isTyped ? " ty" : ""}`, style, body));
269
+ ? `<ul class="ov-card"${cardStyle}>${wipe}${overlay.items.map((item, i) => `<li id="${id}i${i}"><i class="ov-dot"${dotStyle}></i>${escapeHtml(item)}</li>`).join("")}</ul>`
270
+ : `<div class="ov-card"${cardStyle}>${wipe}${overlay.kind === "lower_third" ? `<i class="ov-dot" id="${id}d"${dotStyle}></i>` : ""}<span id="${id}t">${text}</span>${underline}</div>`;
271
+ out.html.push(clipDiv(overlay, id, `ov ov-${overlay.kind.replace("_", "-")}${side === "right" ? " right" : ""}${isTyped ? " ty" : ""}${staggered === undefined ? "" : " st"}${underline === "" ? "" : " ul"}`, style, body));
203
272
  if (overlay.entrance !== null) {
204
- out.tweens.push(...getEntranceTweens(`#${id} .ov-card`, overlay.entrance, overlay.start));
273
+ out.tweens.push(...getMotionTweens(`#${id} .ov-card`, getEntranceMotion(overlay.entrance, overlay.easing ?? "smooth", context.frame), overlay.start));
205
274
  if (overlay.kind !== "list") out.tweens.push(...getTypingTweens(id, overlay, [...overlay.text].length));
206
275
  } else {
207
- // The soft pill's entrance: the card rises from its foot, then its dot and its text settle in.
208
- out.tweens.push(`tl.fromTo("#${id} .ov-card", { scale: 0.88, y: 18, opacity: 0 }, { scale: 1, y: 0, opacity: 1, duration: 0.45, ease: "back.out(1.7)", immediateRender: false }, ${overlay.start});`);
276
+ // The soft pill's entrance: the card rises from its foot, then its dot and its text settle in, eased out without
277
+ // overshoot (RV-133 of an adopting app: nothing grows past its size).
278
+ out.tweens.push(`tl.fromTo("#${id} .ov-card", { scale: 0.88, y: 18, opacity: 0 }, { scale: 1, y: 0, opacity: 1, duration: 0.45, ease: "power3.out", immediateRender: false }, ${overlay.start});`);
209
279
  if (overlay.kind === "lower_third") {
210
- out.tweens.push(`tl.fromTo("#${id}d", { scale: 0 }, { scale: 1, duration: 0.35, ease: "back.out(3)", immediateRender: false }, ${r3(overlay.start + 0.25)});`);
280
+ out.tweens.push(`tl.fromTo("#${id}d", { scale: 0 }, { scale: 1, duration: 0.35, ease: "power2.out", immediateRender: false }, ${r3(overlay.start + 0.25)});`);
211
281
  out.tweens.push(`tl.fromTo("#${id}t", { opacity: 0, x: -10 }, { opacity: 1, x: 0, duration: 0.4, ease: "power3.out", immediateRender: false }, ${r3(overlay.start + 0.3)});`);
212
282
  }
213
- if (overlay.kind === "list") {
283
+ if (overlay.kind === "list" && staggered === undefined) {
214
284
  overlay.items.forEach((_item, i) => {
215
285
  out.tweens.push(`tl.fromTo("#${id}i${i}", { opacity: 0, y: 14 }, { opacity: 1, y: 0, duration: 0.35, ease: "power3.out", immediateRender: false }, ${r3(overlay.start + 0.2 + 0.12 * i)});`);
216
286
  });
217
287
  }
218
288
  }
219
- out.tweens.push(`tl.to("#${id} .ov-card", { scale: 0.94, y: 14, opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`);
289
+ // A staggered list's points come in one by one, each on its own second (`itemStarts`).
290
+ staggered?.forEach((at, i) => {
291
+ out.tweens.push(`tl.fromTo("#${id}i${i}", { opacity: 0, y: ${r3(14 * context.scale)} }, { opacity: 1, y: 0, duration: 0.35, ease: "power3.out", immediateRender: false }, ${at});`);
292
+ });
293
+ if (underline !== "") {
294
+ out.tweens.push(`tl.fromTo("#${id}u", { scaleX: 0 }, { scaleX: 1, duration: ${UNDERLINE_SECONDS}, ease: "power2.out", immediateRender: false }, ${r3(overlay.start + getEntranceSeconds(overlay.entrance, overlay, context.frame))});`);
295
+ }
296
+ out.tweens.push(
297
+ ...getExitTweens(`#${id} .ov-card`, overlay, context.frame, `tl.to("#${id} .ov-card", { scale: 0.94, y: 14, opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`),
298
+ );
299
+ }
300
+
301
+ /** Where a keyword's underline sits in its card: under the text, inside the card's padding. */
302
+ function getUnderlineStyle(overlay: Extract<ResolvedOverlay, { kind: "keyword" }>): string {
303
+ const pad = overlay.padScale ?? 1;
304
+ const x = r3(OVERLAY_PADDING_EM.x * pad);
305
+ return `left:${x}em;right:${x}em;bottom:${r3(Math.max(0.04, OVERLAY_PADDING_EM.y * pad - UNDERLINE_EM.gap - UNDERLINE_EM.height))}em`;
220
306
  }
221
307
 
222
308
  type CardOverlay = Extract<ResolvedOverlay, { kind: "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp" }>;
@@ -227,22 +313,25 @@ function getCardBody(overlay: CardOverlay, id: string, colors: OverlayColors, lo
227
313
  if (overlay.kind === "hook_title") {
228
314
  const place = overlay.place === null ? "" : `<div class="ov-place" style="font-size:${overlay.placeFontSize}px">${getPinSvg(colors.accent)}<span>${escapeHtml(overlay.place)}</span></div>`;
229
315
  const lines = overlay.lines.map((line) => `<div class="ov-line">${typedOrPlain(line)}</div>`).join("");
230
- return { classes: "ov-hook-title center", body: `<div class="ov-card ov-stack${overlay.align === "left" ? " left" : ""}"__STYLE__>${place}${lines}</div>`, typed: overlay.lines.join("").length };
316
+ return { classes: "ov-hook-title center", body: `<div class="ov-card ov-stack${overlay.align === "left" ? " left" : ""}"__STYLE__>__WIPE__${place}${lines}</div>`, typed: overlay.lines.join("").length };
231
317
  }
232
318
  if (overlay.kind === "place_card") {
233
319
  const subtitle = overlay.subtitle === null ? "" : `<div class="ov-sub" style="font-size:${overlay.subtitleFontSize}px">${escapeHtml(overlay.subtitle)}</div>`;
234
320
  const lines = overlay.lines.map((line) => `<div class="ov-line">${typedOrPlain(line)}</div>`).join("");
235
- return { classes: "ov-place-card center", body: `<div class="ov-card ov-stack${overlay.align === "left" ? " left" : ""}"__STYLE__>${lines}${subtitle}</div>`, typed: overlay.lines.join("").length };
321
+ const pinSize = getPlaceCardPinSize(overlay.fontSize);
322
+ const pin = overlay.pin === undefined ? "" : `<div class="ov-pinrow" id="${id}p" style="height:${getPlaceCardPinRow(overlay.fontSize)}px">${getPinSvg(colors.accent).replace('class="ov-pin"', `class="ov-pin" style="width:${pinSize}px;height:${pinSize}px"`)}</div>`;
323
+ const later = [overlay.pin === "drop" ? " pd" : "", overlay.pin !== undefined && overlay.typing === null ? " pl" : "", overlay.subtitleDelay === undefined || subtitle === "" ? "" : " sd"].join("");
324
+ return { classes: `ov-place-card center${later}`, body: `<div class="ov-card ov-stack${overlay.align === "left" ? " left" : ""}"__STYLE__>__WIPE__${pin}${lines}${subtitle}</div>`, typed: overlay.lines.join("").length };
236
325
  }
237
326
  if (overlay.kind === "search_bar") {
238
- return { classes: "ov-search-bar center", body: `<div class="ov-card ov-search"__STYLE__>${getGlassSvg(colors.accent)}<span id="${id}t">${typedOrPlain(overlay.text)}</span></div>`, typed: [...overlay.text].length };
327
+ return { classes: "ov-search-bar center", body: `<div class="ov-card ov-search"__STYLE__>__WIPE__${getGlassSvg(colors.accent)}<span id="${id}t">${typedOrPlain(overlay.text)}</span></div>`, typed: [...overlay.text].length };
239
328
  }
240
329
  if (overlay.kind === "counter") {
241
330
  const unit = overlay.unit === null ? "" : `<span class="ov-unit" style="font-size:${overlay.unitFontSize}px">${escapeHtml(overlay.unit)}</span>`;
242
- return { classes: "ov-counter center", body: `<div class="ov-card"__STYLE__><span id="${id}n">${escapeHtml(formatOverlayNumber(overlay.from, overlay.decimals, locale))}</span>${unit}</div>`, typed: 0 };
331
+ return { classes: "ov-counter center", body: `<div class="ov-card"__STYLE__>__WIPE__<span id="${id}n">${escapeHtml(formatOverlayNumber(overlay.from, overlay.decimals, locale))}</span>${unit}</div>`, typed: 0 };
243
332
  }
244
333
  const place = overlay.place === null ? "" : `<div class="ov-sub" style="font-size:${overlay.placeFontSize}px">${escapeHtml(overlay.place)}</div>`;
245
- return { classes: `ov-date${overlay.side === "right" ? " right" : ""}`, body: `<div class="ov-card"__STYLE__><span>${typedOrPlain(overlay.text)}</span>${place}</div>`, typed: [...overlay.text].length };
334
+ return { classes: `ov-date${overlay.side === "right" ? " right" : ""}`, body: `<div class="ov-card"__STYLE__>__WIPE__<span>${typedOrPlain(overlay.text)}</span>${place}</div>`, typed: [...overlay.text].length };
246
335
  }
247
336
 
248
337
  /** A hook title, a search bar, a place card, a counter or a date stamp. */
@@ -251,10 +340,12 @@ function addCard(overlay: CardOverlay, id: string, context: MarkupContext, out:
251
340
  const { box, fontSize } = overlay;
252
341
  const { classes, body, typed } = getCardBody(overlay, id, colors, context.locale);
253
342
  const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;align-items:flex-start`;
254
- out.html.push(clipDiv(overlay, id, `ov ${classes}${overlay.typing === null ? "" : " ty"}`, style, body.replace("__STYLE__", getCardStyle(overlay, colors, context.scale))));
343
+ const wipe = overlay.entrance === "wipe" ? `<i class="ov-wipe" id="${id}w"></i>` : "";
344
+ out.html.push(clipDiv(overlay, id, `ov ${classes}${overlay.typing === null ? "" : " ty"}`, style, body.replace("__STYLE__", getCardStyle(overlay, colors, context.scale)).replace("__WIPE__", wipe)));
255
345
  const entrance = overlay.entrance ?? (overlay.typing !== null ? "type" : DEFAULT_ENTRANCES[overlay.kind]);
256
- out.tweens.push(...getEntranceTweens(`#${id} .ov-card`, entrance, overlay.start));
346
+ out.tweens.push(...getEntranceTweens(`#${id} .ov-card`, entrance, overlay.start, { ...(overlay.easing === undefined ? {} : { easing: overlay.easing }), frame: context.frame }));
257
347
  out.tweens.push(...getTypingTweens(id, overlay, typed));
348
+ if (overlay.kind === "place_card") out.tweens.push(...getPlaceCardPartTweens(overlay, id, context));
258
349
  if (overlay.kind === "counter") {
259
350
  const count = getCounterSeconds(overlay);
260
351
  const format = `new Intl.NumberFormat(${toScriptString(getScriptLocale(context.locale))}, { minimumFractionDigits: ${overlay.decimals}, maximumFractionDigits: ${overlay.decimals} })`;
@@ -263,7 +354,37 @@ function addCard(overlay: CardOverlay, id: string, context: MarkupContext, out:
263
354
  `(function () { const el = document.getElementById("${id}n"); const nf = ${format}; const n = { v: ${overlay.from} }; tl.fromTo(n, { v: ${overlay.from} }, { v: ${overlay.value}, duration: ${count.duration}, ease: "power2.out", immediateRender: false, onUpdate: () => { el.textContent = nf.format(n.v).replace(/[\\u00a0\\u202f]/g, " "); } }, ${count.start}); })();`,
264
355
  );
265
356
  }
266
- out.tweens.push(`tl.to("#${id} .ov-card", { y: 10, opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`);
357
+ out.tweens.push(...getExitTweens(`#${id} .ov-card`, overlay, context.frame, `tl.to("#${id} .ov-card", { y: 10, opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`));
358
+ }
359
+
360
+ /**
361
+ * A place card's parts that come in after its card: its pin dropping a little onto its place (eased out, no bounce),
362
+ * its title once the pin is there, and its subtitle after its delay; the film seconds of each in `getPlaceCardTimes`.
363
+ */
364
+ function getPlaceCardPartTweens(overlay: Extract<ResolvedOverlay, { kind: "place_card" }>, id: string, context: MarkupContext): string[] {
365
+ const times = getPlaceCardTimes(overlay);
366
+ const tweens: string[] = [];
367
+ if (overlay.pin === "drop") {
368
+ const drop = r3(getPlaceCardPinSize(overlay.fontSize) * PIN_DROP_SHARE);
369
+ tweens.push(`tl.fromTo("#${id}p svg", { opacity: 0, y: -${drop} }, { opacity: 1, y: 0, duration: ${PIN_DROP_SECONDS}, ease: "power2.out", immediateRender: false }, ${overlay.start});`);
370
+ }
371
+ if (overlay.pin !== undefined && overlay.typing === null) {
372
+ tweens.push(`tl.fromTo("#${id} .ov-line", { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out", immediateRender: false }, ${times.title});`);
373
+ }
374
+ if (times.subtitle !== null && overlay.subtitleDelay !== undefined) {
375
+ tweens.push(`tl.fromTo("#${id} .ov-sub", { opacity: 0, y: ${r3(8 * context.scale)} }, { opacity: 1, y: 0, duration: 0.3, ease: "power2.out", immediateRender: false }, ${times.subtitle});`);
376
+ }
377
+ return tweens;
378
+ }
379
+
380
+ /** When a place card's pin, title and subtitle come in, in film seconds: pin first, then the title, then the subtitle. */
381
+ export function getPlaceCardTimes(overlay: Pick<Extract<ResolvedOverlay, { kind: "place_card" }>, "start" | "pin" | "typing" | "subtitle" | "subtitleDelay">): {
382
+ pin: number | null;
383
+ title: number;
384
+ subtitle: number | null;
385
+ } {
386
+ const title = overlay.pin !== undefined && overlay.typing === null ? r3(overlay.start + PIN_TITLE_LEAD) : overlay.start;
387
+ return { pin: overlay.pin === undefined ? null : overlay.start, title, subtitle: overlay.subtitle === null ? null : r3(title + (overlay.subtitleDelay ?? 0)) };
267
388
  }
268
389
 
269
390
  /** The brand's locale as a canonical BCP 47 tag (letters, digits and dashes only), `en-US` when it is not one. */
@@ -313,8 +434,8 @@ function addMark(overlay: Extract<ResolvedOverlay, { kind: "arrow" | "highlight"
313
434
  out.tweens.push(`tl.fromTo("#${id}f", { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "none", immediateRender: false }, ${r3(overlay.start + 0.3)});`);
314
435
  }
315
436
  }
316
- if (overlay.entrance === "fade") out.tweens.push(...getEntranceTweens(`#${id} .ov-svg`, "fade", overlay.start));
317
- out.tweens.push(`tl.to("#${id} .ov-svg", { opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`);
437
+ if (overlay.entrance === "fade") out.tweens.push(...getEntranceTweens(`#${id} .ov-svg`, "fade", overlay.start, { ...(overlay.easing === undefined ? {} : { easing: overlay.easing }), frame }));
438
+ out.tweens.push(...getExitTweens(`#${id} .ov-svg`, overlay, frame, `tl.to("#${id} .ov-svg", { opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`));
318
439
  }
319
440
 
320
441
  /**
@@ -0,0 +1,157 @@
1
+ import type { OverlayEasing, OverlayEntrance, OverlayExit } from "./overlay-schema.js";
2
+
3
+ /**
4
+ * How a drawn overlay moves in and out (RV-133 of an adopting app): one model the render's GSAP tweens and the draft's
5
+ * ASS tags both read, so the two stay one look. Every curve eases out without overshoot: a value travels from its
6
+ * start to its rest and never past it, so no element grows past 100 % (`getEntranceScaleAt`). No bounce, no elastic.
7
+ */
8
+
9
+ /** A GSAP ease name and its curve: each one rises from 0 to 1 and never passes 1. */
10
+ export const OVERLAY_EASES = {
11
+ "power2.out": (t: number) => 1 - (1 - t) ** 2,
12
+ "power3.out": (t: number) => 1 - (1 - t) ** 3,
13
+ "expo.out": (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t)),
14
+ "power2.in": (t: number) => t ** 2,
15
+ } as const;
16
+
17
+ export type OverlayEase = keyof typeof OVERLAY_EASES;
18
+
19
+ /** How far from its rest an overlay starts or ends: its opacity, its scale, px below its place, px of blur. */
20
+ export interface OverlayMotionOffset {
21
+ opacity: number;
22
+ scale: number;
23
+ y: number;
24
+ blur: number;
25
+ }
26
+
27
+ /** A tweened entrance: from `from` to rest over `seconds` along `ease`. */
28
+ export interface OverlayTween {
29
+ from: OverlayMotionOffset;
30
+ seconds: number;
31
+ ease: OverlayEase;
32
+ }
33
+
34
+ /** The entrance of an overlay: tweened, a wipe (accent in, then the card and its text), or none (simply there). */
35
+ export type OverlayEntranceMotion = ({ kind: "tween" } & OverlayTween) | { kind: "wipe"; seconds: number; ease: OverlayEase } | { kind: "none" };
36
+
37
+ /** The exit of an overlay: tweened to `from` over its last `seconds`, wiped off to the right, the kind's own, or none. */
38
+ export type OverlayExitMotion = ({ kind: "tween" } & OverlayTween) | { kind: "wipe"; seconds: number; ease: OverlayEase } | { kind: "own" } | { kind: "none" };
39
+
40
+ /** A pop's start scale: 92 % of its size. */
41
+ export const POP_FROM_SCALE = 0.92;
42
+ /** A pop's exit scale: it shrinks to 96 % as it fades. */
43
+ const POP_EXIT_SCALE = 0.96;
44
+ /** A rise starts this share of the frame's height below its place (4 to 6 %). */
45
+ export const RISE_FROM_HEIGHT = 0.05;
46
+ /** A blur's start, in px of a 1080 px wide frame. */
47
+ export const BLUR_FROM_PX = 14;
48
+ /** A slide's start below its place, in px of a 1080 px wide frame. */
49
+ const SLIDE_FROM_PX = 28;
50
+ /** A slide exit's travel down, in px of a 1080 px wide frame. */
51
+ const SLIDE_EXIT_PX = 14;
52
+ /** The seconds of an exit (smooth). */
53
+ export const OVERLAY_EXIT_SECONDS = 0.3;
54
+ /** How much quicker a snappy curve runs. */
55
+ const SNAPPY_SPEED = 0.7;
56
+
57
+ const REST: OverlayMotionOffset = { opacity: 1, scale: 1, y: 0, blur: 0 };
58
+ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
59
+
60
+ /** The smooth entrances' offsets, seconds and eases; `scale` is the frame's width / 1080, `height` its height. */
61
+ function getSmoothEntrance(entrance: Exclude<OverlayEntrance, "none" | "wipe">, frame: { scale: number; height: number }): OverlayTween {
62
+ switch (entrance) {
63
+ case "fade":
64
+ return { from: { ...REST, opacity: 0 }, seconds: 0.4, ease: "power2.out" };
65
+ case "type":
66
+ return { from: { ...REST, opacity: 0 }, seconds: 0.25, ease: "power2.out" };
67
+ case "slide":
68
+ return { from: { ...REST, opacity: 0, y: r3(SLIDE_FROM_PX * frame.scale) }, seconds: 0.5, ease: "power3.out" };
69
+ case "pop":
70
+ return { from: { ...REST, opacity: 0, scale: POP_FROM_SCALE }, seconds: 0.3, ease: "power2.out" };
71
+ case "rise":
72
+ return { from: { ...REST, opacity: 0, y: r3(RISE_FROM_HEIGHT * frame.height) }, seconds: 0.3, ease: "power3.out" };
73
+ case "blur":
74
+ return { from: { ...REST, opacity: 0, blur: r3(BLUR_FROM_PX * frame.scale) }, seconds: 0.3, ease: "power2.out" };
75
+ }
76
+ }
77
+
78
+ /** A curve's seconds and ease for the easing: snappy runs 0.7 as long on `expo.out`. */
79
+ function withEasing<T extends { seconds: number; ease: OverlayEase }>(motion: T, easing: OverlayEasing): T {
80
+ return easing === "snappy" ? { ...motion, seconds: r3(motion.seconds * SNAPPY_SPEED), ease: "expo.out" } : motion;
81
+ }
82
+
83
+ /** An overlay's entrance motion: `entrance` already resolved to a named one (the kind's own when the overlay names none). */
84
+ export function getEntranceMotion(entrance: OverlayEntrance, easing: OverlayEasing, frame: { width: number; height: number }): OverlayEntranceMotion {
85
+ if (entrance === "none") return { kind: "none" };
86
+ if (entrance === "wipe") return withEasing({ kind: "wipe" as const, seconds: 0.5, ease: "power3.out" }, easing);
87
+ return withEasing({ kind: "tween" as const, ...getSmoothEntrance(entrance, { scale: frame.width / 1080, height: frame.height }) }, easing);
88
+ }
89
+
90
+ /**
91
+ * An overlay's exit motion. `auto` mirrors its named entrance: a fade, a typed or a slid entrance leave by fading or
92
+ * sliding down; a pop shrinks to 96 % as it fades; a rise sinks half its way; a blur blurs; a wipe is wiped off to the
93
+ * right; no entrance (`entrance` null) or `none` leave the kind's own way (`own`), as before RV-133. Only `exit: none`
94
+ * leaves at once.
95
+ */
96
+ export function getExitMotion(input: { exit: OverlayExit; entrance: OverlayEntrance | null; easing: OverlayEasing; frame: { width: number; height: number } }): OverlayExitMotion {
97
+ const { exit, entrance, easing, frame } = input;
98
+ const scale = frame.width / 1080;
99
+ const fade: OverlayTween = { from: { ...REST, opacity: 0 }, seconds: OVERLAY_EXIT_SECONDS, ease: "power2.in" };
100
+ const slide: OverlayTween = { ...fade, from: { ...fade.from, y: r3(SLIDE_EXIT_PX * scale) } };
101
+ const tween = (motion: OverlayTween): OverlayExitMotion => ({ kind: "tween", ...withEasing(motion, easing), ease: easing === "snappy" ? "power2.in" : motion.ease });
102
+ if (exit === "none") return { kind: "none" };
103
+ if (exit === "fade") return tween(fade);
104
+ if (exit === "slide") return tween(slide);
105
+ switch (entrance) {
106
+ case null:
107
+ case "none":
108
+ return { kind: "own" };
109
+ case "fade":
110
+ case "type":
111
+ return tween(fade);
112
+ case "slide":
113
+ return tween(slide);
114
+ case "pop":
115
+ return tween({ ...fade, from: { ...fade.from, scale: POP_EXIT_SCALE } });
116
+ case "rise":
117
+ return tween({ ...fade, from: { ...fade.from, y: r3((RISE_FROM_HEIGHT / 2) * frame.height) } });
118
+ case "blur":
119
+ return tween({ ...fade, from: { ...fade.from, blur: r3((BLUR_FROM_PX / 1.4) * scale) } });
120
+ case "wipe":
121
+ return { kind: "wipe", seconds: easing === "snappy" ? r3(OVERLAY_EXIT_SECONDS * SNAPPY_SPEED) : OVERLAY_EXIT_SECONDS, ease: "power2.in" };
122
+ }
123
+ }
124
+
125
+ /** The scale an entrance gives `seconds` after it starts: from its start scale up to 1, never past it. */
126
+ export function getEntranceScaleAt(motion: OverlayEntranceMotion, seconds: number): number {
127
+ if (motion.kind !== "tween") return 1;
128
+ const progress = Math.min(1, Math.max(0, seconds / motion.seconds));
129
+ return motion.from.scale + (1 - motion.from.scale) * OVERLAY_EASES[motion.ease](progress);
130
+ }
131
+
132
+ /** A wipe's two halves: the accent panel grows from the left over the first, then slides off to the right over the second. */
133
+ export function getWipeHalves(seconds: number): { grow: number; reveal: number } {
134
+ return { grow: r3(seconds / 2), reveal: r3(seconds / 2) };
135
+ }
136
+
137
+ /** A place card's pin drops this share of its own size before it stops, over these seconds. */
138
+ export const PIN_DROP_SHARE = 0.6;
139
+ export const PIN_DROP_SECONDS = 0.35;
140
+ /** A place card's title follows its pin by this long, so the pin comes first. */
141
+ export const PIN_TITLE_LEAD = 0.2;
142
+ /** A keyword's underline is drawn over these seconds, after its entrance. */
143
+ export const UNDERLINE_SECONDS = 0.35;
144
+ /** A keyword's underline: its thickness and its gap under the text, in em of the keyword. */
145
+ export const UNDERLINE_EM = { height: 0.09, gap: 0.05 } as const;
146
+
147
+ /**
148
+ * The film seconds each point of a staggered list comes in at: on its word (`words`, the said times, never before the
149
+ * list nor later than its last 0.6 s), else spaced over the first part of its span (0.25 to 0.6 s apart).
150
+ */
151
+ export function getListItemStarts(input: { start: number; end: number; count: number; words?: readonly number[] }): number[] {
152
+ const { start, end, count } = input;
153
+ const latest = Math.max(start, end - 0.6);
154
+ if (input.words !== undefined) return input.words.map((word) => r3(Math.min(latest, Math.max(start, word))));
155
+ const gap = Math.min(0.6, Math.max(0.25, ((end - start) * 0.4) / count));
156
+ return Array.from({ length: count }, (_item, index) => r3(Math.min(latest, start + 0.2 + index * gap)));
157
+ }
@@ -46,12 +46,37 @@ export const OVERLAY_ALIGNED_KINDS: readonly OverlayKind[] = ["hook_title", "pla
46
46
 
47
47
  /**
48
48
  * How an overlay enters: `fade` in place, `slide` up into place, `type` letter by letter (text kinds), `none` (it is
49
- * simply there). Without one, the kind's own entrance. Never a bounce or a pop: the reel stays natural.
49
+ * simply there), `pop` (grows from 92 % to 100 % while it fades in, eased out, never past its size), `rise` (up from
50
+ * 5 % of the frame's height while it fades in), `blur` (from a slight blur to sharp) or `wipe` (its card revealed from
51
+ * the left in the accent colour, then its text). Without one, the kind's own entrance. Never a bounce or an overshoot:
52
+ * the reel stays natural (`overlay-motion.ts`).
50
53
  */
51
- export const OVERLAY_ENTRANCES = ["fade", "slide", "type", "none"] as const;
54
+ export const OVERLAY_ENTRANCES = ["fade", "slide", "type", "none", "pop", "rise", "blur", "wipe"] as const;
52
55
 
53
56
  export type OverlayEntrance = (typeof OVERLAY_ENTRANCES)[number];
54
57
 
58
+ /**
59
+ * How an overlay leaves over its last moment: `auto` mirrors its entrance (a pop shrinks a little as it fades, a rise
60
+ * sinks, a blur blurs, a wipe is wiped off to the right; the kind's own exit without an entrance), `fade`, `slide`
61
+ * (down and out) or `none` (gone at its end).
62
+ */
63
+ export const OVERLAY_EXITS = ["auto", "fade", "slide", "none"] as const;
64
+
65
+ export type OverlayExit = (typeof OVERLAY_EXITS)[number];
66
+
67
+ /** The curve of an overlay's entrance and exit: `smooth` (the default, a soft ease-out) or `snappy` (quicker, sharper). */
68
+ export const OVERLAY_EASINGS = ["smooth", "snappy"] as const;
69
+
70
+ export type OverlayEasing = (typeof OVERLAY_EASINGS)[number];
71
+
72
+ /** A place card's pin above its title: `none`, `static` (there with the card) or `drop` (falls a little and stops). */
73
+ export const OVERLAY_PINS = ["none", "static", "drop"] as const;
74
+
75
+ export type OverlayPin = (typeof OVERLAY_PINS)[number];
76
+
77
+ /** The longest a place card's subtitle waits after its title, in seconds. */
78
+ export const MAX_OVERLAY_SUBTITLE_DELAY = 0.6;
79
+
55
80
  /** The shortest an overlay stays on screen: shorter does not read. */
56
81
  export const MIN_OVERLAY_SECONDS = 1;
57
82
  /** The longest an overlay stays on screen (a `hook_title` may stay up to `MAX_HOOK_TITLE_SECONDS`). */
@@ -121,6 +146,18 @@ export interface EdlOverlayStyle {
121
146
  align?: OverlayAlign;
122
147
  /** A place card's subtitle size: `s`, `m` (about 55 % of the title, the default) or `l`. */
123
148
  subtitle_size?: OverlaySize;
149
+ /** How it leaves (`auto` without it: mirrors the entrance). */
150
+ exit?: OverlayExit;
151
+ /** The curve of its entrance and exit (`smooth` without it). */
152
+ easing?: OverlayEasing;
153
+ /** A list's points come in one by one (on their `item_words` when given, else spaced automatically). */
154
+ stagger?: boolean;
155
+ /** Seconds a place card's subtitle waits after its title (0 to `MAX_OVERLAY_SUBTITLE_DELAY`). */
156
+ subtitle_delay?: number;
157
+ /** A place card's accent pin above its title. */
158
+ pin?: OverlayPin;
159
+ /** A keyword's accent bar drawn under the word after it enters. */
160
+ underline?: boolean;
124
161
  }
125
162
 
126
163
  export interface EdlOverlay {
@@ -135,6 +172,10 @@ export interface EdlOverlay {
135
172
  text?: string;
136
173
  /** The `list` points (2 to 4). */
137
174
  items?: string[];
175
+ /** A `list`'s words its points come in on, one per point (they come in one by one); give this or `item_at`. */
176
+ item_words?: EdlOverlayWord[];
177
+ /** A `list`'s film seconds its points come in at, one per point; give this or `item_words`. */
178
+ item_at?: number[];
138
179
  /** The `arrow` point or the `highlight` rectangle. */
139
180
  anchor?: EdlOverlayAnchor;
140
181
  /** The place label of a `hook_title` (with a pin) or a `date_stamp`. */
@@ -201,8 +242,8 @@ export const OVERLAY_POSITIONS_BY_KIND: Partial<Record<OverlayKind, readonly Ove
201
242
  counter: ["top", "middle", "bottom"],
202
243
  };
203
244
 
204
- const TEXT_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "type", "none"];
205
- const BLOCK_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "none"];
245
+ const TEXT_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "type", "none", "pop", "rise", "blur", "wipe"];
246
+ const BLOCK_ENTRANCES: readonly OverlayEntrance[] = ["fade", "slide", "none", "pop", "rise", "blur", "wipe"];
206
247
 
207
248
  /** The entrances a kind may take (none listed: it takes no entrance). */
208
249
  export const OVERLAY_ENTRANCES_BY_KIND: Record<OverlayKind, readonly OverlayEntrance[]> = {
@@ -242,6 +283,15 @@ function checkOverlayFields(overlay: EdlOverlay, issue: (path: string[], message
242
283
  const limit = TEXT_LIMITS[kind];
243
284
  if (limit !== undefined && overlay.text !== undefined && overlay.text.length > limit) issue(["text"], `is longer than ${limit} characters`);
244
285
  if (fields.items && overlay.items === undefined) issue(["items"], "a list needs 2 to 4 points");
286
+ if (overlay.item_words !== undefined) {
287
+ if (kind !== "list") issue(["item_words"], `${article(kind)} has no points; leave item_words out`);
288
+ else if (overlay.items !== undefined && overlay.item_words.length !== overlay.items.length) issue(["item_words"], `gives ${overlay.item_words.length} words for ${overlay.items.length} points; one word per point`);
289
+ }
290
+ if (overlay.item_at !== undefined) {
291
+ if (kind !== "list") issue(["item_at"], `${article(kind)} has no points; leave item_at out`);
292
+ else if (overlay.item_words !== undefined) issue(["item_at"], "give item_words or item_at, not both");
293
+ else if (overlay.items !== undefined && overlay.item_at.length !== overlay.items.length) issue(["item_at"], `gives ${overlay.item_at.length} seconds for ${overlay.items.length} points; one second per point`);
294
+ }
245
295
  if (!fields.items && overlay.items !== undefined) issue(["items"], `${article(kind)} draws no points; leave them out`);
246
296
  if (fields.anchor === "none" && overlay.anchor !== undefined) issue(["anchor"], `${article(kind)} has no anchor; leave it out`);
247
297
  if (fields.anchor !== "none" && overlay.anchor === undefined) issue(["anchor"], `${article(kind)} needs its anchor`);
@@ -274,6 +324,11 @@ function checkOverlayStyle(overlay: EdlOverlay, issue: (path: string[], message:
274
324
  if (style.corner_radius !== undefined && (kind === "punch_in" || kind === "arrow" || kind === "highlight")) issue(["style", "corner_radius"], `${article(kind)} draws no card; leave corner_radius out`);
275
325
  if (style.align !== undefined && !OVERLAY_ALIGNED_KINDS.includes(kind)) issue(["style", "align"], "only a hook_title or a place_card aligns its lines; leave align out");
276
326
  if (style.subtitle_size !== undefined && kind !== "place_card") issue(["style", "subtitle_size"], "only a place_card has a subtitle; leave subtitle_size out");
327
+ if (style.subtitle_delay !== undefined && kind !== "place_card") issue(["style", "subtitle_delay"], "only a place_card has a subtitle; leave subtitle_delay out");
328
+ if (style.pin !== undefined && kind !== "place_card") issue(["style", "pin"], "only a place_card draws a pin; leave pin out");
329
+ if (style.stagger !== undefined && kind !== "list") issue(["style", "stagger"], "only a list has points to stagger; leave stagger out");
330
+ if (style.underline !== undefined && kind !== "keyword") issue(["style", "underline"], "only a keyword is underlined; leave underline out");
331
+ if ((style.exit !== undefined || style.easing !== undefined) && kind === "punch_in") issue(["style", style.exit === undefined ? "easing" : "exit"], "a punch_in eases the picture itself; leave exit and easing out");
277
332
  if (style.colors === undefined) return;
278
333
  if (kind === "punch_in") issue(["style", "colors"], "a punch_in draws nothing to colour; leave colors out");
279
334
  if ((kind === "arrow" || kind === "highlight") && (style.colors.card !== undefined || style.colors.text !== undefined)) {
@@ -310,6 +365,23 @@ export const overlaySchema = z
310
365
  .max(4, "a list needs 2 to 4 points")
311
366
  .optional()
312
367
  .describe(`The list's points: 2 to 4, up to ${MAX_OVERLAY_LIST_ITEM_LENGTH} characters each.`),
368
+ item_words: z
369
+ .array(
370
+ z.strictObject({
371
+ text: overlayText.describe("The word as the transcript has it; compared without case and punctuation."),
372
+ occurrence: z.number().int().min(1).optional().describe("Which time the film says it (1 the first, the default)."),
373
+ }),
374
+ )
375
+ .min(2)
376
+ .max(4)
377
+ .optional()
378
+ .describe("A list only: the word each point comes in on, one per point in order; the points come in one by one."),
379
+ item_at: z
380
+ .array(z.number().min(0))
381
+ .min(2)
382
+ .max(4)
383
+ .optional()
384
+ .describe("A list only, in place of item_words: the film second each point comes in at, one per point in order."),
313
385
  anchor: z
314
386
  .strictObject({
315
387
  x: z.number().min(0).describe("Px from the frame's left edge."),
@@ -344,7 +416,11 @@ export const overlaySchema = z
344
416
  entrance: z
345
417
  .enum(OVERLAY_ENTRANCES)
346
418
  .optional()
347
- .describe("fade, slide, type (text typed in letter by letter) or none; without it the kind's own. Never a bounce or a pop."),
419
+ .describe(
420
+ "fade, slide, type (text typed in letter by letter), none, pop (92 % to 100 %, no overshoot), rise (up from 5 % of the height), blur (blurred to sharp) or wipe (card revealed from the left in the accent, then the text); without it the kind's own. Never a bounce.",
421
+ ),
422
+ exit: z.enum(OVERLAY_EXITS).optional().describe("auto (the default: mirrors the entrance), fade, slide (down and out) or none."),
423
+ easing: z.enum(OVERLAY_EASINGS).optional().describe("smooth (the default) or snappy: the curve of the entrance and the exit."),
348
424
  typing_speed: z
349
425
  .number()
350
426
  .min(MIN_OVERLAY_TYPING_SPEED)
@@ -365,6 +441,15 @@ export const overlaySchema = z
365
441
  .describe("The card's corner: none, s, m, l or pill; the brand style's without it (no punch_in, arrow or highlight)."),
366
442
  align: z.enum(OVERLAY_ALIGNS).optional().describe("center (the default) or left: how a hook_title's or a place_card's lines sit in their card."),
367
443
  subtitle_size: z.enum(OVERLAY_SIZES).optional().describe("s, m (the default, about 55 % of the title) or l: a place_card's subtitle size."),
444
+ stagger: z.boolean().optional().describe("A list only: its points come in one by one (on item_words when given, else spaced automatically)."),
445
+ subtitle_delay: z
446
+ .number()
447
+ .min(0)
448
+ .max(MAX_OVERLAY_SUBTITLE_DELAY)
449
+ .optional()
450
+ .describe(`A place_card only: seconds its subtitle waits after its title (0-${MAX_OVERLAY_SUBTITLE_DELAY}).`),
451
+ pin: z.enum(OVERLAY_PINS).optional().describe("A place_card only: none (the default), static or drop (an accent pin above the title that falls a little and stops)."),
452
+ underline: z.boolean().optional().describe("A keyword only: an accent bar drawn under the word after it enters."),
368
453
  })
369
454
  .optional()
370
455
  .describe("The overlay's look: size, side, position, entrance, typing speed and colours; fonts are the brand's."),