Open source CapCut alternative.
TypeScript
feat(site): a word effect engine with configs [rebuild]
David Le314dcd9a0054
diff --git a/site/packages/effects-kit/src/render.ts b/site/packages/effects-kit/src/render.tsindex 17b746de..83d64c19 100644--- a/site/packages/effects-kit/src/render.ts+++ b/site/packages/effects-kit/src/render.ts@@ -34,13 +34,14 @@ import {type TextShadowSpec,} from "./types";import {- applyWordAccent,- highlightSwell,+ applyWordDraw,overlayWords,+ REST_WORD,WORD_ACCENT_DEFAULT,- wordAccentIndex,+ WORD_BASELINE_DROP,+ wordReach,+ wordSampleWindows,wordSwell,- wordWindows,} from "./words";// Text metrics shared by DOM preview and canvas burn-in.@@ -382,43 +383,71 @@ async function paintText(const cx = overlay.x * width;const cy = overlay.y * frame.height;- // Karaoke lays its words out first. The emphasized word may be swollen, and- // it takes that width in the line — its neighbours move out of its way — so- // the plate, the alignment and the draw all have to read one layout.- const swell = overlay.highlightWord === undefined ? 1 : highlightSwell(overlay);- const bigFont = swell !== 1 ? textCssFont(overlay, fpx * swell, env) : cssFont;- if (swell !== 1) await ensureFontLoaded(bigFont, overlay.text);- /** Draw and measure at the swollen word's size, or back at the line's.- * Tracking is em of the size in play, so a swollen word is spaced like the- * words beside it. */- const setSize = (big: boolean) => {- ctx.font = big ? bigFont : cssFont;- if ("letterSpacing" in ctx)- ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * (big ? fpx * swell : fpx)}px`;+ // A word effect lays its words out first. A word may draw at its own size,+ // and it takes that width in the line — its neighbours move out of its way —+ // so the plate, the alignment and the draw all have to read one layout.+ const draws = overlay.wordDraw?.length ? overlay.wordDraw : null;+ const fonts = new Map<number, string>();+ const sizeKey = (mult: number) => Math.round(mult * 1000) / 1000;+ const fontFor = (mult: number) => {+ const key = sizeKey(mult);+ let f = fonts.get(key);+ if (!f) {+ f = key === 1 ? cssFont : textCssFont(overlay, fpx * key, env);+ fonts.set(key, f);+ }+ return f;+ };+ // Every size in play has to be resident before measureText, or the layout is+ // measured against a fallback face and the burn-in drifts off the preview.+ if (draws) {+ const sizes = new Set(draws.flatMap((d) => [sizeKey(d.scale), sizeKey(d.layoutScale)]));+ for (const key of sizes) {+ if (key !== 1) await ensureFontLoaded(fontFor(key), overlay.text);+ }+ }+ /** Draw and measure at a word's own size, or back at the line's. Tracking is+ * em of the size in play, so a resized word is spaced like the words beside+ * it. */+ // The size the next draw happens at. A font string carries the weight in+ // front of it, so reading the size back out of `ctx.font` returns the weight+ // on any bold face; this is the size, tracked where it is set.+ let drawSize = fpx;+ const setSize = (mult: number) => {+ ctx.font = fontFor(mult);+ drawSize = fpx * sizeKey(mult);+ if ("letterSpacing" in ctx) ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * drawSize}px`;};- const runs =- overlay.highlightWord === undefined- ? null- : (() => {- const spaceW = ctx.measureText(" ").width;- let k = 0;- return lines.map((line) => {- const words = line.split(" ").filter(Boolean);- const widths = words.map((w) => {- const big = k++ === overlay.highlightWord && swell !== 1;- if (big) setSize(true);- const ww = ctx.measureText(w).width;- if (big) setSize(false);- return ww;- });- return {- words,- widths,- spaceW,- lineW: widths.reduce((a, b) => a + b, 0) + spaceW * Math.max(0, words.length - 1),- };- });- })();+ const runs = !draws+ ? null+ : (() => {+ const spaceW = ctx.measureText(" ").width;+ let k = 0;+ const at = (w: string, mult: number) => {+ if (mult === 1) return ctx.measureText(w).width;+ setSize(mult);+ const ww = ctx.measureText(w).width;+ setSize(1);+ return ww;+ };+ return lines.map((line) => {+ const words = line.split(" ").filter(Boolean);+ // Two widths per word: the room it takes in the line, and the width+ // it actually draws at. They differ only while a word is growing+ // into its place, and it draws centered in the room it will fill.+ const from = k;+ k += words.length;+ const widths = words.map((w, j) => at(w, sizeKey(draws[from + j]?.layoutScale ?? 1)));+ const drawn = words.map((w, j) => at(w, sizeKey(draws[from + j]?.scale ?? 1)));+ return {+ words,+ widths,+ drawn,+ spaceW,+ lineW: widths.reduce((a, b) => a + b, 0) + spaceW * Math.max(0, words.length - 1),+ };+ });+ })();const widthsOf = runs ? runs.map((r) => r.lineW) : lines.map((l) => ctx.measureText(l).width);const maxW = Math.max(...widthsOf, 1);@@ -447,10 +476,9 @@ async function paintText(const drawText = (text: string, x: number, y: number, fill: string = overlay.color) => {if (overlay.stroke && strokeW > 0) {ctx.lineJoin = "round";- // In em of whatever size is set, so a swollen word wears the same+ // In em of whatever size is set, so a resized word wears the same// outline weight as the words beside it.- const em = parseFloat(ctx.font) || fpx;- ctx.lineWidth = (strokeW / fpx) * em * 2; // half of a centered stroke shows behind the fill+ ctx.lineWidth = (strokeW / fpx) * drawSize * 2; // half of a centered stroke shows behind the fillctx.strokeStyle = overlay.stroke.color;ctx.strokeText(text, x, y);}@@ -503,68 +531,100 @@ async function paintText(return;}- // Karaoke: draw word by word so the spoken word takes its accent treatment —- // color, underline, a box, or a swell; the word index counts across all- // lines. The words sit in the layout measured above, so a swollen one has- // already pushed its neighbours aside and they close back up as the- // emphasis moves on.- if (!runs) {+ // A word effect draws word by word, each word at the color, opacity and pose+ // the engine resolved for it; the word index counts across all lines. The+ // words sit in the layout measured above, so one drawn bigger has already+ // pushed its neighbours aside and they close back up as it shrinks.+ if (!runs || !draws) {lines.forEach((line, i) => drawText(line, lineX(i), cy - totalH / 2 + lineH * (i + 0.5)));return;}- // A word drawn at another size shares the baseline with the words beside- // it, so where that baseline sits has to be read off the face: the middle- // this painter draws from is half the type's own height above it.- const fm = ctx.measureText("Hg");- const asc = fm.fontBoundingBoxAscent ?? fpx * 0.8;- const desc = fm.fontBoundingBoxDescent ?? fpx * 0.2;- const midOf = (size: number) => ((asc - desc) / 2) * (size / fpx);+ // A word drawn at another size shares the baseline with the words beside it,+ // so where that baseline sits under the middle this painter draws from has to+ // be read off the face. Measuring the same string against both alignments+ // gives the gap exactly, in whatever engine is drawing: the ascent is+ // reported from the alignment point, so the difference between the two is the+ // distance between them.+ const ascentAt = (baseline: CanvasTextBaseline) => {+ ctx.textBaseline = baseline;+ return ctx.measureText("Hg").actualBoundingBoxAscent;+ };+ const alphabetic = ascentAt("alphabetic");+ const middle = ascentAt("middle");+ const drop =+ Number.isFinite(alphabetic) && Number.isFinite(middle) && alphabetic > middle+ ? alphabetic - middle+ : fpx * WORD_BASELINE_DROP;+ ctx.textBaseline = "middle";+ const alpha0 = ctx.globalAlpha;let k = 0;ctx.textAlign = "left";runs.forEach((run, i) => {const y = cy - totalH / 2 + lineH * (i + 0.5);let x = cx - run.lineW / 2;run.words.forEach((w, wi) => {- const active = k === overlay.highlightWord;- const big = active && swell !== 1;- // A word at the line's own size draws from the middle, exactly as it- // always has; a swollen one hangs off the shared baseline instead, and- // its own middle follows from there.- const size = big ? fpx * swell : fpx;- const drawY = big ? y + midOf(fpx) : y;- const mid = big ? y + midOf(fpx) - midOf(size) : y;- if (big) {- setSize(true);- ctx.textBaseline = "alphabetic";- }- if (active && overlay.highlightMode === "box") {- // Accent box behind the word, contrast text on top — drawn with the- // shadow off so the box and its word stay crisp.- const pad = 0.12 * size;- const prevShadow = ctx.shadowColor;- ctx.shadowColor = "transparent";- ctx.fillStyle = overlay.highlightColor ?? WORD_ACCENT_DEFAULT;- ctx.beginPath();- ctx.roundRect(x - pad, mid - size * 0.5 - pad, run.widths[wi] + pad * 2, size + pad * 2, 0.18 * size);- ctx.fill();- drawText(w, x, drawY, overlay.highlightText ?? "#111114");- ctx.shadowColor = prevShadow;- } else if (active) {- drawText(w, x, drawY, overlay.highlightColor ?? WORD_ACCENT_DEFAULT);- if (overlay.highlightMode === "underline") {- ctx.fillRect(x, mid + size * 0.42, run.widths[wi], Math.max(2 * scale, size * 0.07));+ const d = draws[k] ?? { ...REST_WORD, color: overlay.color };+ const mult = sizeKey(d.scale);+ const width = run.widths[wi];+ const alpha = alpha0 * Math.min(1, Math.max(0, d.opacity));+ // A word its effect has not brought in yet has no pixels; it still holds+ // its place, so the words beside it stay where they will be.+ if (alpha > 0.001) {+ // Every word draws from its own middle; a resized one has that middle+ // lifted or dropped by exactly as much as sharing the line's baseline+ // asks for.+ const size = fpx * mult;+ const mid = y + drop * (1 - mult);+ const drawY = mid;+ // Centered in the room the layout left it.+ const drawX = x + (width - run.drawn[wi]) / 2;+ // Everything below rides one saved state, so nothing set for this word+ // reaches the next.+ ctx.save();+ ctx.globalAlpha = alpha;+ // Offsets are em of the word's own size, and it turns about its center.+ if (d.dx || d.dy || d.rotate) {+ const wx = drawX + run.drawn[wi] / 2;+ ctx.translate(wx + d.dx * size, mid + d.dy * size);+ if (d.rotate) ctx.rotate((d.rotate * Math.PI) / 180);+ ctx.translate(-wx, -mid);}- } else {- drawText(w, x, drawY);- }- if (big) {- setSize(false);- ctx.textBaseline = "middle";+ setSize(mult);+ const boxed = d.mark === "box" && !!d.markAlpha;+ if (boxed) {+ // Accent box behind the word, and the word on top of it — both drawn+ // with the shadow off so the box and its word stay crisp.+ const pad = 0.12 * size;+ ctx.shadowColor = "transparent";+ ctx.globalAlpha = alpha * d.markAlpha!;+ ctx.fillStyle = d.markColor ?? WORD_ACCENT_DEFAULT;+ ctx.beginPath();+ ctx.roundRect(+ drawX - pad,+ mid - size * 0.5 - pad,+ run.drawn[wi] + pad * 2,+ size + pad * 2,+ 0.18 * size+ );+ ctx.fill();+ ctx.globalAlpha = alpha;+ }+ drawText(w, drawX, drawY, d.color);+ if (d.mark === "underline" && d.markAlpha) {+ ctx.globalAlpha = alpha * d.markAlpha;+ ctx.fillStyle = d.color;+ ctx.fillRect(drawX, mid + size * 0.42, run.drawn[wi], Math.max(2 * scale, size * 0.07));+ }+ ctx.restore();+ // `restore` puts the canvas back at the line's own size; the size this+ // painter tracks goes back with it.+ drawSize = fpx;}- x += run.widths[wi] + run.spaceW;+ x += width + run.spaceW;k++;});});+ ctx.globalAlpha = alpha0;ctx.textAlign = "center";}@@ -797,10 +857,12 @@ export function planAnimatedLayers(o: Overlay, end: number): AnimatedLayer[] {phase,});if (words) {- wordWindows((o as TextOverlay).text, dur, words.times).forEach((w, i) => {+ wordSampleWindows((o as TextOverlay).text, words, dur).forEach((w) => {const a = Math.max(start, o.start + w.start);const b = Math.min(stop, o.start + w.end);- if (b - a >= 1e-3) add(applyWordAccent(overlay, i), a, b);+ // Drawn at the middle of the span it stands for, which is where the+ // picture it caches actually sits.+ if (b - a >= 1e-3) add(applyWordDraw(overlay, (w.start + w.end) / 2, dur), a, b);});return;}@@ -906,14 +968,20 @@ export async function renderOverlayFrames(// the preset's own reach already covers where the glyphs get to.const loop = loopExtent(anim?.loop);const move = moveExtent(anim?.move);- const travel = (edgeTravel + loop.travel + move.travel) * scale;+ // A word effect can lift, shift or turn a word out of the resting line, in+ // em of the type's own size, so the region carries that reach as well.+ const accent = overlayWords(overlay);+ const wordTravel =+ accent && (overlay.kind ?? "text") === "text"+ ? wordReach(accent) * (overlay as TextOverlay).size * scale+ : 0;+ const travel = (edgeTravel + loop.travel + move.travel) * scale + wordTravel;// A keyframed element carries its own travel and its own zoom: the region// spans every pose the track visits, at the largest scale it reaches.const keyed = hasOverlayKeys(overlay);const extent = poseExtent(overlay);// A swollen word grows the line past the resting box, so the region carries// it — width from the swell, and the type's own extra height with it.- const accent = overlayWords(overlay);const maxScale = 1.15 * extent.scale * move.scale * wordSwell(accent);const rotates =!!overlay.rotation ||@@ -952,9 +1020,10 @@ export async function renderOverlayFrames(// Back to the origin the painters draw around, so they stay unaware of// any of this.ctx.translate(-overlay.x * width, -overlay.y * height);- let el: Overlay = applyWordAccent(+ let el: Overlay = applyWordDraw({ ...overlay, rotation: undefined, opacity: undefined },- wordAccentIndex(overlay, tLocal, dur)+ tLocal,+ dur);if (ev.textProgress !== undefined && (overlay.kind ?? "text") === "text") {const text = (overlay as TextOverlay).text;@@ -1021,10 +1090,11 @@ export async function renderOverlayFrames(if (middle > 1e-3) {const period = loopPeriod(anim) ?? lottieDur;if (accent) {- // The picture changes as the emphasis moves on, and nowhere else: one- // frame per word covers the middle however long it runs. The last one- // absorbs the rounding, so the pieces sum to the middle exactly.- const spans = wordWindows((overlay as TextOverlay).text, dur, accent.times)+ // The picture changes as the effect walks the line, and nowhere else:+ // one frame per span the engine says holds still covers the middle+ // however long it runs. The last one absorbs the rounding, so the+ // pieces sum to the middle exactly.+ const spans = wordSampleWindows((overlay as TextOverlay).text, accent, dur, fps).map((w) => ({ a: Math.max(inS, w.start), b: Math.min(dur - outS, w.end) })).filter((w) => w.b - w.a > 1e-3);if (spans.length > 0) spans[spans.length - 1].b = dur - outS;diff --git a/site/packages/effects-kit/src/types.ts b/site/packages/effects-kit/src/types.tsindex 1a1d08aa..1e409d8f 100644--- a/site/packages/effects-kit/src/types.ts+++ b/site/packages/effects-kit/src/types.ts@@ -9,6 +9,7 @@ import type { OverlayAnim } from "./anim";import type { EffectOverlay } from "./effects";import type { OverlayKey } from "./keys";import type { Mask } from "./mask";+import type { WordDraw } from "./words/types";/** Fields every overlay element carries, whatever its kind. */export interface OverlayBase {@@ -39,13 +40,6 @@ export interface OverlayBase {mask?: Mask;}-/** How a highlighted word lights up in karaoke text: accent color only,- * accent color plus underline, an accent box behind the word, or the word- * swelling at the accent color. A swollen word takes its new width in the- * line, so its neighbours move out of its way and settle back as the- * emphasis travels on. */-export type WordAccentMode = "color" | "underline" | "box" | "pop";-/** A custom drop shadow. Every field is optional — absent ones take the* legacy defaults, so `shadow: true` and `shadow: {}` render identically. */export interface TextShadowSpec {@@ -90,14 +84,10 @@ export interface TextOverlay extends OverlayBase {plateRadius?: number; // plate corner radius in emplateColor?: string; // plate fill colorplateOpacity?: number; // plate fill opacity 0..1- /** Karaoke burn-in: index of the display word (whitespace-split across all- * lines) drawn per the accent treatment. */- highlightWord?: number;- highlightColor?: string;- highlightMode?: WordAccentMode;- highlightText?: string;- /** How far the highlighted word swells; absent = the mode's own default. */- highlightScale?: number;+ /** Word burn-in: one entry per display word (whitespace-split across all+ * lines), each resolved to the color, opacity and pose it draws at. Stamped+ * by the word engine at paint time; absent = the line draws as one piece. */+ wordDraw?: WordDraw[];}export type ShapeKind =diff --git a/site/packages/effects-kit/src/words.test.ts b/site/packages/effects-kit/src/words.test.tsdeleted file mode 100644index 04d459cf..00000000--- a/site/packages/effects-kit/src/words.test.ts+++ /dev/null@@ -1,123 +0,0 @@-import { describe, expect, test } from "bun:test";-import { hasOverlayAnim } from "./anim";-import type { TextOverlay } from "./types";-import {- applyWordAccent,- displayWords,- wordAccent,- WORD_ACCENT_DEFAULT,- wordAccentIndex,- wordSwell,- WORD_POP_SCALE,- WORD_SWELL_MAX,- wordWindows,-} from "./words";--const title = (over: Partial<TextOverlay> = {}): TextOverlay => ({- id: "t1",- kind: "text",- text: "one two three",- start: 2,- end: 5,- x: 0.5,- y: 0.5,- size: 64,- font: "sf",- weight: 700,- color: "#FFFFFF",- shadow: true,- plate: false,- ...over,-});--describe("word windows", () => {- test("cover the span end to end with no gaps", () => {- const wins = wordWindows("one two three", 3);- expect(wins.length).toBe(3);- expect(wins[0].start).toBe(0);- expect(wins[2].end).toBe(3);- for (let i = 1; i < wins.length; i++) expect(wins[i].start).toBe(wins[i - 1].end);- });-- test("follow measured onsets when they match the words", () => {- const wins = wordWindows("one two three", 3, [0, 1.2, 2.4]);- expect(wins.map((w) => w.start)).toEqual([0, 1.2, 2.4]);- expect(wins[2].end).toBe(3);- });-- test("fall back to an even share when the text has outgrown the times", () => {- const wins = wordWindows("one two three four", 4, [0, 1.2, 2.4]);- expect(wins.length).toBe(4);- expect(wins[0].start).toBe(0);- });-- test("never run backwards", () => {- const wins = wordWindows("one two three", 3, [0, 2.5, 1]);- expect(wins[2].start).toBeGreaterThanOrEqual(wins[1].start);- });-- test("count words across lines", () => {- expect(displayWords("one two\nthree")).toEqual(["one", "two", "three"]);- });-});--describe("word emphasis", () => {- const words = { style: "pop" as const, color: "#FF3D00" };-- test("counts as animation, so both renderers take the moving path", () => {- expect(hasOverlayAnim({ words })).toBe(true);- expect(hasOverlayAnim({})).toBe(false);- });-- test("marks the word being said", () => {- const o = title({ anim: { words } });- expect(wordAccentIndex(o, 0, 3)).toBe(0);- expect(wordAccentIndex(o, 2.9, 3)).toBe(2);- });-- test("is a title's slot; other kinds ignore it", () => {- const sticker = { ...title({ anim: { words } }), kind: "sticker" as const, w: 0.2 };- expect(wordAccentIndex(sticker as never, 0, 3)).toBe(-1);- });-- test("paints through the same highlight fields captions ride", () => {- const marked = applyWordAccent(title({ anim: { words } }), 1) as TextOverlay;- expect(marked.highlightWord).toBe(1);- expect(marked.highlightMode).toBe("pop");- expect(marked.highlightColor).toBe("#FF3D00");- expect(marked.highlightText).toBe("#FFFFFF");- expect(marked.highlightScale).toBe(WORD_POP_SCALE);- });-- test("a swell keeps the line's own color; the color treatments take the accent", () => {- const swelled = applyWordAccent(- title({ color: "#FFFFFF", anim: { words: { style: "pop" } } }),- 0- ) as TextOverlay;- expect(swelled.highlightColor).toBe("#FFFFFF");- const boxed = applyWordAccent(- title({ color: "#FFFFFF", anim: { words: { style: "box" } } }),- 0- ) as TextOverlay;- expect(boxed.highlightColor).toBe(WORD_ACCENT_DEFAULT);- expect(wordAccent({ style: "pop", color: "#0A84FF" }, "#FFFFFF")).toBe("#0A84FF");- });-- test("swells by the treatment's default until something says otherwise", () => {- expect(wordSwell({ style: "pop" })).toBe(WORD_POP_SCALE);- expect(wordSwell({ style: "box" })).toBe(1);- expect(wordSwell({ style: "box", scale: 1.5 })).toBe(1.5);- expect(wordSwell(undefined)).toBe(1);- });-- test("holds the swell inside its bounds", () => {- expect(wordSwell({ style: "pop", scale: 9 })).toBe(WORD_SWELL_MAX);- expect(wordSwell({ style: "pop", scale: 0.2 })).toBe(1);- expect(wordSwell({ style: "pop", scale: Number.NaN })).toBe(WORD_POP_SCALE);- });-- test("an element with no emphasis rides through untouched", () => {- const o = title();- expect(applyWordAccent(o, 1)).toBe(o);- });-});diff --git a/site/packages/effects-kit/src/words.ts b/site/packages/effects-kit/src/words.tsdeleted file mode 100644index c81ab6d3..00000000--- a/site/packages/effects-kit/src/words.ts+++ /dev/null@@ -1,167 +0,0 @@-/**- * Word-by-word emphasis on text: the whole line stays on screen and the word- * being said takes the accent. Captions have had this since they carried word- * timings; here it is the same treatment offered as a slot on any text- * element, so a title placed by hand emphasizes on its own clock.- *- * The windows are the model. One per display word, covering the element's- * span end to end with no gaps, so the accent never blinks off between two- * words. `times` is the element's own clock — seconds from its start — filled- * in when something measured the speech; its absence means nobody did, and- * the words share the span by length.- */--import type { Overlay, TextOverlay, WordAccentMode } from "./types";--/** Accent for emphasis that names no color of its own. */-export const WORD_ACCENT_DEFAULT = "#FFE94A";--/** How much a popped word swells while it is said, and the bounds a caller- * may set instead. The swollen word takes its new width in the line, so the- * words beside it move out of its way and settle back as it shrinks. */-export const WORD_POP_SCALE = 1.24;-export const WORD_SWELL_MIN = 1;-export const WORD_SWELL_MAX = 2;--/** The treatments, in the order every picker offers them. */-export const WORD_ACCENT_MODE_IDS: WordAccentMode[] = ["pop", "color", "underline", "box"];--export const WORD_ACCENT_LABELS: Record<WordAccentMode, string> = {- pop: "Pop",- color: "Color",- underline: "Underline",- box: "Highlight",-};--export const WORD_ACCENT_NOTES: Record<WordAccentMode, string> = {- pop: "the word swells and the line makes room for it, in the text's own color unless an accent is set",- color: "the word takes the accent color",- underline: "accent color with a rule under the word",- box: "an accent box behind the word",-};--/** Word emphasis as an element carries it. */-export interface OverlayWords {- style: WordAccentMode;- /** Accent color; absent = the treatment's own default (see `wordAccent`):- * a swell keeps the text's color, the color treatments take the accent. */- color?: string;- /** How far the word swells while it is said, WORD_SWELL_MIN..MAX; absent =- * the treatment's own default. */- scale?: number;- /** Word onsets in seconds from the element's start, one per display word.- * Absent, or a count the text has outgrown, = an even share by length. */- times?: number[];-}--/**- * The color an emphasized word wears: what the element set, else the- * treatment's own default. A swell says everything it has to say with size,- * so it keeps the color the rest of the line is written in; the treatments- * that speak in color take the accent.- */-export function wordAccent(- w: { style?: WordAccentMode; color?: string } | undefined,- textColor: string-): string {- if (w?.color) return w.color;- return w?.style === "pop" ? textColor : WORD_ACCENT_DEFAULT;-}--/** How far the emphasized word swells: the element's own setting, else the- * treatment's default — a pop swells, the rest hold their size. */-export function wordSwell(w: { style?: WordAccentMode; scale?: number } | undefined): number {- if (!w) return 1;- const set = w.scale;- if (set !== undefined && Number.isFinite(set))- return Math.min(WORD_SWELL_MAX, Math.max(WORD_SWELL_MIN, set));- return w.style === "pop" ? WORD_POP_SCALE : 1;-}--/** The swell of the word a painted overlay has marked — the same reading as- * `wordSwell`, off the highlight fields the painters actually carry. */-export function highlightSwell(o: { highlightMode?: WordAccentMode; highlightScale?: number }): number {- return wordSwell({ style: o.highlightMode, scale: o.highlightScale });-}--/** Black or white, whichever reads on the given hex fill. */-export function contrastText(hex: string): string {- const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());- if (!m) return "#111114";- const n = parseInt(m[1], 16);- const lum = 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255);- return lum > 150 ? "#111114" : "#FFFFFF";-}--/** The display words of a text block: whitespace-split across every line.- * Both renderers walk them in this order, which is what a word index means. */-export function displayWords(text: string): string[] {- return text.trim().split(/\s+/).filter(Boolean);-}--/**- * One window per display word, seconds from the element's start, partitioning- * [0, dur] with no gaps. Measured onsets are used while they still match the- * text one for one; otherwise (an edited line, a rewrite) the span is split- * proportionally by word length.- */-export function wordWindows(- text: string,- dur: number,- times?: number[]-): { start: number; end: number }[] {- const words = displayWords(text);- const n = words.length;- if (n === 0 || dur <= 0) return [];- const starts: number[] = [];- if (times && times.length === n) {- for (let i = 0; i < n; i++) {- const t = i === 0 ? 0 : Math.min(Math.max(times[i], 0), dur);- starts.push(i > 0 && t < starts[i - 1] ? starts[i - 1] : t);- }- } else {- const weights = words.map((w) => w.length + 1);- const total = weights.reduce((a, b) => a + b, 0);- let acc = 0;- for (const w of weights) {- starts.push((dur * acc) / total);- acc += w;- }- }- return starts.map((start, i) => ({ start, end: i === n - 1 ? dur : starts[i + 1] }));-}--/** The emphasis an element carries, or nothing — the slot is text only. */-export function overlayWords(o: Overlay): OverlayWords | undefined {- if ((o.kind ?? "text") !== "text") return undefined;- return o.anim?.words;-}--/** Which display word is emphasized at `tLocal`, or -1 before the first. */-export function wordAccentIndex(o: Overlay, tLocal: number, dur: number): number {- const w = overlayWords(o);- if (!w) return -1;- return wordWindows((o as TextOverlay).text, dur, w.times).findIndex(- (win) => tLocal >= win.start && tLocal < win.end- );-}--/**- * The element as it paints with one word emphasized — the same- * `highlightWord` fields captions ride, so the painters need to know nothing- * about where the index came from. An element with no emphasis, or a time- * before its first word, rides through untouched.- */-export function applyWordAccent<T extends Overlay>(o: T, index: number): T {- const w = overlayWords(o);- if (!w || index < 0) return o;- const color = wordAccent(w, (o as TextOverlay).color ?? WORD_ACCENT_DEFAULT);- return {- ...o,- highlightWord: index,- highlightColor: color,- highlightMode: w.style,- highlightText: contrastText(color),- highlightScale: wordSwell(w),- } as T;-}diff --git a/site/packages/effects-kit/src/words/catalog.ts b/site/packages/effects-kit/src/words/catalog.tsnew file mode 100644index 00000000..d5b8eb36--- /dev/null+++ b/site/packages/effects-kit/src/words/catalog.ts@@ -0,0 +1,88 @@+/**+ * The word-effect catalog: every treatment a line's words can take, as data.+ *+ * The JSON beside this file holds them in the three-pose shape `types.ts`+ * describes. Every picker, tool enum and prompt line is written from these+ * entries, so an effect added to the file reaches the element panel, the+ * caption panel and the assistant at once.+ */++import effects from "./effects.json";+import type { WordEffect, WordEffectId, WordFamily, WordPose } from "./types";++export const WORD_EFFECTS: Record<string, WordEffect> = effects as unknown as Record<+ string,+ WordEffect+>;++/** The effects, in the order every picker offers them. */+export const WORD_EFFECT_IDS: WordEffectId[] = Object.keys(WORD_EFFECTS);++/** The effect an id names, or the plainest one when the id is unknown — a+ * document written against an effect since renamed still plays. */+export function wordEffect(id: WordEffectId | undefined): WordEffect {+ return WORD_EFFECTS[id ?? ""] ?? WORD_EFFECTS.color;+}++export const WORD_EFFECT_LABELS: Record<string, string> = Object.fromEntries(+ WORD_EFFECT_IDS.map((id) => [id, WORD_EFFECTS[id].label])+);++export const WORD_EFFECT_NOTES: Record<string, string> = Object.fromEntries(+ WORD_EFFECT_IDS.map((id) => [id, WORD_EFFECTS[id].note])+);++/** The catalog as a menu: id, label and line, in picker order — what the+ * element panel, the caption panel and the tool enums all list from. */+export const WORD_EFFECT_MENU: { id: WordEffectId; label: string; note: string; family: WordFamily }[] =+ WORD_EFFECT_IDS.map((id) => ({+ id,+ label: WORD_EFFECTS[id].label,+ note: WORD_EFFECTS[id].note,+ family: WORD_EFFECTS[id].family,+ }));++/** The shelves the picker lays out, with the line each one is titled by. */+export const WORD_FAMILIES: { id: WordFamily; label: string; note: string }[] = [+ {+ id: "emphasis",+ label: "Emphasis",+ note: "the treatment travels along the line, one word at a time",+ },+ { id: "build", label: "Build", note: "the line assembles itself as it is spoken" },+];++export const wordEffectIdsIn = (family: WordFamily): WordEffectId[] =>+ WORD_EFFECT_IDS.filter((id) => WORD_EFFECTS[id].family === family);++const poses = (e: WordEffect): WordPose[] => [e.before, e.active, e.after];++/** Which settings an effect actually has, so a panel offers the knobs that do+ * something and no others. `size` drives every pose scale above 1, `dim` every+ * pose opacity below 1, `color` the accent the effect runs to. A value the+ * element already carries opens its knob whatever the effect does, so a+ * setting in play is always one the reader can see and change. */+export function wordKnobs(+ e: WordEffect,+ set?: { scale?: number; dim?: number }+): { size: boolean; color: boolean; dim: boolean } {+ return {+ size: poses(e).some((p) => (p.scale ?? 1) > 1) || set?.scale !== undefined,+ color: poses(e).some((p) => (p.accent ?? 0) > 0),+ dim: poses(e).some((p) => (p.opacity ?? 1) < 1) || set?.dim !== undefined,+ };+}++/** An effect whose poses change over seconds rather than landing on the beat.+ * A ramp means the picture moves inside a word's window, so the frame+ * samplers cut it finer than one still per word. */+export const wordEffectRamps = (e: WordEffect): boolean => e.attack > 0 || e.release > 0;++/** The catalog as prompt text: one line per effect, grouped by shelf. */+export const wordEffectCatalog = (): string =>+ WORD_FAMILIES.map(+ (f) =>+ `${f.label} — ${f.note}: ${wordEffectIdsIn(f.id)+ .map((id) => `${id} (${WORD_EFFECTS[id].note})`)+ .join("; ")}`+ ).join("\n");diff --git a/site/packages/effects-kit/src/words/effects.json b/site/packages/effects-kit/src/words/effects.jsonnew file mode 100644index 00000000..8973a48d--- /dev/null+++ b/site/packages/effects-kit/src/words/effects.json@@ -0,0 +1,122 @@+{+ "color": {+ "label": "Color",+ "note": "the word being said takes the accent color and hands it on",+ "family": "emphasis",+ "before": {},+ "active": { "accent": 1 },+ "after": {},+ "attack": 0,+ "release": 0+ },+ "pop": {+ "label": "Pop",+ "note": "the word swells and the line makes room for it, in the text's own color unless an accent is set",+ "family": "emphasis",+ "before": {},+ "active": { "accent": 1, "scale": 1.24 },+ "after": {},+ "attack": 0,+ "release": 0,+ "accentDefault": "text"+ },+ "underline": {+ "label": "Underline",+ "note": "accent color with a rule under the word",+ "family": "emphasis",+ "before": {},+ "active": { "accent": 1, "mark": 1 },+ "after": {},+ "attack": 0,+ "release": 0,+ "mark": "underline"+ },+ "box": {+ "label": "Highlight",+ "note": "an accent box behind the word",+ "family": "emphasis",+ "before": {},+ "active": { "accent": 1, "mark": 1 },+ "after": {},+ "attack": 0,+ "release": 0,+ "mark": "box"+ },+ "spotlight": {+ "label": "Spotlight",+ "note": "the line sits faded and only the word being said is at full strength",+ "family": "emphasis",+ "before": { "opacity": 0.35 },+ "active": { "opacity": 1 },+ "after": { "opacity": 0.35 },+ "attack": 0.1,+ "release": 0.18,+ "ease": [0.33, 0, 0.67, 1]+ },+ "build": {+ "label": "Build up",+ "note": "the line starts empty and each word appears as it is said, completing the sentence",+ "family": "build",+ "before": { "opacity": 0 },+ "active": { "opacity": 1 },+ "after": { "opacity": 1 },+ "attack": 0.14,+ "release": 0,+ "ease": [0.33, 0, 0.67, 1]+ },+ "fill": {+ "label": "Fill in",+ "note": "the whole line is up but faint, and each word goes solid as it is said until the sentence is fully opaque",+ "family": "build",+ "before": { "opacity": 0.3 },+ "active": { "opacity": 1 },+ "after": { "opacity": 1 },+ "attack": 0.2,+ "release": 0,+ "ease": [0.33, 0, 0.67, 1]+ },+ "rise": {+ "label": "Rise up",+ "note": "each word lifts into its place as it is said and stays",+ "family": "build",+ "before": { "opacity": 0, "dy": 0.45 },+ "active": { "opacity": 1, "dy": 0 },+ "after": { "opacity": 1, "dy": 0 },+ "attack": 0.26,+ "release": 0,+ "ease": [0.16, 1, 0.3, 1]+ },+ "bloom": {+ "label": "Bloom",+ "note": "each word grows out of nothing into its size as it is said and stays",+ "family": "build",+ "before": { "opacity": 0, "scale": 0.4 },+ "active": { "opacity": 1, "scale": 1 },+ "after": { "opacity": 1, "scale": 1 },+ "attack": 0.24,+ "release": 0,+ "ease": [0.34, 1.56, 0.64, 1]+ },+ "swing": {+ "label": "Swing in",+ "note": "each word drops in leaning and rights itself as it is said",+ "family": "build",+ "before": { "opacity": 0, "rotate": -14, "dy": -0.3 },+ "active": { "opacity": 1, "rotate": 0, "dy": 0 },+ "after": { "opacity": 1, "rotate": 0, "dy": 0 },+ "attack": 0.3,+ "release": 0,+ "ease": [0.34, 1.56, 0.64, 1]+ },+ "paint": {+ "label": "Paint on",+ "note": "the line is written in its own color and each word takes the accent as it is said, keeping it",+ "family": "build",+ "before": {},+ "active": { "accent": 1 },+ "after": { "accent": 1 },+ "attack": 0.12,+ "release": 0,+ "ease": [0.33, 0, 0.67, 1]+ }+}diff --git a/site/packages/effects-kit/src/words/engine.ts b/site/packages/effects-kit/src/words/engine.tsnew file mode 100644index 00000000..5b2ba6fb--- /dev/null+++ b/site/packages/effects-kit/src/words/engine.ts@@ -0,0 +1,348 @@+/**+ * The one word evaluator.+ *+ * Everything a line does word by word — the karaoke accent captions have+ * always had, a title swelling on the beat, a sentence assembling itself as+ * it is spoken — comes through here. The windows are the model: one per+ * display word, covering the element's span end to end with no gaps, so a+ * treatment never blinks off between two words. `times` is the element's own+ * clock, filled in when something measured the speech; its absence means+ * nobody did, and the words share the span by length.+ *+ * A word's look at a moment is read off its effect's three poses and the+ * seconds between them (see `types.ts`), resolved to a `WordDraw` the+ * painters read straight. Neither painter knows what an effect is.+ */++import { bezierEase } from "../motion/evaluate";+import type { Overlay, TextOverlay } from "../types";+import { wordEffect, wordEffectRamps } from "./catalog";+import type { OverlayWords, WordDraw, WordEffect, WordPose } from "./types";++/** How far a word's alphabetic baseline sits below the middle of its em box,+ * in em. The canvas painter measures this off the face it is drawing and only+ * falls back here; a stylesheet cannot measure, so the DOM twin works from+ * this figure, which is where the two can differ by a hair while a word is+ * mid-resize. */+export const WORD_BASELINE_DROP = 0.3;++/** Accent for an effect that names no color of its own. */+export const WORD_ACCENT_DEFAULT = "#FFE94A";++/** How much a popped word swells while it is said, and the bounds a caller+ * may set instead. */+export const WORD_POP_SCALE = 1.24;+export const WORD_SWELL_MIN = 1;+export const WORD_SWELL_MAX = 2;++const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);+const lerp = (a: number, b: number, p: number) => a + (b - a) * p;++/** Black or white, whichever reads on the given hex fill. */+export function contrastText(hex: string): string {+ const n = hexValue(hex);+ if (n === null) return "#111114";+ const lum = 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255);+ return lum > 150 ? "#111114" : "#FFFFFF";+}++function hexValue(hex: string): number | null {+ const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());+ return m ? parseInt(m[1], 16) : null;+}++/** Two hex colors blended in sRGB. Anything that will not parse hands back+ * the endpoint it is nearest, so an unusual color string still draws. */+export function mixHex(from: string, to: string, p: number): string {+ if (p <= 0.001) return from;+ if (p >= 0.999) return to;+ const a = hexValue(from);+ const b = hexValue(to);+ if (a === null || b === null) return p < 0.5 ? from : to;+ let out = "#";+ for (let s = 16; s >= 0; s -= 8) {+ const v = Math.round(lerp((a >> s) & 255, (b >> s) & 255, p));+ out += v.toString(16).padStart(2, "0");+ }+ return out;+}++/**+ * The color a word runs to: what the element set, else the effect's own+ * default. An effect that says everything with size keeps the color the rest+ * of the line is written in; the ones that speak in color take the accent.+ */+export function wordAccent(+ w: { style?: string; color?: string } | undefined,+ textColor: string+): string {+ if (w?.color) return w.color;+ return wordEffect(w?.style).accentDefault === "text" ? textColor : WORD_ACCENT_DEFAULT;+}++/** How far a word swells at its moment: the element's own setting, else the+ * peak its effect reaches. Never below 1 — this is also the room a frame+ * sampler leaves around the line for a word that grows past it. */+export function wordSwell(w: { style?: string; scale?: number } | undefined): number {+ if (!w) return 1;+ const set = w.scale;+ if (set !== undefined && Number.isFinite(set))+ return Math.min(WORD_SWELL_MAX, Math.max(WORD_SWELL_MIN, set));+ const e = wordEffect(w.style);+ return Math.max(1, e.before.scale ?? 1, e.active.scale ?? 1, e.after.scale ?? 1);+}++/** The opacity a word wears off its moment: the element's own setting, else+ * the faintest its effect calls for. */+export function wordDim(w: { style?: string; dim?: number } | undefined): number {+ if (w?.dim !== undefined && Number.isFinite(w.dim)) return clamp01(w.dim);+ const e = wordEffect(w?.style);+ return Math.min(1, e.before.opacity ?? 1, e.active.opacity ?? 1, e.after.opacity ?? 1);+}++/** The display words of a text block: whitespace-split across every line.+ * Both renderers walk them in this order, which is what a word index means. */+export function displayWords(text: string): string[] {+ return text.trim().split(/\s+/).filter(Boolean);+}++/**+ * One window per display word, seconds from the element's start, partitioning+ * [0, dur] with no gaps. Measured onsets are used while they still match the+ * text one for one; otherwise (an edited line, a rewrite) the span is split+ * proportionally by word length.+ */+export function wordWindows(+ text: string,+ dur: number,+ times?: number[]+): { start: number; end: number }[] {+ const words = displayWords(text);+ const n = words.length;+ if (n === 0 || dur <= 0) return [];+ const starts: number[] = [];+ if (times && times.length === n) {+ for (let i = 0; i < n; i++) {+ const t = i === 0 ? 0 : Math.min(Math.max(times[i], 0), dur);+ starts.push(i > 0 && t < starts[i - 1] ? starts[i - 1] : t);+ }+ } else {+ const weights = words.map((w) => w.length + 1);+ const total = weights.reduce((a, b) => a + b, 0);+ let acc = 0;+ for (const w of weights) {+ starts.push((dur * acc) / total);+ acc += w;+ }+ }+ return starts.map((start, i) => ({ start, end: i === n - 1 ? dur : starts[i + 1] }));+}++/** A pose with every channel filled in, and the element's two overrides+ * folded in: the size knob replaces every scale above 1, the dim knob every+ * opacity below 1. Both are single settings across the effect, so an effect+ * that wanted two different faint levels would flatten them — none does. */+function settled(+ p: WordPose,+ swell: number,+ dim: number,+ /** The pose a word wears at its moment, which is where a swell the caller+ * asked for lands even on an effect that resizes nothing of its own. */+ atItsMoment = false+): Required<WordPose> {+ const scale = p.scale ?? 1;+ const opacity = p.opacity ?? 1;+ return {+ accent: p.accent ?? 0,+ opacity: opacity < 1 ? dim : 1,+ scale: scale > 1 || (atItsMoment && swell > 1) ? swell : scale,+ dx: p.dx ?? 0,+ dy: p.dy ?? 0,+ rotate: p.rotate ?? 0,+ mark: p.mark ?? 0,+ };+}++function blend(a: Required<WordPose>, b: Required<WordPose>, p: number): Required<WordPose> {+ return {+ accent: lerp(a.accent, b.accent, p),+ opacity: lerp(a.opacity, b.opacity, p),+ scale: lerp(a.scale, b.scale, p),+ dx: lerp(a.dx, b.dx, p),+ dy: lerp(a.dy, b.dy, p),+ rotate: lerp(a.rotate, b.rotate, p),+ mark: lerp(a.mark, b.mark, p),+ };+}++/**+ * One word's pose at `t` seconds on the element's clock: held at `before`+ * until its window opens, ramped to `active` over the attack, held there to+ * the end of the window, then ramped to `after` over the release. An attack+ * longer than the window itself is cut to fit, so a fast word still finishes+ * arriving before the next one starts.+ */+export function wordPoseAt(+ e: WordEffect,+ win: { start: number; end: number },+ t: number,+ opts: { swell: number; dim: number }+): Required<WordPose> {+ const before = settled(e.before, opts.swell, opts.dim);+ const active = settled(e.active, opts.swell, opts.dim, true);+ const after = settled(e.after, opts.swell, opts.dim);+ const ease = (u: number) => (e.ease ? bezierEase(e.ease, clamp01(u)) : clamp01(u));+ const span = Math.max(0, win.end - win.start);+ const attack = Math.min(e.attack, span);+ if (t < win.start) return before;+ if (attack > 0 && t < win.start + attack)+ return blend(before, active, ease((t - win.start) / attack));+ if (t < win.end) return active;+ if (e.release > 0 && t < win.end + e.release)+ return blend(active, after, ease((t - win.end) / e.release));+ return after;+}++/** The word effect an element carries, or nothing — the slot is text only. */+export function overlayWords(o: Overlay): OverlayWords | undefined {+ if ((o.kind ?? "text") !== "text") return undefined;+ return o.anim?.words;+}++/**+ * Every display word resolved for drawing at `t` seconds on the element's+ * clock. The accent is already blended into each word's fill, so a painter+ * reads colors and numbers and nothing else.+ */+export function wordDrawsAt(+ text: string,+ words: OverlayWords,+ textColor: string,+ dur: number,+ t: number+): WordDraw[] {+ const e = wordEffect(words.style);+ const accent = wordAccent(words, textColor);+ const markText = contrastText(accent);+ // A box puts the word inside the accent, so its fill runs to the color that+ // reads against that fill rather than to the accent itself.+ const target = e.mark === "box" ? markText : accent;+ const opts = { swell: wordSwell(words), dim: wordDim(words) };+ const restScale = (e.after.scale ?? 1) > 1 ? opts.swell : (e.after.scale ?? 1);+ return wordWindows(text, dur, words.times).map((win) => {+ const p = wordPoseAt(e, win, t, opts);+ return {+ color: mixHex(textColor, target, p.accent),+ opacity: p.opacity,+ scale: p.scale,+ layoutScale: Math.max(p.scale, restScale),+ dx: p.dx,+ dy: p.dy,+ rotate: p.rotate,+ ...(e.mark && p.mark > 0.001+ ? { mark: e.mark, markAlpha: p.mark, markColor: accent, markText }+ : {}),+ };+ });+}++/**+ * The element as it paints at `t`, its words resolved — the one field both+ * painters read, so neither needs to know an effect exists. An element with+ * no word effect rides through untouched.+ */+export function applyWordDraw<T extends Overlay>(o: T, t: number, dur: number): T {+ const w = overlayWords(o);+ if (!w) return o;+ const text = o as TextOverlay;+ return {+ ...o,+ wordDraw: wordDrawsAt(text.text, w, text.color ?? WORD_ACCENT_DEFAULT, dur, t),+ } as T;+}++/** Frames per second a ramping effect is cut at when a sampler has to bake it+ * into stills. Matches the slice rate the typed-out ramps use. */+const WORD_SLICE_FPS = 24;++/**+ * The spans a sampler has to draw separately to carry this effect: one per+ * stretch where the picture holds still, cut finer wherever a word is+ * ramping. An effect that lands on the beat comes back as its word windows+ * exactly — one still per word, which is what the caption burn-in has always+ * written. Spans partition [0, dur] with no gaps.+ */+export function wordSampleWindows(+ text: string,+ words: OverlayWords,+ dur: number,+ fps = WORD_SLICE_FPS,+ /** Most slices one ramp may be cut into. A sampler whose pictures are+ * expensive — a caption burn-in draws whole frames — bounds it, so a long+ * attack costs the same few pictures a short one does. */+ maxSlices = Infinity+): { start: number; end: number }[] {+ const wins = wordWindows(text, dur, words.times);+ if (wins.length === 0) return [];+ const e = wordEffect(words.style);+ const cuts = new Set<number>([0, dur]);+ const at = (v: number) => {+ if (v > 1e-3 && v < dur - 1e-3) cuts.add(Math.round(v * 1e4) / 1e4);+ };+ for (const w of wins) {+ at(w.start);+ at(w.end);+ }+ if (wordEffectRamps(e)) {+ const ramp = (from: number, secs: number) => {+ if (secs <= 0) return;+ const n = Math.min(Math.ceil(secs * fps), maxSlices + 1);+ for (let i = 1; i < n; i++) at(from + (secs * i) / n);+ };+ for (const w of wins) {+ ramp(w.start, Math.min(e.attack, Math.max(0, w.end - w.start)));+ ramp(w.end, e.release);+ }+ }+ const sorted = [...cuts].sort((a, b) => a - b);+ const out: { start: number; end: number }[] = [];+ for (let i = 0; i + 1 < sorted.length; i++) {+ if (sorted[i + 1] - sorted[i] > 1e-3) out.push({ start: sorted[i], end: sorted[i + 1] });+ }+ return out;+}++/** A hex color at a given alpha, as the 8-digit hex both CSS and a canvas+ * fill accept. */+export function hexAlpha(hex: string, a: number): string {+ const n = hexValue(hex);+ const byte = Math.round(clamp01(a) * 255)+ .toString(16)+ .padStart(2, "0");+ if (n === null) return hex;+ return `#${n.toString(16).padStart(6, "0")}${byte}`;+}++/** How far a word strays from its place, in em of its own type size — the+ * room a frame sampler has to leave around the line. A turn counts as reach+ * too: a word pivoting about its own center swings its ends out of the box.+ */+export function wordReach(w: { style?: string } | undefined): number {+ if (!w) return 0;+ const e = wordEffect(w.style);+ const of = (p: WordPose) =>+ Math.max(Math.abs(p.dx ?? 0), Math.abs(p.dy ?? 0)) + Math.abs(p.rotate ?? 0) / 30;+ return Math.max(of(e.before), of(e.active), of(e.after));+}++/** A word at rest — the pose a painter falls back to when the track it was+ * handed is shorter than the text it is drawing. */+export const REST_WORD: WordDraw = {+ color: "#FFFFFF",+ opacity: 1,+ scale: 1,+ layoutScale: 1,+ dx: 0,+ dy: 0,+ rotate: 0,+};diff --git a/site/packages/effects-kit/src/words/index.ts b/site/packages/effects-kit/src/words/index.tsnew file mode 100644index 00000000..260d6b7c--- /dev/null+++ b/site/packages/effects-kit/src/words/index.ts@@ -0,0 +1,3 @@+export * from "./types";+export * from "./catalog";+export * from "./engine";diff --git a/site/packages/effects-kit/src/words/types.ts b/site/packages/effects-kit/src/words/types.tsnew file mode 100644index 00000000..9bd111e8--- /dev/null+++ b/site/packages/effects-kit/src/words/types.ts@@ -0,0 +1,108 @@+/**+ * The word-effect format: three poses and the seconds between them.+ *+ * A word effect is what a line does word by word while it plays. Each display+ * word owns a window on the element's clock (see `wordWindows`), and the+ * effect says how that word looks before its window, at it, and after it has+ * passed. An emphasis travels — `after` is `before`, so the treatment moves+ * along the line. A build accumulates — `after` is `active`, so the line+ * assembles itself as it is spoken.+ *+ * Everything in the picker is one entry in this shape, stored as data beside+ * this file. Adding an effect means adding an entry; no code lists them.+ */++import type { Easing } from "../motion/types";++/** One word's look at one moment. Offsets are em of the word's own type size,+ * rotation is degrees clockwise about its center; every channel is optional+ * and an absent one rests. */+export interface WordPose {+ /** How far the word has taken the accent color, 0..1. */+ accent?: number;+ /** The word's own opacity, multiplying the element's. */+ opacity?: number;+ /** Type-size multiplier. A word drawn bigger takes its new width in the+ * line, so its neighbours move out of its way and settle back after. */+ scale?: number;+ dx?: number;+ dy?: number;+ rotate?: number;+ /** How far the effect's mark is drawn, 0..1. */+ mark?: number;+}++/** The mark an effect draws behind or under the word it is on. */+export type WordMark = "underline" | "box";++/** Which shelf of the picker an effect sits on: an emphasis that travels+ * along the line, or a build the line assembles itself through. */+export type WordFamily = "emphasis" | "build";++export interface WordEffect {+ label: string;+ /** What the effect does, in one line — the text the tool schemas and the+ * assistant's skills are written from. */+ note: string;+ family: WordFamily;+ /** Before the word's window. */+ before: WordPose;+ /** Once it has arrived. */+ active: WordPose;+ /** After its window has passed. */+ after: WordPose;+ /** Seconds from the word's onset to `active`; 0 = it lands on the beat. */+ attack: number;+ /** Seconds from the end of its window to `after`; 0 = it leaves on the+ * beat. */+ release: number;+ ease?: Easing;+ mark?: WordMark;+ /** The color the accent channel runs to when the element names none: the+ * accent (`accent`), or the text's own color (`text`), which is what an+ * effect that says everything with size wants. */+ accentDefault?: "accent" | "text";+}++/** The effect ids, as saved on an element and on the subtitles block. */+export type WordEffectId = string;++/** Word effects as an element carries them. */+export interface OverlayWords {+ style: WordEffectId;+ /** Accent color; absent = the effect's own default (see `wordAccent`). */+ color?: string;+ /** How far a word swells at its moment; replaces every pose scale above 1.+ * Absent = the effect's own. */+ scale?: number;+ /** The opacity a word wears off its moment; replaces every pose opacity+ * below 1. Absent = the effect's own. */+ dim?: number;+ /** Word onsets in seconds from the element's start, one per display word.+ * Absent, or a count the text has outgrown, = an even share by length. */+ times?: number[];+}++/** One word, resolved for drawing: what both painters read and neither+ * computes. */+export interface WordDraw {+ /** The fill, with the accent already blended in. */+ color: string;+ opacity: number;+ scale: number;+ /** The size the word takes room at, which is its own or its resting size,+ * whichever is wider. A word swelling past its rest pushes its neighbours+ * aside; one still growing into place holds the room it will end up+ * needing, so the line does not slide about as it assembles. */+ layoutScale: number;+ /** Em of the word's own type size. */+ dx: number;+ dy: number;+ rotate: number;+ /** The mark to draw, and how far; absent = none. */+ mark?: WordMark;+ markAlpha?: number;+ markColor?: string;+ /** Word color over a box, which needs to read against the fill. */+ markText?: string;+}diff --git a/site/packages/effects-kit/src/words/words.test.ts b/site/packages/effects-kit/src/words/words.test.tsnew file mode 100644index 00000000..426b6a23--- /dev/null+++ b/site/packages/effects-kit/src/words/words.test.ts@@ -0,0 +1,261 @@+import { describe, expect, test } from "bun:test";+import { hasOverlayAnim } from "../anim";+import type { TextOverlay } from "../types";+import {+ applyWordDraw,+ displayWords,+ mixHex,+ wordAccent,+ WORD_ACCENT_DEFAULT,+ wordDim,+ wordDrawsAt,+ wordEffect,+ WORD_EFFECT_IDS,+ wordKnobs,+ WORD_POP_SCALE,+ wordSampleWindows,+ wordSwell,+ WORD_SWELL_MAX,+ wordWindows,+} from ".";++const title = (over: Partial<TextOverlay> = {}): TextOverlay => ({+ id: "t1",+ kind: "text",+ text: "one two three",+ start: 2,+ end: 5,+ x: 0.5,+ y: 0.5,+ size: 64,+ font: "sf",+ weight: 700,+ color: "#FFFFFF",+ shadow: true,+ plate: false,+ ...over,+});++describe("word windows", () => {+ test("cover the span end to end with no gaps", () => {+ const wins = wordWindows("one two three", 3);+ expect(wins.length).toBe(3);+ expect(wins[0].start).toBe(0);+ expect(wins[2].end).toBe(3);+ for (let i = 1; i < wins.length; i++) expect(wins[i].start).toBe(wins[i - 1].end);+ });++ test("follow measured onsets when they match the words", () => {+ const wins = wordWindows("one two three", 3, [0, 1.2, 2.4]);+ expect(wins.map((w) => w.start)).toEqual([0, 1.2, 2.4]);+ expect(wins[2].end).toBe(3);+ });++ test("fall back to an even share when the text has outgrown the times", () => {+ const wins = wordWindows("one two three four", 4, [0, 1.2, 2.4]);+ expect(wins.length).toBe(4);+ expect(wins[0].start).toBe(0);+ });++ test("never run backwards", () => {+ const wins = wordWindows("one two three", 3, [0, 2.5, 1]);+ expect(wins[2].start).toBeGreaterThanOrEqual(wins[1].start);+ });++ test("count words across lines", () => {+ expect(displayWords("one two\nthree")).toEqual(["one", "two", "three"]);+ });+});++describe("the catalog", () => {+ test("every effect names its family and settles its three poses", () => {+ for (const id of WORD_EFFECT_IDS) {+ const e = wordEffect(id);+ expect(["emphasis", "build"]).toContain(e.family);+ expect(e.attack).toBeGreaterThanOrEqual(0);+ expect(e.release).toBeGreaterThanOrEqual(0);+ }+ });++ test("an emphasis returns to where it started; a build keeps what it did", () => {+ expect(wordEffect("color").after).toEqual(wordEffect("color").before);+ expect(wordEffect("build").after).toEqual(wordEffect("build").active);+ });++ test("an unknown id falls back rather than throwing", () => {+ expect(wordEffect("nope").label).toBe(wordEffect("color").label);+ });++ test("offers the knobs an effect actually uses", () => {+ expect(wordKnobs(wordEffect("pop"))).toEqual({ size: true, color: true, dim: false });+ expect(wordKnobs(wordEffect("build"))).toEqual({ size: false, color: false, dim: true });+ });+});++describe("word effects", () => {+ const words = { style: "pop", color: "#FF3D00" };++ test("count as animation, so both renderers take the moving path", () => {+ expect(hasOverlayAnim({ words })).toBe(true);+ expect(hasOverlayAnim({})).toBe(false);+ });++ test("mark the word being said and leave the rest alone", () => {+ const draws = wordDrawsAt("one two three", words, "#FFFFFF", 3, 0);+ expect(draws[0].color).toBe("#FF3D00");+ expect(draws[0].scale).toBe(WORD_POP_SCALE);+ expect(draws[1].color).toBe("#FFFFFF");+ expect(draws[1].scale).toBe(1);+ });++ test("are a title's slot; other kinds ride through untouched", () => {+ const sticker = { ...title({ anim: { words } }), kind: "sticker" as const, w: 0.2 };+ expect(applyWordDraw(sticker as never, 0, 3)).toBe(sticker);+ });++ test("stamp one entry per display word", () => {+ const marked = applyWordDraw(title({ anim: { words } }), 1.5, 3) as TextOverlay;+ expect(marked.wordDraw?.length).toBe(3);+ });++ test("a swell keeps the line's own color; the color treatments take the accent", () => {+ expect(wordAccent({ style: "pop" }, "#FFFFFF")).toBe("#FFFFFF");+ expect(wordAccent({ style: "box" }, "#FFFFFF")).toBe(WORD_ACCENT_DEFAULT);+ expect(wordAccent({ style: "pop", color: "#0A84FF" }, "#FFFFFF")).toBe("#0A84FF");+ });++ test("a box puts contrast text on the word so it reads against its own fill", () => {+ const draws = wordDrawsAt("one two", { style: "box", color: "#FFE94A" }, "#FFFFFF", 2, 0);+ expect(draws[0].mark).toBe("box");+ expect(draws[0].markColor).toBe("#FFE94A");+ expect(draws[0].color).toBe("#111114");+ });++ test("swell by the effect's default until something says otherwise", () => {+ expect(wordSwell({ style: "pop" })).toBe(WORD_POP_SCALE);+ expect(wordSwell({ style: "box" })).toBe(1);+ expect(wordSwell({ style: "box", scale: 1.5 })).toBe(1.5);+ expect(wordSwell(undefined)).toBe(1);+ });++ test("hold the swell inside its bounds", () => {+ expect(wordSwell({ style: "pop", scale: 9 })).toBe(WORD_SWELL_MAX);+ expect(wordSwell({ style: "pop", scale: 0.2 })).toBe(1);+ expect(wordSwell({ style: "pop", scale: Number.NaN })).toBe(WORD_POP_SCALE);+ });++ test("an element with no effect rides through untouched", () => {+ const o = title();+ expect(applyWordDraw(o, 1, 3)).toBe(o);+ });+});++describe("a build", () => {+ const words = { style: "build", times: [0, 1, 2] };+ const text = "one two three";++ test("starts with nothing up and finishes with the whole line", () => {+ const first = wordDrawsAt(text, words, "#FFFFFF", 3, 0);+ expect(first[1].opacity).toBe(0);+ expect(first[2].opacity).toBe(0);+ const last = wordDrawsAt(text, words, "#FFFFFF", 3, 2.9);+ expect(last.every((d) => d.opacity === 1)).toBe(true);+ });++ test("keeps every word it has landed", () => {+ const mid = wordDrawsAt(text, words, "#FFFFFF", 3, 1.5);+ expect(mid[0].opacity).toBe(1);+ expect(mid[1].opacity).toBe(1);+ expect(mid[2].opacity).toBe(0);+ });++ test("ramps rather than snapping", () => {+ const e = wordEffect("build");+ const mid = wordDrawsAt(text, words, "#FFFFFF", 3, 1 + e.attack / 2);+ expect(mid[1].opacity).toBeGreaterThan(0);+ expect(mid[1].opacity).toBeLessThan(1);+ });+});++describe("a fill", () => {+ const words = { style: "fill", times: [0, 1, 2] };+ const text = "one two three";++ test("leaves the whole line faintly up before its words land", () => {+ const draws = wordDrawsAt(text, words, "#FFFFFF", 3, 0);+ expect(draws[2].opacity).toBeCloseTo(wordEffect("fill").before.opacity!, 5);+ expect(draws[2].opacity).toBeGreaterThan(0);+ });++ test("takes the caller's transparency over its own", () => {+ const draws = wordDrawsAt(text, { ...words, dim: 0.6 }, "#FFFFFF", 3, 0);+ expect(draws[2].opacity).toBeCloseTo(0.6, 5);+ expect(wordDim({ style: "fill", dim: 0.6 })).toBe(0.6);+ expect(wordDim({ style: "fill" })).toBe(wordEffect("fill").before.opacity);+ });++ test("ends fully opaque all the way along", () => {+ const draws = wordDrawsAt(text, { ...words, dim: 0.6 }, "#FFFFFF", 3, 3);+ expect(draws.every((d) => d.opacity === 1)).toBe(true);+ });+});++describe("sample windows", () => {+ test("an effect that lands on the beat is one still per word", () => {+ const spans = wordSampleWindows("one two three", { style: "color" }, 3);+ expect(spans.length).toBe(3);+ expect(spans[0].start).toBe(0);+ expect(spans[2].end).toBe(3);+ });++ test("a ramping effect is cut finer, still covering the span with no gaps", () => {+ const spans = wordSampleWindows("one two three", { style: "build", times: [0, 1, 2] }, 3);+ expect(spans.length).toBeGreaterThan(3);+ expect(spans[0].start).toBe(0);+ expect(spans[spans.length - 1].end).toBe(3);+ for (let i = 1; i < spans.length; i++) expect(spans[i].start).toBe(spans[i - 1].end);+ });+});++describe("color blending", () => {+ test("runs between the two ends and stops at them", () => {+ expect(mixHex("#000000", "#FFFFFF", 0)).toBe("#000000");+ expect(mixHex("#000000", "#FFFFFF", 1)).toBe("#FFFFFF");+ expect(mixHex("#000000", "#FFFFFF", 0.5)).toBe("#808080");+ });+});++describe("a saved swell", () => {+ test("lands on the word's moment even where the effect resizes nothing", () => {+ // The picker used to offer a size on every treatment, so documents carry+ // one on effects whose own poses hold their size.+ const draws = wordDrawsAt("one two", { style: "box", scale: 1.5 }, "#FFFFFF", 2, 0);+ expect(draws[0].scale).toBe(1.5);+ expect(draws[1].scale).toBe(1);+ });++ test("opens its knob wherever a value is in play", () => {+ expect(wordKnobs(wordEffect("box")).size).toBe(false);+ expect(wordKnobs(wordEffect("box"), { scale: 1.5 }).size).toBe(true);+ expect(wordKnobs(wordEffect("color"), { dim: 0.5 }).dim).toBe(true);+ });++ test("leaves a word still growing into place at the size its effect asks", () => {+ const e = wordEffect("bloom");+ const draws = wordDrawsAt("one two", { style: "bloom", times: [0, 1] }, "#FFFFFF", 2, 0.999);+ expect(draws[1].scale).toBeCloseTo(e.before.scale!, 5);+ expect(draws[1].layoutScale).toBe(1);+ });+});++describe("sample slices", () => {+ test("are bounded when the sampler asks for a cap", () => {+ const words = { style: "rise", times: [0, 1, 2] };+ const free = wordSampleWindows("one two three", words, 3);+ const capped = wordSampleWindows("one two three", words, 3, 12, 2);+ expect(capped.length).toBeLessThan(free.length);+ expect(capped.length).toBeLessThanOrEqual(9);+ expect(capped[capped.length - 1].end).toBe(3);+ for (let i = 1; i < capped.length; i++) expect(capped[i].start).toBe(capped[i - 1].end);+ });+});