@softure-ai/marketing-kit 0.34.0 → 0.35.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 (88) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/NOTICE +6 -0
  3. package/README.md +26 -0
  4. package/dist/config/schema.d.ts +8 -0
  5. package/dist/config/schema.d.ts.map +1 -1
  6. package/dist/config/schema.js +1 -1
  7. package/dist/config/schema.js.map +1 -1
  8. package/dist/footage/compose.d.ts +2 -1
  9. package/dist/footage/compose.d.ts.map +1 -1
  10. package/dist/footage/compose.js +16 -3
  11. package/dist/footage/compose.js.map +1 -1
  12. package/dist/footage/draft-overlays.d.ts +6 -0
  13. package/dist/footage/draft-overlays.d.ts.map +1 -1
  14. package/dist/footage/draft-overlays.js +188 -4
  15. package/dist/footage/draft-overlays.js.map +1 -1
  16. package/dist/footage/draft.d.ts +11 -0
  17. package/dist/footage/draft.d.ts.map +1 -1
  18. package/dist/footage/draft.js +45 -3
  19. package/dist/footage/draft.js.map +1 -1
  20. package/dist/footage/drawn-transitions.d.ts +63 -0
  21. package/dist/footage/drawn-transitions.d.ts.map +1 -0
  22. package/dist/footage/drawn-transitions.js +177 -0
  23. package/dist/footage/drawn-transitions.js.map +1 -0
  24. package/dist/footage/edl.d.ts +16 -0
  25. package/dist/footage/edl.d.ts.map +1 -1
  26. package/dist/footage/edl.js +24 -1
  27. package/dist/footage/edl.js.map +1 -1
  28. package/dist/footage/film.d.ts +4 -3
  29. package/dist/footage/film.d.ts.map +1 -1
  30. package/dist/footage/film.js +3 -2
  31. package/dist/footage/film.js.map +1 -1
  32. package/dist/footage/hand-font.d.ts +16 -0
  33. package/dist/footage/hand-font.d.ts.map +1 -0
  34. package/dist/footage/hand-font.js +43 -0
  35. package/dist/footage/hand-font.js.map +1 -0
  36. package/dist/footage/overlay-html.d.ts +1 -0
  37. package/dist/footage/overlay-html.d.ts.map +1 -1
  38. package/dist/footage/overlay-html.js +134 -8
  39. package/dist/footage/overlay-html.js.map +1 -1
  40. package/dist/footage/overlay-motion.d.ts +35 -0
  41. package/dist/footage/overlay-motion.d.ts.map +1 -1
  42. package/dist/footage/overlay-motion.js +45 -0
  43. package/dist/footage/overlay-motion.js.map +1 -1
  44. package/dist/footage/overlay-schema.d.ts +48 -6
  45. package/dist/footage/overlay-schema.d.ts.map +1 -1
  46. package/dist/footage/overlay-schema.js +71 -18
  47. package/dist/footage/overlay-schema.js.map +1 -1
  48. package/dist/footage/overlays.d.ts +125 -1
  49. package/dist/footage/overlays.d.ts.map +1 -1
  50. package/dist/footage/overlays.js +260 -8
  51. package/dist/footage/overlays.js.map +1 -1
  52. package/dist/footage/picture.d.ts +5 -2
  53. package/dist/footage/picture.d.ts.map +1 -1
  54. package/dist/footage/picture.js +30 -8
  55. package/dist/footage/picture.js.map +1 -1
  56. package/dist/footage/pipeline.d.ts.map +1 -1
  57. package/dist/footage/pipeline.js +7 -1
  58. package/dist/footage/pipeline.js.map +1 -1
  59. package/dist/footage/tools.d.ts +1 -1
  60. package/dist/footage/tools.d.ts.map +1 -1
  61. package/dist/footage/tools.js +1 -1
  62. package/dist/footage/tools.js.map +1 -1
  63. package/dist/index.d.ts +5 -3
  64. package/dist/index.d.ts.map +1 -1
  65. package/dist/index.js +5 -3
  66. package/dist/index.js.map +1 -1
  67. package/fonts/Caveat-SemiBold-Latin.ttf +0 -0
  68. package/fonts/LICENSE-Caveat.txt +93 -0
  69. package/fonts/README.md +14 -0
  70. package/package.json +1 -1
  71. package/schema/edl.schema.json +38 -11
  72. package/schema/marketing.schema.json +10 -2
  73. package/src/config/schema.ts +1 -1
  74. package/src/footage/compose.ts +14 -3
  75. package/src/footage/draft-overlays.ts +217 -2
  76. package/src/footage/draft.ts +54 -3
  77. package/src/footage/drawn-transitions.ts +214 -0
  78. package/src/footage/edl.ts +21 -1
  79. package/src/footage/film.ts +3 -2
  80. package/src/footage/hand-font.ts +47 -0
  81. package/src/footage/overlay-html.ts +141 -7
  82. package/src/footage/overlay-motion.ts +49 -0
  83. package/src/footage/overlay-schema.ts +78 -19
  84. package/src/footage/overlays.ts +306 -10
  85. package/src/footage/picture.ts +35 -10
  86. package/src/footage/pipeline.ts +7 -1
  87. package/src/footage/tools.ts +1 -1
  88. package/src/index.ts +32 -0
@@ -3,6 +3,8 @@ import { z } from "zod";
3
3
  import type { TimedWord } from "../voice/voiceover.js";
4
4
  import { cameraSchema, describeCamera, isSameCamera, type EdlCamera } from "./camera.js";
5
5
  import { overlaySchema, type EdlOverlay } from "./overlay-schema.js";
6
+ import { DRAWN_TRANSITION_FRAMES, isDrawnTransition, STUTTER_FRAMES } from "./drawn-transitions.js";
7
+ import { FOOTAGE_FPS } from "./normalize.js";
6
8
  import { CUT_TRANSITIONS, type ClipRole, type CutOptions, type CutTransition, type FootageTransitions } from "./film.js";
7
9
  import { splitFilmSentences, type Sentence } from "./sentences.js";
8
10
  import { isFiller } from "./words.js";
@@ -92,7 +94,7 @@ const segmentFields = {
92
94
  clip: z.string().min(1).describe("The clip's id: the picture, and the sound unless audio says otherwise."),
93
95
  start: z.number().min(0).describe("Seconds in the trimmed clip where the segment starts."),
94
96
  end: z.number().positive().describe("Seconds in the trimmed clip where the segment ends."),
95
- transition: z.enum(CUT_TRANSITIONS).describe("How the segment starts: cut, fade (a cross-fade from the segment before), zoom (a punch-in) or whoosh."),
97
+ transition: z.enum(CUT_TRANSITIONS).describe("How the segment starts: cut, fade (a cross-fade from the segment before), zoom (a punch-in), whoosh, whip (a whip pan with motion blur, 14 frames), card (the shot grows from a small card, 13 frames), paper (a torn-paper wipe, 12 frames) or stutter (5 frames wide, then tight)."),
96
98
  motion: z.enum(SEGMENT_MOTIONS).describe("kenburns: a slow zoom over the segment; none: still."),
97
99
  };
98
100
 
@@ -332,12 +334,30 @@ export function validateEdl(edl: Edl, clips: Pick<EdlClip, "id" | "duration">[],
332
334
  function findCameraProblems(at: string, segment: EdlSegment): string[] {
333
335
  const problems: string[] = [];
334
336
  if (segment.fadeFrames !== undefined && segment.transition !== "fade") problems.push(`${at}.fadeFrames: only a fade cut has a length; this segment starts on a ${segment.transition}`);
337
+ problems.push(...findTransitionProblems(at, segment));
335
338
  if (segment.camera === undefined) return problems;
336
339
  if (segment.motion === "kenburns") problems.push(`${at}.camera: the segment has a Ken Burns zoom, which owns the picture's scale; set motion to none or drop the camera`);
337
340
  if (segment.transition === "zoom") problems.push(`${at}.camera: the segment starts on a zoom cut, which owns the picture's scale; start it on a cut or a fade`);
338
341
  return problems;
339
342
  }
340
343
 
344
+ /**
345
+ * A drawn transition on a segment shorter than its frames (its head is the transition), and a stutter beside a zoom of
346
+ * its own: a moving camera or a Ken Burns zoom (the stutter holds one tight framing after its wide frames).
347
+ */
348
+ function findTransitionProblems(at: string, segment: EdlSegment): string[] {
349
+ const problems: string[] = [];
350
+ const frames = Math.round((segment.end - segment.start) * FOOTAGE_FPS);
351
+ if (isDrawnTransition(segment.transition) && frames <= DRAWN_TRANSITION_FRAMES[segment.transition]) {
352
+ problems.push(`${at}.transition: a ${segment.transition} takes ${String(DRAWN_TRANSITION_FRAMES[segment.transition])} frames, longer than the segment (${String(frames)} frames)`);
353
+ }
354
+ if (segment.transition !== "stutter") return problems;
355
+ if (frames <= STUTTER_FRAMES) problems.push(`${at}.transition: a stutter shows ${String(STUTTER_FRAMES)} wide frames first, longer than the segment (${String(frames)} frames)`);
356
+ if (segment.motion === "kenburns") problems.push(`${at}.transition: a stutter holds one tight framing; the segment's Ken Burns zoom would move it`);
357
+ if (segment.camera !== undefined && segment.camera.from !== segment.camera.to) problems.push(`${at}.transition: a stutter holds one tight framing; the segment's camera moves`);
358
+ return problems;
359
+ }
360
+
341
361
  /** Caption ranges that are empty, run past the cut, overlap one another or (with `captionBounds`) leave the frame. */
342
362
  function findCaptionRangeProblems(edl: Edl, captionBounds: EdlCaptionBounds | undefined): string[] {
343
363
  const problems: string[] = [];
@@ -23,9 +23,10 @@ export type ClipFit = (typeof CLIP_FITS)[number];
23
23
 
24
24
  /**
25
25
  * How a segment of the cut starts: `cut` (hard), `fade` (a short cross-fade from the previous segment), `zoom` (a
26
- * punch-in that hides a jump cut inside one talking clip) or `whoosh` (a hard cut with the whoosh sound).
26
+ * punch-in that hides a jump cut inside one talking clip), `whoosh` (a hard cut with the whoosh sound), the drawn
27
+ * transitions `whip`, `card` and `paper` (`drawn-transitions.ts`) or `stutter` (five frames wide, then tight).
27
28
  */
28
- export const CUT_TRANSITIONS = ["cut", "fade", "zoom", "whoosh"] as const;
29
+ export const CUT_TRANSITIONS = ["cut", "fade", "zoom", "whoosh", "whip", "card", "paper", "stutter"] as const;
29
30
 
30
31
  export type CutTransition = (typeof CUT_TRANSITIONS)[number];
31
32
 
@@ -0,0 +1,47 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { fileURLToPath } from "node:url";
3
+
4
+ import { readFontTables, readUint16 } from "../og/font-tables.js";
5
+ import { createDraftTextMeasure, type DraftTextMeasure } from "./draft-text-width.js";
6
+
7
+ /**
8
+ * The kit's handwriting: Caveat (SIL Open Font License 1.1, `fonts/LICENSE-Caveat.txt`), a static SemiBold instance
9
+ * subset to Latin with every Polish letter. A note card and an end word are written in it in both paths: the draft
10
+ * copies the file into its fonts folder (libass finds it by `family`), the render copies it to `asset` with its
11
+ * `@font-face`.
12
+ */
13
+ export const HAND_FONT = {
14
+ family: "Caveat",
15
+ file: fileURLToPath(new URL("../../fonts/Caveat-SemiBold-Latin.ttf", import.meta.url)),
16
+ asset: "assets/fonts/hand.ttf",
17
+ } as const;
18
+
19
+ /** Room left round a measured handwritten line: kerning and Caveat's contextual letters are not read. */
20
+ const HAND_WIDTH_SLACK = 1.04;
21
+
22
+ let handMetrics: { measure: DraftTextMeasure; toEm: number } | undefined;
23
+
24
+ /** The hand font's measure in CSS pixels and its libass-size-to-em ratio, read once from the kit's own file. */
25
+ function getHandMetrics(): { measure: DraftTextMeasure; toEm: number } {
26
+ if (handMetrics !== undefined) return handMetrics;
27
+ const font = readFileSync(HAND_FONT.file);
28
+ const tables = readFontTables(font);
29
+ const libass = createDraftTextMeasure(font);
30
+ const head = tables.ok ? tables.value.get("head") : undefined;
31
+ const os2 = tables.ok ? tables.value.get("OS/2") : undefined;
32
+ if (libass === null || head === undefined || os2 === undefined) throw new Error(`the kit's hand font ${HAND_FONT.file} cannot be read`);
33
+ // `createDraftTextMeasure` measures as libass sizes a font (by usWinAscent + usWinDescent); a browser sizes it by the em.
34
+ const toEm = (readUint16(os2, 74) + readUint16(os2, 76)) / readUint16(head, 18);
35
+ handMetrics = { measure: (text, fontSize) => Math.ceil(libass(text, fontSize * toEm) * HAND_WIDTH_SLACK), toEm };
36
+ return handMetrics;
37
+ }
38
+
39
+ /** How wide `text` is written in the hand font at `fontSize` px in the render. */
40
+ export function measureHandText(text: string, fontSize: number): number {
41
+ return getHandMetrics().measure(text, fontSize);
42
+ }
43
+
44
+ /** The draft's `\fs` for the hand font at the render's `fontSize`: libass sizes a font by its ascent and descent, so the letters match the render's. */
45
+ export function getHandFontAssSize(fontSize: number): number {
46
+ return Math.round(fontSize * getHandMetrics().toEm);
47
+ }
@@ -2,7 +2,15 @@ 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 { HAND_FONT } from "./hand-font.js";
5
6
  import {
7
+ DROP_FROM_EM,
8
+ DROP_LETTER_GAP,
9
+ DROP_LETTER_SECONDS,
10
+ NOTE_GROW_FROM_SCALE,
11
+ NOTE_GROW_SECONDS,
12
+ NOTE_TICK_SECONDS,
13
+ getDropLetterTurns,
6
14
  PIN_DROP_SECONDS,
7
15
  PIN_DROP_SHARE,
8
16
  PIN_TITLE_LEAD,
@@ -15,6 +23,7 @@ import {
15
23
  type OverlayMotionOffset,
16
24
  } from "./overlay-motion.js";
17
25
  import {
26
+ NOTE_LINE_HEIGHT,
18
27
  OVERLAY_LINE_HEIGHT,
19
28
  OVERLAY_LIST_LINE_HEIGHT,
20
29
  OVERLAY_PADDING_EM,
@@ -26,7 +35,13 @@ import {
26
35
  getPlaceCardPinSize,
27
36
  getListCardsByItem,
28
37
  getListItemTimes,
38
+ getNoteColors,
39
+ getNotePaperPoints,
40
+ getNoteTextBox,
41
+ getNoteTickPoints,
42
+ getNoteWordsByLine,
29
43
  getTitleContentBox,
44
+ isHandFontNeeded,
30
45
  type OverlayBox,
31
46
  type ResolvedOverlay,
32
47
  } from "./overlays.js";
@@ -133,6 +148,22 @@ function getOverlayCss(colors: OverlayColors, fonts: { heading: string; interfac
133
148
  `.pd .ov-pinrow svg,.pl .ov-line,.sd .ov-sub{opacity:0}`,
134
149
  // An underlined keyword keeps only its drawn bar: the card's own accent edge would be a second line under it.
135
150
  `.ov-keyword.ul .ov-card{border-bottom-color:transparent}`,
151
+ // Dropped letters: each its own box, hidden until it starts falling.
152
+ `.dl{display:inline-block;opacity:0}`,
153
+ // A highlight backdrop: no card, each line on its own tight box that grows with the typed letters.
154
+ `.ov-mark{padding:.04em .22em;border-radius:.14em;-webkit-box-decoration-break:clone;box-decoration-break:clone}`,
155
+ `.ty .hl .ch{display:none}`,
156
+ // A typed line's mark waits for its first letter: an empty mark would show as a bare block of padding.
157
+ `.ty .hl .ov-mark{display:none}`,
158
+ // A note: its paper (an SVG outline with a torn edge and a soft shadow), its lines placed in px, its words hidden until said.
159
+ `.ov-note .nb{position:absolute;inset:0;transform-origin:50% 50%}`,
160
+ `.ov-note .paper{position:absolute;inset:0;overflow:visible;filter:drop-shadow(0 6px 14px rgba(0,0,0,.28))}`,
161
+ `.ov-note .nt{position:absolute;white-space:nowrap;line-height:${NOTE_LINE_HEIGHT}}`,
162
+ `.ov-note .nw{opacity:0}`,
163
+ `.ov-note .tick{position:absolute;inset:0;overflow:visible}`,
164
+ `.ov-strip .nt{font-family:${fonts.heading};font-weight:800;letter-spacing:.02em}`,
165
+ `.ov-hand{font-family:"${HAND_FONT.family}",cursive;font-weight:400}`,
166
+ `.ov-endword{white-space:nowrap;line-height:${OVERLAY_LINE_HEIGHT};text-shadow:0 3px 10px rgba(0,0,0,.45)}`,
136
167
  // The brand's style (after the kinds' own rules, so it wins over them; the search bar stays a pill).
137
168
  ...(style === undefined
138
169
  ? []
@@ -141,6 +172,30 @@ function getOverlayCss(colors: OverlayColors, fonts: { heading: string; interfac
141
172
  `.ov-search{border-radius:999px}`,
142
173
  ...(style.border === "none" ? [] : [`.ov-keyword .ov-card{border-bottom:.12em solid ${colors.accent}}`]),
143
174
  ]),
175
+ // After the brand's style, so a highlight backdrop never draws the card under its marks.
176
+ `.ov .ov-card.hl{background:transparent;box-shadow:none;border:none}`,
177
+ ];
178
+ }
179
+
180
+ /** The hand font's face, when a note card or an end word is drawn: the kit's file, copied to `src` by the render. */
181
+ function getHandFontCss(overlays: readonly ResolvedOverlay[], src: string): string[] {
182
+ return isHandFontNeeded(overlays) ? [`@font-face{font-family:"${HAND_FONT.family}";src:url("${src}") format("truetype");font-weight:400;font-style:normal}`] : [];
183
+ }
184
+
185
+ /** A text whose letters drop in: each letter its own box (spaces stay text, so the line breaks and spaces as before). */
186
+ function toDropHtml(text: string): string {
187
+ return [...text].map((char) => (char.trim() === "" ? " " : `<span class="dl">${escapeHtml(char)}</span>`)).join("");
188
+ }
189
+
190
+ /**
191
+ * The tweens of dropped letters under `target`: each falls from `DROP_FROM_EM` above with its turn and lands eased out
192
+ * (`power2.out`, never past its place), `DROP_LETTER_GAP` after the one before, fading in over its first half.
193
+ */
194
+ function getDropTweens(target: string, text: string, start: number, fontSize: number): string[] {
195
+ const turns = getDropLetterTurns([...text].filter((char) => char.trim() !== "").join(""));
196
+ return [
197
+ `tl.fromTo("${target} .dl", { y: ${r3(-DROP_FROM_EM * fontSize)}, rotation: (i) => ${JSON.stringify(turns)}[i] }, { y: 0, rotation: 0, duration: ${DROP_LETTER_SECONDS}, ease: "power2.out", stagger: ${DROP_LETTER_GAP}, immediateRender: false }, ${r3(start)});`,
198
+ `tl.fromTo("${target} .dl", { opacity: 0 }, { opacity: 1, duration: ${r3(DROP_LETTER_SECONDS / 2)}, ease: "none", stagger: ${DROP_LETTER_GAP}, immediateRender: false }, ${r3(start)});`,
144
199
  ];
145
200
  }
146
201
 
@@ -182,7 +237,8 @@ function toTypedHtml(text: string): string {
182
237
  function getCardStyle(overlay: ResolvedOverlay, colors: OverlayColors, scale = 1): string {
183
238
  if (overlay.kind === "punch_in") return "";
184
239
  const own = overlay.colors;
185
- const parts = [own.card === undefined ? "" : `background:${colors.background}`, own.text === undefined ? "" : `color:${colors.foreground}`];
240
+ const isMarked = (overlay.kind === "hook_title" || overlay.kind === "keyword") && overlay.backdrop === "highlight";
241
+ const parts = [own.card === undefined || isMarked ? "" : `background:${colors.background}`, own.text === undefined ? "" : `color:${colors.foreground}`];
186
242
  if (overlay.cornerRadius !== undefined && overlay.cornerRadius !== null) parts.push(`border-radius:${getCornerRadiusCss(overlay.cornerRadius, scale)}`);
187
243
  if (overlay.kind === "hook_title" || overlay.kind === "place_card") {
188
244
  // The text block sits where the draft draws it: the card's padding is what its fitted box leaves round it.
@@ -254,6 +310,19 @@ function getTypingTweens(id: string, overlay: { start: number; typing: number |
254
310
  return [`tl.to("#${id} .ch", { opacity: 1, display: "inline", duration: 0.01, ease: "none", stagger: ${r3(1 / overlay.typing)} }, ${r3(overlay.start + OVERLAY_TYPING_DELAY)});`];
255
311
  }
256
312
 
313
+ /** Shows each typed line's highlight mark (`#<id>m<line>`, a keyword's `#<id>t`) with the line's first letter. */
314
+ function getMarkRevealTweens(ids: readonly string[], overlay: { start: number; typing: number | null }, lines: readonly string[]): string[] {
315
+ const { typing } = overlay;
316
+ if (typing === null) return [];
317
+ let offset = 0;
318
+ return lines.flatMap((line, index) => {
319
+ const at = overlay.start + OVERLAY_TYPING_DELAY + offset / typing;
320
+ offset += [...line].length;
321
+ const target = ids[index];
322
+ return line === "" || target === undefined ? [] : [`tl.set("#${target}", { display: "inline" }, ${r3(at)});`];
323
+ });
324
+ }
325
+
257
326
  /** Each new kind's own entrance when the overlay names none. */
258
327
  const DEFAULT_ENTRANCES = { hook_title: "slide", search_bar: "fade", place_card: "slide", counter: "fade", date_stamp: "fade" } as const;
259
328
 
@@ -273,14 +342,19 @@ function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lowe
273
342
  const dotStyle = overlay.colors.accent === undefined ? "" : ` style="background:${colors.accent}"`;
274
343
  const isTyped = overlay.typing !== null;
275
344
  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"}`;
276
- const text = isTyped ? toTypedHtml(overlay.text) : escapeHtml(overlay.text);
345
+ const isDrop = overlay.kind === "keyword" && overlay.entrance === "drop";
346
+ const text = isTyped ? toTypedHtml(overlay.text) : isDrop ? toDropHtml(overlay.text) : escapeHtml(overlay.text);
347
+ const isMarked = overlay.kind === "keyword" && overlay.backdrop === "highlight";
277
348
  const wipe = overlay.entrance === "wipe" ? `<i class="ov-wipe" id="${id}w"></i>` : "";
278
349
  const underline = overlay.kind === "keyword" && overlay.underline === true ? `<i class="ov-ul" id="${id}u" style="${getUnderlineStyle(overlay)}"></i>` : "";
279
- const body = `<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>`;
350
+ const mark = isMarked ? ` class="ov-mark" style="background:${colors.background}"` : "";
351
+ const body = `<div class="ov-card${isMarked ? " hl" : ""}"${cardStyle}>${wipe}${overlay.kind === "lower_third" ? `<i class="ov-dot" id="${id}d"${dotStyle}></i>` : ""}<span id="${id}t"${mark}>${text}</span>${underline}</div>`;
280
352
  out.html.push(clipDiv(overlay, id, `ov ov-${overlay.kind.replace("_", "-")}${isCentred ? " center" : side === "right" ? " right" : ""}${isTyped ? " ty" : ""}${underline === "" ? "" : " ul"}`, style, body));
281
353
  if (overlay.entrance !== null) {
282
354
  out.tweens.push(...getMotionTweens(`#${id} .ov-card`, getEntranceMotion(overlay.entrance, overlay.easing ?? "smooth", context.frame), overlay.start));
283
355
  out.tweens.push(...getTypingTweens(id, overlay, [...overlay.text].length));
356
+ if (isMarked) out.tweens.push(...getMarkRevealTweens([`${id}t`], overlay, [[...overlay.text].join("")]));
357
+ if (isDrop) out.tweens.push(...getDropTweens(`#${id}`, overlay.text, overlay.start, overlay.fontSize));
284
358
  } else {
285
359
  // The soft pill's entrance: the card rises from its foot, then its dot and its text settle in, eased out without
286
360
  // overshoot (RV-133 of an adopting app: nothing grows past its size).
@@ -374,8 +448,14 @@ function getCardBody(overlay: CardOverlay, id: string, colors: OverlayColors, lo
374
448
  const typedOrPlain = (text: string) => (overlay.typing === null ? escapeHtml(text) : toTypedHtml(text));
375
449
  if (overlay.kind === "hook_title") {
376
450
  const place = overlay.place === null ? "" : `<div class="ov-place" style="font-size:${overlay.placeFontSize}px">${getPinSvg(colors.accent)}<span>${escapeHtml(overlay.place)}</span></div>`;
377
- const lines = overlay.lines.map((line) => `<div class="ov-line">${typedOrPlain(line)}</div>`).join("");
378
- 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 };
451
+ const isMarked = overlay.backdrop === "highlight";
452
+ const draw = (line: string) => (overlay.entrance === "drop" ? toDropHtml(line) : typedOrPlain(line));
453
+ const lines = overlay.lines.map((line, index) => `<div class="ov-line">${isMarked ? `<span class="ov-mark" id="${id}m${String(index)}" style="background:${colors.background}">${draw(line)}</span>` : draw(line)}</div>`).join("");
454
+ return {
455
+ classes: "ov-hook-title center",
456
+ body: `<div class="ov-card ov-stack${overlay.align === "left" ? " left" : ""}${isMarked ? " hl" : ""}"__STYLE__>__WIPE__${place}${lines}</div>`,
457
+ typed: overlay.lines.join("").length,
458
+ };
379
459
  }
380
460
  if (overlay.kind === "place_card") {
381
461
  const subtitle = overlay.subtitle === null ? "" : `<div class="ov-sub" style="font-size:${overlay.subtitleFontSize}px">${escapeHtml(overlay.subtitle)}</div>`;
@@ -407,6 +487,8 @@ function addCard(overlay: CardOverlay, id: string, context: MarkupContext, out:
407
487
  const entrance = overlay.entrance ?? (overlay.typing !== null ? "type" : DEFAULT_ENTRANCES[overlay.kind]);
408
488
  out.tweens.push(...getEntranceTweens(`#${id} .ov-card`, entrance, overlay.start, { ...(overlay.easing === undefined ? {} : { easing: overlay.easing }), frame: context.frame }));
409
489
  out.tweens.push(...getTypingTweens(id, overlay, typed));
490
+ if (overlay.kind === "hook_title" && overlay.backdrop === "highlight") out.tweens.push(...getMarkRevealTweens(overlay.lines.map((_, index) => `${id}m${String(index)}`), overlay, overlay.lines));
491
+ if (overlay.kind === "hook_title" && overlay.entrance === "drop") out.tweens.push(...getDropTweens(`#${id}`, overlay.lines.join(""), overlay.start, overlay.fontSize));
410
492
  if (overlay.kind === "place_card") out.tweens.push(...getPlaceCardPartTweens(overlay, id, context));
411
493
  if (overlay.kind === "counter") {
412
494
  const count = getCounterSeconds(overlay);
@@ -463,6 +545,55 @@ function toScriptString(value: string): string {
463
545
  return JSON.stringify(value).replace(/</g, "\\u003c");
464
546
  }
465
547
 
548
+ /**
549
+ * A note: its paper (the torn outline of `getNotePaperPoints`) turned by its tilt about its middle; a card's words
550
+ * handwritten and shown each on its said second, the card there (empty) just before; a strip growing in from
551
+ * `NOTE_GROW_FROM_SCALE` (eased out, never past its size) and typing its capitals; the tick drawn after the last word.
552
+ */
553
+ function addNote(overlay: Extract<ResolvedOverlay, { kind: "note" }>, id: string, context: MarkupContext, out: OverlayMarkup): void {
554
+ const { box, fontSize } = overlay;
555
+ const colors = getNoteColors(overlay);
556
+ const isStrip = overlay.noteStyle === "strip";
557
+ const local = (point: { x: number; y: number }) => `${r3(point.x - box.left)},${r3(point.y - box.top)}`;
558
+ const paper = `<svg class="paper" viewBox="0 0 ${box.width} ${box.height}"><polygon points="${getNotePaperPoints(overlay).map(local).join(" ")}" fill="${colors.paper}"/></svg>`;
559
+ const text = getNoteTextBox(overlay);
560
+ const lineHeight = fontSize * NOTE_LINE_HEIGHT;
561
+ const place = (index: number) => `left:${r3(text.left - box.left)}px;top:${r3(text.top - box.top + index * lineHeight)}px`;
562
+ let word = 0;
563
+ const lines = isStrip
564
+ ? overlay.lines.map((line, index) => `<div class="nt" style="${place(index)}">${toTypedHtml(line)}</div>`)
565
+ : getNoteWordsByLine(overlay).map((words, index) => `<div class="nt" style="${place(index)}">${words.map((entry) => `<span class="nw" id="${id}w${word++}">${escapeHtml(entry.text)}</span>`).join(" ")}</div>`);
566
+ const tick = overlay.tickAt === null ? "" : `<svg class="tick" viewBox="0 0 ${box.width} ${box.height}"><polyline id="${id}k" points="${getNoteTickPoints(overlay).map(local).join(" ")}" fill="none" stroke="${colors.tick}" stroke-width="${r3(fontSize * 0.12)}" stroke-linecap="round" stroke-linejoin="round" pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/></svg>`;
567
+ const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;color:${colors.ink};transform:rotate(${r3(-overlay.tilt)}deg)`;
568
+ out.html.push(clipDiv(overlay, id, `ov ov-note ${isStrip ? "ov-strip ty" : "ov-hand"}`, style, `<div class="nb">${paper}${lines.join("")}${tick}</div>`));
569
+ const look = { ...(overlay.easing === undefined ? {} : { easing: overlay.easing }), frame: context.frame };
570
+ if (isStrip && overlay.entrance === null) {
571
+ out.tweens.push(`tl.fromTo("#${id} .nb", { scale: ${NOTE_GROW_FROM_SCALE} }, { scale: 1, duration: ${NOTE_GROW_SECONDS}, ease: "power2.out", immediateRender: false }, ${overlay.start});`);
572
+ } else out.tweens.push(...getEntranceTweens(`#${id} .nb`, overlay.entrance ?? "none", overlay.start, look));
573
+ if (isStrip) out.tweens.push(...getTypingTweens(id, overlay, overlay.lines.join("").length));
574
+ else {
575
+ getNoteWordsByLine(overlay)
576
+ .flat()
577
+ .forEach((entry, index) => out.tweens.push(`tl.fromTo("#${id}w${index}", { opacity: 0 }, { opacity: 1, duration: 0.1, ease: "none", immediateRender: false }, ${entry.at});`));
578
+ }
579
+ if (overlay.tickAt !== null) {
580
+ out.tweens.push(`tl.fromTo("#${id}k", { attr: { "stroke-dashoffset": 1 } }, { attr: { "stroke-dashoffset": 0 }, duration: ${NOTE_TICK_SECONDS}, ease: "power2.out", immediateRender: false }, ${overlay.tickAt});`);
581
+ }
582
+ out.tweens.push(...getExitTweens(`#${id} .nb`, overlay, context.frame, `tl.to("#${id} .nb", { opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`));
583
+ }
584
+
585
+ /** An end word: one big handwritten line, no card, its letters dropping in (or its own entrance), fading out at the end. */
586
+ function addEndWord(overlay: Extract<ResolvedOverlay, { kind: "end_word" }>, id: string, context: MarkupContext, out: OverlayMarkup): void {
587
+ const { box, fontSize } = overlay;
588
+ const entrance = overlay.entrance ?? "drop";
589
+ const text = entrance === "drop" ? toDropHtml(overlay.text) : escapeHtml(overlay.text);
590
+ const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;justify-content:center;align-items:flex-start`;
591
+ out.html.push(clipDiv(overlay, id, "ov ov-end-word", style, `<div class="ov-endword ov-hand nb" style="color:${overlay.colors.text ?? "#ffffff"}">${text}</div>`));
592
+ if (entrance === "drop") out.tweens.push(...getDropTweens(`#${id}`, overlay.text, overlay.start, fontSize));
593
+ else out.tweens.push(...getEntranceTweens(`#${id} .nb`, entrance, overlay.start, { ...(overlay.easing === undefined ? {} : { easing: overlay.easing }), frame: context.frame }));
594
+ out.tweens.push(...getExitTweens(`#${id} .nb`, overlay, context.frame, `tl.to("#${id} .nb", { opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`));
595
+ }
596
+
466
597
  /** An overlay's clip: shown for its own span. */
467
598
  function clipDiv(overlay: ResolvedOverlay, id: string, classes: string, style: string, body: string): string {
468
599
  return `<div id="${id}" class="clip ${classes}" data-start="${overlay.start}" data-duration="${r3(overlay.end - overlay.start)}" style="${style}">${body}</div>`;
@@ -508,17 +639,20 @@ function addMark(overlay: Extract<ResolvedOverlay, { kind: "arrow" | "highlight"
508
639
  */
509
640
  export function getOverlayMarkup(
510
641
  overlays: readonly ResolvedOverlay[],
511
- input: { colors: OverlayColors; headingFont: string; interfaceFont?: string; locale?: string; frame: { width: number; height: number }; style?: BrandStyle },
642
+ input: { colors: OverlayColors; headingFont: string; interfaceFont?: string; locale?: string; frame: { width: number; height: number }; style?: BrandStyle; handFontSrc?: string },
512
643
  ): OverlayMarkup {
513
644
  const drawn = overlays.filter((overlay): overlay is Exclude<ResolvedOverlay, { kind: "punch_in" }> => overlay.kind !== "punch_in");
514
645
  if (drawn.length === 0) return { html: [], css: [], tweens: [] };
515
646
  const context: MarkupContext = { colors: input.colors, scale: input.frame.width / 1080, locale: input.locale ?? "en-US", frame: input.frame };
516
- const out: OverlayMarkup = { html: [], css: getOverlayCss(input.colors, { heading: input.headingFont, interface: input.interfaceFont ?? "inherit" }, input.style, context.scale), tweens: [] };
647
+ const css = [...getHandFontCss(drawn, input.handFontSrc ?? HAND_FONT.asset), ...getOverlayCss(input.colors, { heading: input.headingFont, interface: input.interfaceFont ?? "inherit" }, input.style, context.scale)];
648
+ const out: OverlayMarkup = { html: [], css, tweens: [] };
517
649
  for (const overlay of drawn) {
518
650
  const id = `ov${overlay.index}`;
519
651
  if (overlay.kind === "list") addList(overlay, id, context, out);
520
652
  else if (overlay.kind === "keyword" || overlay.kind === "lower_third") addSideText(overlay, id, context, out);
521
653
  else if (overlay.kind === "arrow" || overlay.kind === "highlight") addMark(overlay, id, context, out);
654
+ else if (overlay.kind === "note") addNote(overlay, id, context, out);
655
+ else if (overlay.kind === "end_word") addEndWord(overlay, id, context, out);
522
656
  else addCard(overlay, id, context, out);
523
657
  }
524
658
  return out;
@@ -62,6 +62,8 @@ function getSmoothEntrance(entrance: Exclude<OverlayEntrance, "none" | "wipe">,
62
62
  switch (entrance) {
63
63
  case "fade":
64
64
  return { from: { ...REST, opacity: 0 }, seconds: 0.4, ease: "power2.out" };
65
+ // A dropped text's card (or highlight) fades in quickly; its letters fall in on their own (`getDropOffsetAt`).
66
+ case "drop":
65
67
  case "type":
66
68
  return { from: { ...REST, opacity: 0 }, seconds: 0.25, ease: "power2.out" };
67
69
  case "slide":
@@ -108,6 +110,7 @@ export function getExitMotion(input: { exit: OverlayExit; entrance: OverlayEntra
108
110
  return { kind: "own" };
109
111
  case "fade":
110
112
  case "type":
113
+ case "drop":
111
114
  return tween(fade);
112
115
  case "slide":
113
116
  return tween(slide);
@@ -155,3 +158,49 @@ export function getListItemStarts(input: { start: number; end: number; count: nu
155
158
  const gap = Math.min(0.6, Math.max(0.25, ((end - start) * 0.4) / count));
156
159
  return Array.from({ length: count }, (_item, index) => r3(Math.min(latest, start + 0.2 + index * gap)));
157
160
  }
161
+
162
+ /** A dropped letter falls from this share of its line's type size above its place. */
163
+ export const DROP_FROM_EM = 0.3;
164
+ /** The seconds one letter falls, and the seconds between two letters' starts (2 frames at 30 fps). */
165
+ export const DROP_LETTER_SECONDS = 0.3;
166
+ export const DROP_LETTER_GAP = 0.067;
167
+ /** The most a letter is turned when it starts falling, in degrees; it turns back to straight as it lands. */
168
+ export const DROP_MAX_TURN = 8;
169
+
170
+ /**
171
+ * The film seconds each letter of a dropped text starts falling at (a space takes no turn of its own): the first at
172
+ * `start`, each next one `DROP_LETTER_GAP` later.
173
+ */
174
+ export function getDropLetterTimes(start: number, text: string): number[] {
175
+ let letter = 0;
176
+ return [...text].map((char) => {
177
+ const at = r3(start + letter * DROP_LETTER_GAP);
178
+ if (char.trim() !== "") letter += 1;
179
+ return at;
180
+ });
181
+ }
182
+
183
+ /** The turn each letter starts with, in degrees: alternating sides, between half and all of `DROP_MAX_TURN`. */
184
+ export function getDropLetterTurns(text: string): number[] {
185
+ return [...text].map((_char, index) => r3((index % 2 === 0 ? -1 : 1) * DROP_MAX_TURN * (0.5 + 0.5 * (((index * 7) % 5) / 4))));
186
+ }
187
+
188
+ /**
189
+ * A dropped letter `seconds` after it starts falling: px above its place (negative y, up), its turn and its opacity.
190
+ * The fall eases out along `power2.out`, so the letter slows into its place and never passes it: y stays at or above 0
191
+ * (screen y grows down), and the turn shrinks to 0 without changing sides.
192
+ */
193
+ export function getDropOffsetAt(seconds: number, input: { fontSize: number; turn: number }): { y: number; turn: number; opacity: number } {
194
+ const progress = Math.min(1, Math.max(0, seconds / DROP_LETTER_SECONDS));
195
+ const eased = OVERLAY_EASES["power2.out"](progress);
196
+ return { y: r3(-DROP_FROM_EM * input.fontSize * (1 - eased)), turn: r3(input.turn * (1 - eased)), opacity: r3(Math.min(1, progress * 2)) };
197
+ }
198
+
199
+ /** A note strip grows from this share of its size over these seconds (8 frames at 30 fps), eased out. */
200
+ export const NOTE_GROW_FROM_SCALE = 0.3;
201
+ export const NOTE_GROW_SECONDS = 0.267;
202
+ /** A note's tick is drawn over these seconds, this long after its last word. */
203
+ export const NOTE_TICK_SECONDS = 0.3;
204
+ export const NOTE_TICK_DELAY = 0.15;
205
+ /** A note card is there, empty, this long before its first word (one frame at 30 fps). */
206
+ export const NOTE_FIRST_WORD_LEAD = 0.034;