@softure-ai/marketing-kit 0.42.0 → 0.44.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 (38) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +11 -0
  3. package/dist/footage/draft-overlays.d.ts +27 -1
  4. package/dist/footage/draft-overlays.d.ts.map +1 -1
  5. package/dist/footage/draft-overlays.js +169 -37
  6. package/dist/footage/draft-overlays.js.map +1 -1
  7. package/dist/footage/draft-text-width.d.ts +13 -0
  8. package/dist/footage/draft-text-width.d.ts.map +1 -1
  9. package/dist/footage/draft-text-width.js +12 -1
  10. package/dist/footage/draft-text-width.js.map +1 -1
  11. package/dist/footage/draft.d.ts +7 -1
  12. package/dist/footage/draft.d.ts.map +1 -1
  13. package/dist/footage/draft.js +9 -1
  14. package/dist/footage/draft.js.map +1 -1
  15. package/dist/footage/overlay-html.d.ts +13 -4
  16. package/dist/footage/overlay-html.d.ts.map +1 -1
  17. package/dist/footage/overlay-html.js +15 -9
  18. package/dist/footage/overlay-html.js.map +1 -1
  19. package/dist/footage/overlay-motion.d.ts +31 -4
  20. package/dist/footage/overlay-motion.d.ts.map +1 -1
  21. package/dist/footage/overlay-motion.js +53 -5
  22. package/dist/footage/overlay-motion.js.map +1 -1
  23. package/dist/footage/overlays.d.ts +64 -2
  24. package/dist/footage/overlays.d.ts.map +1 -1
  25. package/dist/footage/overlays.js +112 -4
  26. package/dist/footage/overlays.js.map +1 -1
  27. package/dist/index.d.ts +4 -4
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +4 -4
  30. package/dist/index.js.map +1 -1
  31. package/package.json +1 -1
  32. package/src/footage/draft-overlays.ts +202 -36
  33. package/src/footage/draft-text-width.ts +22 -1
  34. package/src/footage/draft.ts +11 -2
  35. package/src/footage/overlay-html.ts +20 -8
  36. package/src/footage/overlay-motion.ts +61 -5
  37. package/src/footage/overlays.ts +132 -4
  38. package/src/index.ts +17 -0
@@ -6,16 +6,54 @@ import type { OverlayEasing, OverlayEntrance, OverlayExit } from "./overlay-sche
6
6
  * start to its rest and never past it, so no element grows past 100 % (`getEntranceScaleAt`). No bounce, no elastic.
7
7
  */
8
8
 
9
- /** A GSAP ease name and its curve: each one rises from 0 to 1 and never passes 1. */
9
+ /** GSAP 3's `expo.in`, of which `expo.out` is the mirror. */
10
+ const expoIn = (t: number): number => 2 ** (10 * (t - 1)) * t + t ** 6 * (1 - t);
11
+
12
+ /**
13
+ * A GSAP ease name and its curve, exactly as GSAP 3 computes it (the render's tweens name the ease, the draft computes
14
+ * its steps from the curve, so the two stand at the same place in every frame): each one rises from 0 to 1 and never
15
+ * passes 1. GSAP's `powerN` is a polynomial of degree N + 1 (`power1` is the quadratic), so `power2.out` is cubic.
16
+ */
10
17
  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,
18
+ "power2.out": (t: number) => 1 - (1 - t) ** 3,
19
+ "power3.out": (t: number) => 1 - (1 - t) ** 4,
20
+ "expo.out": (t: number) => 1 - expoIn(1 - t),
21
+ "power2.in": (t: number) => t ** 3,
15
22
  } as const;
16
23
 
17
24
  export type OverlayEase = keyof typeof OVERLAY_EASES;
18
25
 
26
+ /** A step of a value the draft changes every frame: shown from `from` to `to` (film seconds). */
27
+ export interface FrameStep {
28
+ from: number;
29
+ to: number;
30
+ text: string;
31
+ }
32
+
33
+ /**
34
+ * A value that changes every frame, as the draft's steps: one step per film frame from `start` to `end`, showing
35
+ * `valueAt` that frame's second, each spanning half a frame either side of it (so rounding a step's edges to the
36
+ * centisecond never moves a frame into its neighbour's step); neighbours that show the same text are joined. A span
37
+ * with no frame in it shows `valueAt(start)`.
38
+ */
39
+ export function getFrameSteps(input: { start: number; end: number; fps: number; valueAt: (seconds: number) => string }): FrameStep[] {
40
+ const { start, end, fps } = input;
41
+ if (!(end > start)) return [];
42
+ const first = Math.ceil(start * fps - 1e-6);
43
+ const last = Math.ceil(end * fps - 1e-6) - 1;
44
+ if (last < first) return [{ from: start, to: end, text: input.valueAt(start) }];
45
+ const steps: FrameStep[] = [];
46
+ for (let frame = first; frame <= last; frame++) {
47
+ const from = frame === first ? start : (frame - 0.5) / fps;
48
+ const to = frame === last ? end : (frame + 0.5) / fps;
49
+ const text = input.valueAt(frame / fps);
50
+ const previous = steps.at(-1);
51
+ if (previous?.text === text) previous.to = to;
52
+ else steps.push({ from, to, text });
53
+ }
54
+ return steps;
55
+ }
56
+
19
57
  /** How far from its rest an overlay starts or ends: its opacity, its scale, px below its place, px of blur. */
20
58
  export interface OverlayMotionOffset {
21
59
  opacity: number;
@@ -54,6 +92,24 @@ export const OVERLAY_EXIT_SECONDS = 0.3;
54
92
  /** How much quicker a snappy curve runs. */
55
93
  const SNAPPY_SPEED = 0.7;
56
94
 
95
+ /** When a typed overlay starts typing, after its card has faded in, in seconds from its start. */
96
+ export const OVERLAY_TYPING_DELAY = 0.3;
97
+
98
+ /** The seconds between two typed characters at `speed` characters a second: the render's stagger, to the millisecond. */
99
+ export function getTypingStep(speed: number): number {
100
+ return r3(1 / speed);
101
+ }
102
+
103
+ /**
104
+ * The film seconds each character of a typed text appears at, from `OVERLAY_TYPING_DELAY` after `start`, one
105
+ * `getTypingStep` apart (the render's stagger). `firstIndex` characters were typed before it (a later line of the
106
+ * same overlay), so its first character comes that many steps later.
107
+ */
108
+ export function getTypingTimes(start: number, text: string, speed: number, firstIndex = 0): number[] {
109
+ const step = getTypingStep(speed);
110
+ return [...text].map((_char, index) => r3(start + OVERLAY_TYPING_DELAY + (firstIndex + index) * step));
111
+ }
112
+
57
113
  const REST: OverlayMotionOffset = { opacity: 1, scale: 1, y: 0, blur: 0 };
58
114
  const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
59
115
 
@@ -24,7 +24,7 @@ import {
24
24
  import { isCameraMoving, isSameCamera } from "./camera.js";
25
25
  import { getSegmentZoomEases } from "./compose.js";
26
26
  import { normalizeWord } from "./words.js";
27
- import { NOTE_FIRST_WORD_LEAD, NOTE_TICK_DELAY, getListItemStarts } from "./overlay-motion.js";
27
+ import { NOTE_FIRST_WORD_LEAD, NOTE_TICK_DELAY, OVERLAY_TYPING_DELAY, getListItemStarts, getTypingStep } from "./overlay-motion.js";
28
28
  import { STYLE_PADDING_SCALES, type BrandStyle, type CornerRadius } from "./brand-style.js";
29
29
  import { measureHandText } from "./hand-font.js";
30
30
 
@@ -436,9 +436,20 @@ export function getSideTextLines(overlay: SideTextOverlay): string[] {
436
436
  * The card a drawn overlay shows, in px of the frame, or null for a `punch_in`. A keyword, a lower third and a list
437
437
  * are placed in the whole width they may take (`box`); their card fits their widest line (by `estimateTextWidth`)
438
438
  * plus its padding, on its side, as tall as the box. Every other kind's card is its box (`getOverlayBounds`). The
439
- * draft draws this card, so a report of where an overlay sits (does it cover a face?) reads the same box.
439
+ * draft draws this card, so a report of where an overlay sits (does it cover a face?) reads the same box. With the
440
+ * brand fonts' `measure` (`createOverlayTextMeasure`), a keyword's, a lower third's and a counter's card is the one the
441
+ * render lays out (`getSideTextLayout`, `getCounterCard`, the counter at its final value), as the draft then draws it;
442
+ * a highlighted keyword or hook title (no card of its own) answers where its marks show.
440
443
  */
441
- export function getDrawnOverlayCard(overlay: ResolvedOverlay): OverlayBox | null {
444
+ export function getDrawnOverlayCard(overlay: ResolvedOverlay, measure?: OverlayTextMeasure): OverlayBox | null {
445
+ if (measure !== undefined && overlay.kind === "keyword" && overlay.backdrop === "highlight") {
446
+ const layout = getSideTextLayout(overlay, measure);
447
+ return getKeywordMarkBlock(overlay, layout, layout.lines, measure);
448
+ }
449
+ if (measure !== undefined && (overlay.kind === "keyword" || overlay.kind === "lower_third")) return getSideTextLayout(overlay, measure).card;
450
+ if (measure !== undefined && overlay.kind === "hook_title" && overlay.backdrop === "highlight") return getMarkedTitleBounds(overlay, measure) ?? overlay.box;
451
+ // The counter's widest number: its final value, grouped as en-US groups it (as `measureCounter` sizes its box).
452
+ if (measure !== undefined && overlay.kind === "counter") return getCounterCard(overlay, formatOverlayNumber(overlay.value, overlay.decimals, "en-US"), measure);
442
453
  if (overlay.kind !== "keyword" && overlay.kind !== "lower_third" && overlay.kind !== "list") return getOverlayBounds(overlay);
443
454
  if (overlay.kind === "list" && overlay.chips !== undefined) return getBoxesUnion(overlay.chips);
444
455
  return getSideTextCard(overlay, getSideTextLines(overlay), overlay.box.height);
@@ -455,6 +466,123 @@ function getSideTextCard(overlay: SideTextOverlay, lines: readonly string[], hei
455
466
  return { left, top: box.top, width, height };
456
467
  }
457
468
 
469
+ /**
470
+ * A line's width in CSS px in the brand font of `role` at `cssPx`, its letters spaced `spacingEm` (the render's
471
+ * `letter-spacing`): the render's own measure, read from the font files (`createOverlayTextMeasure`).
472
+ */
473
+ export type OverlayTextMeasure = (role: OverlayFontRole, text: string, cssPx: number, spacingEm: number) => number;
474
+
475
+ /** A lower third's accent dot and the gap after it, in ems of its font size (the render's `.ov-dot` and card gap). */
476
+ export const OVERLAY_DOT_EM = { size: 0.36, gap: 0.45 } as const;
477
+ /** A keyword card's accent edge under its text, in ems (the render's `border-bottom`). */
478
+ export const KEYWORD_EDGE_EM = 0.12;
479
+ /** The gap between a counter's number and its unit, in ems of the number's size. */
480
+ export const COUNTER_UNIT_GAP_EM = 0.3;
481
+ /** A highlight mark's padding round its text and its corner, in ems (the render's `.ov-mark`). */
482
+ export const MARK_PADDING_EM = { x: 0.22, y: 0.04 } as const;
483
+ export const MARK_RADIUS_EM = 0.14;
484
+
485
+ /** A keyword's or a lower third's card as the render lays it out: its text's lines, the card, where the text starts and its dot. */
486
+ export interface SideTextLayout {
487
+ /** The text broken as the render's card breaks it, one entry a line. */
488
+ lines: string[];
489
+ card: OverlayBox;
490
+ /** Where the first letter of every line starts (a centred keyword: the card's middle). */
491
+ textX: number;
492
+ /** The top of the first line (inside a highlight mark's padding). */
493
+ textTop: number;
494
+ /** A lower third's accent dot; null for a keyword. */
495
+ dot: { centre: OverlayPoint; radius: number } | null;
496
+ }
497
+
498
+ /** `words` broken greedily into lines no wider than `width` by `measureLine`, as a browser breaks a line (a word wider than a line stands alone). */
499
+ function breakLines(words: readonly string[], width: number, measureLine: (line: string) => number): string[] {
500
+ const lines: string[] = [];
501
+ for (const word of words) {
502
+ const last = lines[lines.length - 1];
503
+ if (last !== undefined && measureLine(`${last} ${word}`) <= width) lines[lines.length - 1] = `${last} ${word}`;
504
+ else lines.push(word);
505
+ }
506
+ return lines;
507
+ }
508
+
509
+ /**
510
+ * A keyword's or a lower third's card as the render lays it out (`.ov-card` in its box): its text broken inside the
511
+ * box less the padding (and a highlight mark's padding, a lower third's dot), the card as wide as its widest line (the
512
+ * whole box once it wraps), as tall as its lines plus padding and a keyword's accent edge; a keyword's card hangs from
513
+ * the box's top, a lower third's stands on its foot. `measure` reads the brand font, as the browser does.
514
+ */
515
+ export function getSideTextLayout(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" }>, measure: OverlayTextMeasure): SideTextLayout {
516
+ const { box, fontSize, side } = overlay;
517
+ const pad = getOverlayPadding(overlay);
518
+ const role = OVERLAY_FONT_ROLES[overlay.kind];
519
+ const isMarked = overlay.kind === "keyword" && overlay.backdrop === "highlight";
520
+ const markPad = isMarked ? fontSize * MARK_PADDING_EM.x : 0;
521
+ const dotRoom = overlay.kind === "lower_third" ? fontSize * (OVERLAY_DOT_EM.size + OVERLAY_DOT_EM.gap) : 0;
522
+ const measureLine = (line: string): number => measure(role, line, fontSize, OVERLAY_LETTER_SPACING_EM.card);
523
+ const words = overlay.text.replace(/\s+/g, " ").trim().split(" ");
524
+ const lines = breakLines(words, box.width - 2 * pad.x - dotRoom - 2 * markPad, measureLine);
525
+ const textWidth = Math.max(0, ...lines.map(measureLine)) + 2 * markPad + dotRoom;
526
+ const width = lines.length > 1 ? box.width : Math.min(box.width, Math.ceil(textWidth + 2 * pad.x));
527
+ // A highlighted keyword's card draws no border; an underlined one keeps its edge's room, transparent.
528
+ const edge = overlay.kind === "keyword" && !isMarked ? Math.round(fontSize * KEYWORD_EDGE_EM) : 0;
529
+ // A highlighted keyword's text is one block (a flex item) on its mark, padded on every side.
530
+ const markPadY = isMarked ? fontSize * MARK_PADDING_EM.y : 0;
531
+ const height = Math.ceil(lines.length * fontSize * OVERLAY_LINE_HEIGHT + 2 * markPadY + 2 * pad.y + edge);
532
+ const isCentred = overlay.kind === "keyword" && overlay.isCentred === true;
533
+ const left = isCentred ? box.left + Math.round((box.width - width) / 2) : side === "right" ? box.left + box.width - width : box.left;
534
+ const top = overlay.kind === "lower_third" ? box.top + box.height - height : box.top;
535
+ const card = { left, top, width, height };
536
+ const textTop = top + pad.y + markPadY;
537
+ const dot =
538
+ overlay.kind === "lower_third" ? { centre: { x: left + pad.x + (fontSize * OVERLAY_DOT_EM.size) / 2, y: top + height / 2 }, radius: (fontSize * OVERLAY_DOT_EM.size) / 2 } : null;
539
+ return { lines, card, textX: isCentred ? left + width / 2 : left + pad.x + dotRoom + markPad, textTop, dot };
540
+ }
541
+
542
+ /**
543
+ * A highlighted keyword's mark as the render draws it (`.ov-mark` is a flex item of the card, so one block): round
544
+ * `lines` (the whole text's, or the letters typed so far on theirs), as wide as the widest line, or all the card's
545
+ * room once the text wraps, as tall as the lines, padded by `MARK_PADDING_EM`.
546
+ */
547
+ export function getKeywordMarkBlock(overlay: Extract<ResolvedOverlay, { kind: "keyword" }>, layout: SideTextLayout, lines: readonly string[], measure: OverlayTextMeasure): OverlayBox {
548
+ const { fontSize } = overlay;
549
+ const pad = { x: fontSize * MARK_PADDING_EM.x, y: fontSize * MARK_PADDING_EM.y };
550
+ const measureLine = (line: string): number => measure(OVERLAY_FONT_ROLES.keyword, line, fontSize, OVERLAY_LETTER_SPACING_EM.card);
551
+ const width = lines.length > 1 ? layout.card.width - 2 * getOverlayPadding(overlay).x : Math.max(0, ...lines.map(measureLine)) + 2 * pad.x;
552
+ const height = lines.length * fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y;
553
+ const left = overlay.isCentred === true ? layout.textX - width / 2 : layout.textX - pad.x;
554
+ return { left, top: layout.textTop - pad.y, width, height };
555
+ }
556
+
557
+ /**
558
+ * Where a highlighted hook title shows (its card is transparent): round its lines' marks, as wide as the widest line
559
+ * and its marks' padding, as tall as its lines; null when it names a place (its row is not a mark).
560
+ */
561
+ function getMarkedTitleBounds(overlay: Extract<ResolvedOverlay, { kind: "hook_title" }>, measure: OverlayTextMeasure): OverlayBox | null {
562
+ if (overlay.place !== null) return null;
563
+ const { fontSize } = overlay;
564
+ const content = getTitleContentBox(overlay);
565
+ const padX = fontSize * MARK_PADDING_EM.x;
566
+ const width = Math.max(0, ...overlay.lines.map((line) => measure("heading", line, fontSize, OVERLAY_LETTER_SPACING_EM.hookTitle))) + 2 * padX;
567
+ const left = overlay.align === "left" ? content.left : content.left + content.width / 2 - width / 2;
568
+ return { left, top: content.top, width, height: content.height };
569
+ }
570
+
571
+ /**
572
+ * A counter's card as the render lays it out while it shows `text` (its number, as formatted): as wide as the number,
573
+ * its unit and the gap between, plus padding; one line tall; in the middle of its box, from its top.
574
+ */
575
+ export function getCounterCard(overlay: Extract<ResolvedOverlay, { kind: "counter" }>, text: string, measure: OverlayTextMeasure): OverlayBox {
576
+ const { box, fontSize, unit, unitFontSize } = overlay;
577
+ const pad = getOverlayPadding(overlay);
578
+ const role = OVERLAY_FONT_ROLES.counter;
579
+ // The card's letter spacing is set in ems of the card's size and inherited as px by the unit.
580
+ const unitWidth = unit === null ? 0 : fontSize * COUNTER_UNIT_GAP_EM + measure(role, unit, unitFontSize, (OVERLAY_LETTER_SPACING_EM.card * fontSize) / unitFontSize);
581
+ const width = Math.ceil(measure(role, text, fontSize, OVERLAY_LETTER_SPACING_EM.card) + unitWidth + 2 * pad.x);
582
+ const height = Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y);
583
+ return { left: box.left + Math.round((box.width - width) / 2), top: box.top, width, height };
584
+ }
585
+
458
586
  /** The smallest box round every box of a non-empty list. */
459
587
  function getBoxesUnion(boxes: readonly OverlayBox[]): OverlayBox {
460
588
  const left = Math.min(...boxes.map((box) => box.left));
@@ -880,7 +1008,7 @@ export function timeNote(note: Extract<ResolvedOverlay, { kind: "note" }>, words
880
1008
  const latest = r3(Math.max(first, note.end - 0.6));
881
1009
  if (note.noteStyle === "strip") {
882
1010
  const typed = note.typing ?? DEFAULT_OVERLAY_TYPING_SPEED;
883
- const lastLetter = note.start + 0.3 + ([...note.lines.join("")].length - 1) / typed;
1011
+ const lastLetter = note.start + OVERLAY_TYPING_DELAY + ([...note.lines.join("")].length - 1) * getTypingStep(typed);
884
1012
  return { wordTimes: null, tickAt: tickAfter(lastLetter) };
885
1013
  }
886
1014
  const said = words.filter((word) => word.start >= note.start - 0.05 && word.start < note.end);
package/src/index.ts CHANGED
@@ -158,6 +158,7 @@ export {
158
158
  type StyleShadow,
159
159
  } from "./footage/brand-style.js";
160
160
  export {
161
+ DEFAULT_CONTENT_AREA,
161
162
  createDraftFont,
162
163
  createDraftTextMeasure,
163
164
  getSpacingWidth,
@@ -190,7 +191,17 @@ export {
190
191
  getChipCoveredTimes,
191
192
  getChipParts,
192
193
  getChipTickPoints,
194
+ getCounterCard,
193
195
  getDrawnOverlayCard,
196
+ getKeywordMarkBlock,
197
+ getSideTextLayout,
198
+ COUNTER_UNIT_GAP_EM,
199
+ KEYWORD_EDGE_EM,
200
+ MARK_PADDING_EM,
201
+ MARK_RADIUS_EM,
202
+ OVERLAY_DOT_EM,
203
+ type OverlayTextMeasure,
204
+ type SideTextLayout,
194
205
  getListCardsByItem,
195
206
  getListItemTimes,
196
207
  getListStops,
@@ -219,6 +230,7 @@ export {
219
230
  } from "./footage/overlays.js";
220
231
  export {
221
232
  OVERLAY_EASES,
233
+ OVERLAY_TYPING_DELAY,
222
234
  POP_FROM_SCALE,
223
235
  RISE_FROM_HEIGHT,
224
236
  getEntranceMotion,
@@ -227,6 +239,10 @@ export {
227
239
  getListItemStarts,
228
240
  getDropLetterTimes,
229
241
  getDropOffsetAt,
242
+ getFrameSteps,
243
+ getTypingStep,
244
+ getTypingTimes,
245
+ type FrameStep,
230
246
  type OverlayEase,
231
247
  type OverlayEntranceMotion,
232
248
  type OverlayExitMotion,
@@ -702,6 +718,7 @@ export {
702
718
  FOOTAGE_DRAFT_FONT,
703
719
  FOOTAGE_DRAFT_WIDTH,
704
720
  loadFootageDraftFonts,
721
+ createOverlayTextMeasure,
705
722
  type FootageDraftFonts,
706
723
  buildFootageDraftArgs,
707
724
  buildFootageDraftCaptions,