rvlib-shipkit 2.3.0 → 2.4.0

package/src/trailer/titles.ts

@@ -1,59 +1,230 @@
-// the trailer's drawn frames: one transparent PNG per title, cut to what it draws, and the card's ground, in the repo's
-// look (look.ts). Seven styles: logo, big, caption, corner, line, and a short's words (short, progress) in the look's
-// short face. Cached on what they draw, so a title edit draws one PNG
-import { createCanvas, GlobalFonts, loadImage, type Image, type SKRSContext2D } from '@napi-rs/canvas'
+// the trailer's drawn frames: one transparent PNG per title cut to what it draws, the frames of its entrance and exit
+// beside it, and the card's ground, in the repo's look (look.ts). Seven styles (logo, big, caption, corner, line, and a
+// short's words: short, progress), every word of text drawn by one painter (`ink`) that takes a title's face, size,
+// fill, outline, shadow and glow, and moves letter by letter. Cached on what they draw, so a title edit draws one title
+import { type Canvas, createCanvas, GlobalFonts, loadImage, type Image, type SKRSContext2D } from '@napi-rs/canvas'
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import sharp from 'sharp'
-import type { Title, TitleStyle } from './grammar.ts'
+import { hasFamily, registerFont } from './fonts.ts'
+import type { Title, TitleFx, TitlePlace, TitleStyle } from './grammar.ts'
 import { alpha, darker, shortLook, type TrailerLook } from './look.ts'
+import { type Glyph, inFrame, inFrames, outFrame, outFrames, STILL, type TitleFrame, type TitleMotion, type Whole } from './motion.ts'
 
 /** bump when a style's drawing changes: every cached title draws again */
-const DRAWING = 1
+const DRAWING = 3
 
-/** where a title stands: as `place` says; a short's caption in the frame's middle, a progress bar at the top; else
- *  the bottom */
-export type TitlePlace = 'top' | 'middle' | 'bottom'
-export const placeOf = (ti: Pick<Title, 'place' | 'style'>): TitlePlace => ti.place ?? (ti.style === 'short' ? 'middle' : ti.style === 'progress' ? 'top' : 'bottom')
+export { placeOf, type TitlePlace } from './grammar.ts'
 
 /** a short's words centred on these shares of the height, inside the phones' safe zone: under the lockup (`top`), the
  *  frame's middle, where the end card's lines stand (`bottom`) */
 export const SHORT_Y: Record<TitlePlace, number> = { top: 0.31, middle: 0.5, bottom: 0.645 }
 
-/** a title's PNG cut to what it draws, and where it sits on the frame: the stitch blends that box, never the whole frame */
+/** a title's PNG cut to what it draws, and where it sits on the frame: the stitch blends that box, never the whole
+ *  frame. `in` and `out` count the frames of its entrance and exit, drawn beside it (motion.ts `inFrames`,
+ *  `outFrames`) in the same box */
 export interface TitleImage {
     file: string
     x: number
     y: number
     w: number
     h: number
+    in?: number
+    out?: number
 }
 
 const registered = new Set<string>()
-/** the look's font files registered once under their families */
+/** the look's font files registered once under their families; a family the machine lacks fails loud */
 export function registerFace(look: TrailerLook, root: string): void {
     for (const f of [look.font, look.short.font]) {
-        if (!f.file || registered.has(f.file)) continue
-        const abs = join(root, f.file)
-        if (!existsSync(abs)) throw new Error(`the brand's trailer font ${f.file} is not in the repo`)
-        GlobalFonts.registerFromPath(abs, f.family)
-        registered.add(f.file)
+        if (f.file && !registered.has(f.file)) {
+            const abs = join(root, f.file)
+            if (!existsSync(abs)) throw new Error(`the brand's trailer font ${f.file} is not in the repo`)
+            GlobalFonts.registerFromPath(abs, f.family)
+            registered.add(f.file)
+        }
+        if (!hasFamily(f.family)) throw new Error(`the brand's trailer font family ${f.family} is not on this machine: give its file (trailer.font.file)`)
     }
 }
 
+/** a variable face takes its weight on its axis, a static one ignores it */
+const axis = (g: SKRSContext2D, weight: number): void => {
+    ;(g as unknown as { fontVariationSettings: string }).fontVariationSettings = `"wght" ${weight}`
+}
+
 export const face = (g: SKRSContext2D, look: TrailerLook, px: number, weight = look.font.weight): void => {
     const fam = look.font.family.includes(',') ? look.font.family : `"${look.font.family}"`
     g.font = `${weight} ${Math.round(px)}px ${fam}`
+    axis(g, weight)
+}
+
+/** how one run of words is painted: its face, its fill (a colour, or stops top to bottom), the accent of its `*word*`,
+ *  and the passes under the fill: a glow, an outline (its shadow under it), an inner stroke */
+export interface Paint {
+    family: string
+    weight: number
+    px: number
+    fill: string | string[]
+    key: string
+    outline: { w: number; color: string; dy?: number } | null
+    inner: { w: number; color: string } | null
+    shadow: { blur: number; dy: number; color: string } | null
+    glow: { blur: number; color: string } | null
+    spacing: number
+}
+
+/** the draw in progress: letter by letter when a letter move plays (`glyph`), the plates' and bands' alpha, and the
+ *  count of letters drawn so far */
+interface Ctx {
+    glyph?: (i: number, n: number) => Glyph
+    n: number
+    i: number
+    decor: number
+}
+const restCtx = (): Ctx => ({ n: 0, i: 0, decor: 1 })
+
+/** a plate, a band, a glow or the logo image: faded with the title's decor */
+function decor(cx: Ctx, g: SKRSContext2D, draw: () => void): void {
+    g.save()
+    g.globalAlpha *= cx.decor
+    draw()
+    g.restore()
+}
+
+function setFace(g: SKRSContext2D, p: Paint): void {
+    const fam = p.family.includes(',') ? p.family : `"${p.family}"`
+    g.font = `${p.weight} ${Math.round(p.px)}px ${fam}`
+    axis(g, p.weight)
+    ;(g as unknown as { letterSpacing: string }).letterSpacing = `${Math.round(p.spacing)}px`
+}
+
+/** the top and bottom of a line of `px` letters standing on `y` as the context's baseline reads it */
+function lineBox(g: SKRSContext2D, y: number, px: number): [number, number] {
+    const b = g.textBaseline
+    return b === 'top' ? [y, y + px] : b === 'middle' ? [y - px / 2, y + px / 2] : [y - px * 0.8, y + px * 0.2]
 }
 
-/** the text cut into lines no wider than `max`; `\n` breaks a line */
+/** THE painter: a line of words at (x, y), `*word*` in the accent; at rest as runs (the face's kerning whole), under a
+ *  letter move letter by letter, each about its own middle. Every pass covers every letter before the next pass, so an
+ *  outline never lies over a neighbour's fill */
+function ink(cx: Ctx, g: SKRSContext2D, p: Paint, text: string, x: number, y: number, align: 'center' | 'left' = 'center'): void {
+    setFace(g, p)
+    g.textAlign = 'left'
+    const parts = text.split('*').map((t, n) => ({ text: t, key: n % 2 === 1 })).filter((q) => q.text !== '')
+    const plain = parts.map((q) => q.text).join('')
+    const width = g.measureText(plain).width
+    const x0 = align === 'center' ? x - width / 2 : x
+    const at = (j: number): number => (j === 0 ? 0 : g.measureText(plain.slice(0, j)).width)
+    const units: { text: string; x: number; w: number; key: boolean; i: number | null }[] = []
+    let j = 0
+    for (const part of parts) {
+        if (cx.glyph) {
+            for (const ch of [...part.text]) {
+                units.push({ text: ch, x: x0 + at(j), w: g.measureText(ch).width, key: part.key, i: /\s/.test(ch) ? null : cx.i++ })
+                j += ch.length
+            }
+        } else {
+            units.push({ text: part.text, x: x0 + at(j), w: g.measureText(part.text).width, key: part.key, i: null })
+            cx.i += [...part.text.replace(/\s/g, '')].length
+            j += part.text.length
+        }
+    }
+    const [top, bottom] = lineBox(g, y, p.px)
+    const fill = (key: boolean): string | CanvasGradient => {
+        if (key) return p.key
+        if (typeof p.fill === 'string') return p.fill
+        const grad = g.createLinearGradient(0, top, 0, bottom)
+        p.fill.forEach((c, k) => grad.addColorStop(0.1 + (0.9 * k) / Math.max(1, p.fill.length - 1), c))
+        return grad as unknown as CanvasGradient
+    }
+    const pass = (draw: (u: (typeof units)[number]) => void): void => {
+        for (const u of units) {
+            if (u.text.trim() === '') continue
+            const s = u.i !== null && cx.glyph ? cx.glyph(u.i, cx.n) : null
+            if (s && s.a <= 0) continue
+            g.save()
+            if (s) {
+                g.globalAlpha *= s.a
+                const mx = u.x + u.w / 2
+                const my = (top + bottom) / 2
+                g.translate(mx + s.dx, my + s.dy)
+                g.scale(s.s, s.s)
+                g.translate(-mx, -my)
+            }
+            draw(u)
+            g.restore()
+        }
+    }
+    const shadowed = (sh: Paint['shadow']): void => {
+        if (!sh) return
+        g.shadowColor = sh.color
+        g.shadowBlur = sh.blur
+        g.shadowOffsetY = sh.dy
+    }
+    g.lineJoin = 'round'
+    if (p.glow) {
+        const gl = p.glow
+        pass((u) => {
+            g.shadowColor = gl.color
+            g.shadowBlur = gl.blur
+            g.fillStyle = gl.color
+            g.fillText(u.text, u.x, y)
+            g.fillText(u.text, u.x, y)
+        })
+    }
+    if (p.outline) {
+        const o = p.outline
+        pass((u) => {
+            shadowed(p.shadow)
+            g.lineWidth = o.w
+            g.strokeStyle = o.color
+            g.strokeText(u.text, u.x, y + (o.dy ?? 0))
+        })
+    }
+    if (p.inner) {
+        const o = p.inner
+        pass((u) => {
+            g.lineWidth = o.w
+            g.strokeStyle = o.color
+            g.strokeText(u.text, u.x, y)
+        })
+    }
+    pass((u) => {
+        if (!p.outline) shadowed(p.shadow)
+        g.fillStyle = fill(u.key) as string
+        g.fillText(u.text, u.x, y)
+    })
+}
+
+/** a title's own words over its style's paint: `k` scales the pixels a line writes (at a frame 1080 tall); a `font`
+ *  word's face draws at 400 unless its `weight` says */
+export function paintWith(base: Paint, fx: TitleFx | undefined, look: TrailerLook, k: number, family: string | null): Paint {
+    const p: Paint = { ...base }
+    if (family) {
+        p.family = family
+        p.weight = 400
+    }
+    if (!fx) return p
+    const c = (w: string | undefined, fallback: string): string => (w === undefined ? fallback : w === 'light' ? look.light : w === 'edge' ? look.edge : w === 'accent' ? look.accent : w)
+    if (fx.weight !== undefined) p.weight = fx.weight
+    if (fx.color !== undefined) p.fill = c(fx.color, look.light)
+    if (fx.gradient) p.fill = fx.gradient.map((x) => c(x, look.light))
+    if (fx.outline) p.outline = fx.outline.px === 0 ? null : { w: fx.outline.px * k, color: c(fx.outline.color, base.outline?.color ?? look.edge) }
+    // an inner stroke keeps its share of the outline it sits in, so a thinner outline still shows its edge
+    if (fx.outline && base.inner && base.outline) p.inner = p.outline ? { ...base.inner, w: (base.inner.w * p.outline.w) / base.outline.w } : null
+    if (fx.shadow) p.shadow = fx.shadow.px === 0 ? null : { blur: fx.shadow.px * k, dy: (fx.shadow.px * k) / 3, color: c(fx.shadow.color, alpha(look.edge, 0.6)) }
+    if (fx.glow) p.glow = fx.glow.px === 0 ? null : { blur: fx.glow.px * k, color: c(fx.glow.color, look.accent) }
+    return p
+}
+
+/** the text cut into lines no wider than `max` with the context's face; `\n` breaks a line; `*` marks take no room */
 function wrap(g: SKRSContext2D, text: string, max: number): string[] {
     const out: string[] = []
     for (const para of text.split('\\n')) {
         let line = ''
         for (const w of para.split(/\s+/).filter(Boolean)) {
             const next = line ? `${line} ${w}` : w
-            if (line && g.measureText(next).width > max) {
+            if (line && g.measureText(next.replaceAll('*', '')).width > max) {
                 out.push(line)
                 line = w
             } else line = next
@@ -81,245 +252,174 @@ function plate(g: SKRSContext2D, x: number, y: number, w: number, h: number, r:
     g.stroke()
 }
 
-/** words in the light on a thick edge outline, centred on `x`, its top at `y` */
-function outlined(g: SKRSContext2D, look: TrailerLook, text: string, x: number, y: number, size: number, k: number, fill: string): void {
-    face(g, look, size)
-    g.textAlign = 'center'
-    g.textBaseline = 'top'
-    g.lineJoin = 'round'
-    g.lineWidth = Math.round(size * 0.16)
-    g.strokeStyle = look.edge
-    g.shadowColor = alpha(look.edge, 0.5)
-    g.shadowBlur = 18 * k
-    g.shadowOffsetY = 4 * k
-    g.strokeText(text, x, y)
-    g.shadowColor = 'transparent'
-    g.fillStyle = fill
-    g.fillText(text, x, y)
-}
-
-/** a line of words, `*word*` in the accent, the whole line centred on `top` */
-function starred(g: SKRSContext2D, look: TrailerLook, line: string, W: number, top: number, size: number, k: number): void {
-    const words = line.split(' ').map((x) => ({ text: x.replaceAll('*', ''), key: x.includes('*') }))
-    face(g, look, size)
-    const space = g.measureText(' ').width
-    let x = (W - (words.reduce((n, w) => n + g.measureText(w.text).width, 0) + space * (words.length - 1))) / 2
-    for (const w of words) {
-        const ww = g.measureText(w.text).width
-        outlined(g, look, w.text, x + ww / 2, top, size, k, w.key ? look.accent : look.light)
-        x += ww + space
-    }
-}
-
-/** a short's caption: the words large, centred on `y` (a share of the height), a `\n` breaking the line, over a soft
- *  band of shade; sized by the frame's width */
-function drawShort(g: SKRSContext2D, look: TrailerLook, text: string, y: number, W: number, H: number): void {
-    const k = W / 1080
-    const size = Math.round(100 * k)
-    face(g, look, size)
-    const lines = text.split('\\n').flatMap((part) => wrap(g, part, W - 100 * k))
-    const lead = Math.round(size * 1.14)
-    const top = y * H - (lines.length * lead) / 2
-    const band = g.createLinearGradient(0, top - 140 * k, 0, top + lines.length * lead + 140 * k)
-    band.addColorStop(0, alpha(look.edge, 0))
-    band.addColorStop(0.5, alpha(look.edge, 0.42))
-    band.addColorStop(1, alpha(look.edge, 0))
-    g.fillStyle = band
-    g.fillRect(0, top - 140 * k, W, lines.length * lead + 280 * k)
-    lines.forEach((line, i) => starred(g, look, line, W, top + i * lead, size, k))
+/** a soft band of the edge's shade across the frame, behind words */
+function band(cx: Ctx, g: SKRSContext2D, look: TrailerLook, y0: number, y1: number, W: number, a: number): void {
+    decor(cx, g, () => {
+        const b = g.createLinearGradient(0, y0, 0, y1)
+        b.addColorStop(0, alpha(look.edge, 0))
+        b.addColorStop(0.5, alpha(look.edge, a))
+        b.addColorStop(1, alpha(look.edge, 0))
+        g.fillStyle = b
+        g.fillRect(0, y0, W, y1 - y0)
+    })
 }
 
-/** a progress step: its name centred on `y` (a share of the height), a row of notches under it, `i` of `n` filled in
- *  the accent, the newest lit; measured at 1080 px wide */
-function drawProgress(g: SKRSContext2D, look: TrailerLook, name: string, i: number, n: number, y: number, W: number, H: number): void {
-    const k = W / 1080
-    const size = Math.round(84 * k)
-    const lead = Math.round(size * 1.14)
-    const [width, gap, notch, under] = [700 * k, 14 * k, 28 * k, 24 * k]
-    const top = y * H - (lead + under + notch) / 2
-    const band = g.createLinearGradient(0, top - 110 * k, 0, top + lead + under + notch + 110 * k)
-    band.addColorStop(0, alpha(look.edge, 0))
-    band.addColorStop(0.5, alpha(look.edge, 0.36))
-    band.addColorStop(1, alpha(look.edge, 0))
-    g.fillStyle = band
-    g.fillRect(0, top - 110 * k, W, lead + under + notch + 220 * k)
-    starred(g, look, name, W, top, size, k)
-    const nw = (width - gap * (n - 1)) / n
-    const bar = top + lead + under
-    for (let j = 0; j < n; j++) {
-        const nx = (W - width) / 2 + j * (nw + gap)
-        g.save()
-        if (j === i - 1) {
-            g.shadowColor = alpha(look.accent, 0.9)
-            g.shadowBlur = 22 * k
-        }
-        g.beginPath()
-        g.roundRect(nx, bar, nw, notch, notch / 2)
-        g.fillStyle = j < i ? look.accent : alpha(look.light, 0.32)
-        g.fill()
-        g.restore()
-        g.lineWidth = 5 * k
-        g.strokeStyle = look.edge
-        g.beginPath()
-        g.roundRect(nx, bar, nw, notch, notch / 2)
-        g.stroke()
-    }
+/** what a title draws: its words, style, place, look, logo, step, its own look words and the family its `font` word
+ *  registered (null: the look's face) */
+export interface TitleDraw {
+    text: string
+    style: TitleStyle
+    place: TitlePlace
+    look: TrailerLook
+    logo: Image | null
+    step?: Title['step']
+    fx?: TitleFx
+    family: string | null
 }
 
-/** one title over a transparent frame. A title's `\n` breaks its line; a logo's second line is its subtitle */
-export function drawTitle(text: string, style: TitleStyle, [W, H]: readonly [number, number], place: TitlePlace, look: TrailerLook, logo: Image | null, step?: Title['step']): Buffer {
-    const top = place === 'top'
-    const c = createCanvas(W, H)
-    const g = c.getContext('2d')
+/** one title over a transparent frame, at rest or under a letter move (`cx`). A title's `\n` breaks its line; a logo's
+ *  second line is its subtitle */
+function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, number], cx: Ctx): void {
+    const { text, style, look } = d
+    const top = d.place === 'top'
     const k = Math.min(H, W) / 1080
+    const own = (p: Paint): Paint => paintWith(p, d.fx, look, k, d.family)
     g.textAlign = 'center'
     g.textBaseline = 'middle'
     const [first = '', ...more] = text.split('\\n')
+    const base = (px: number, weight: number, l: TrailerLook = look): Paint => ({ family: l.font.family, weight, px, fill: l.light, key: l.accent, outline: null, inner: null, shadow: null, glow: null, spacing: 0 })
     if (style === 'short' || style === 'progress') {
         const sl = shortLook(look)
-        if (style === 'short') drawShort(g, sl, text, SHORT_Y[place], W, H)
-        else drawProgress(g, sl, text, step?.i ?? 1, step?.n ?? 1, SHORT_Y[place], W, H)
+        const ks = W / 1080
+        const size = (d.fx?.size ?? (style === 'short' ? 100 : 84)) * ks
+        const p = paintWith({ ...base(size, sl.font.weight, sl), outline: { w: Math.round(size * 0.16), color: sl.edge }, shadow: { blur: 18 * ks, dy: 4 * ks, color: alpha(sl.edge, 0.5) } }, d.fx, sl, ks, d.family)
+        const y = SHORT_Y[d.place]
+        g.textBaseline = 'top'
+        setFace(g, p)
+        const lead = Math.round(size * 1.14)
+        if (style === 'short') {
+            const lines = text.split('\\n').flatMap((part) => wrap(g, part, W - 100 * ks))
+            const t0 = y * H - (lines.length * lead) / 2
+            band(cx, g, sl, t0 - 140 * ks, t0 + lines.length * lead + 140 * ks, W, 0.42)
+            lines.forEach((line, i) => ink(cx, g, p, line, W / 2, t0 + i * lead))
+        } else {
+            const [i, n] = [d.step?.i ?? 1, d.step?.n ?? 1]
+            const [width, gap, notch, under] = [700 * ks, 14 * ks, 28 * ks, 24 * ks]
+            const t0 = y * H - (lead + under + notch) / 2
+            band(cx, g, sl, t0 - 110 * ks, t0 + lead + under + notch + 110 * ks, W, 0.36)
+            ink(cx, g, p, text, W / 2, t0)
+            const nw = (width - gap * (n - 1)) / n
+            const bar = t0 + lead + under
+            decor(cx, g, () => {
+                for (let j = 0; j < n; j++) {
+                    const nx = (W - width) / 2 + j * (nw + gap)
+                    g.save()
+                    if (j === i - 1) {
+                        g.shadowColor = alpha(sl.accent, 0.9)
+                        g.shadowBlur = 22 * ks
+                    }
+                    g.beginPath()
+                    g.roundRect(nx, bar, nw, notch, notch / 2)
+                    g.fillStyle = j < i ? sl.accent : alpha(sl.light, 0.32)
+                    g.fill()
+                    g.restore()
+                    g.lineWidth = 5 * ks
+                    g.strokeStyle = sl.edge
+                    g.beginPath()
+                    g.roundRect(nx, bar, nw, notch, notch / 2)
+                    g.stroke()
+                }
+            })
+        }
     } else if (style === 'logo') {
-        // the logo image over the word, the word in the accent over the edge and its soft drop, the subtitle spaced under it
-        const glow = g.createRadialGradient(W / 2, H * 0.48, 0, W / 2, H * 0.48, Math.max(W, H) * 0.45)
-        glow.addColorStop(0, alpha(look.edge, 0.45))
-        glow.addColorStop(1, alpha(look.edge, 0))
-        g.fillStyle = glow
-        g.fillRect(0, 0, W, H)
-        const markH = logo ? Math.min(H * 0.3, W * 0.3) : 0
-        face(g, look, 170 * k, 900)
-        const kl = Math.min(1, (W * 0.78) / (g.measureText(first).width + 16 * k))
-        const px = 170 * k * kl
-        const subPx = 34 * k * Math.max(kl, 0.7)
+        // the logo image over the word, the word in a light to accent ramp over a dropped edge, the subtitle spaced under
+        decor(cx, g, () => {
+            const glow = g.createRadialGradient(W / 2, H * 0.48, 0, W / 2, H * 0.48, Math.max(W, H) * 0.45)
+            glow.addColorStop(0, alpha(look.edge, 0.45))
+            glow.addColorStop(1, alpha(look.edge, 0))
+            g.fillStyle = glow
+            g.fillRect(0, 0, W, H)
+        })
+        const S = d.fx?.size ?? 170
+        const markH = d.logo ? Math.min(H * 0.3, W * 0.3) : 0
+        setFace(g, own(base(S * k, 900)))
+        const kl = Math.min(1, (W * 0.78) / (g.measureText(first.replaceAll('*', '')).width + 16 * k))
+        const px = S * k * kl
+        const subPx = S * 0.2 * k * Math.max(kl, 0.7)
         const block = markH + (markH ? px * 0.25 : 0) + (first ? px : 0) + (more.length ? subPx * 2 : 0)
         let y = H * 0.48 - block / 2
+        const logo = d.logo
         if (logo) {
             const w = (logo.width / logo.height) * markH
-            g.save()
-            g.shadowColor = alpha(look.edge, 0.6)
-            g.shadowBlur = 30 * k
-            g.drawImage(logo, W / 2 - w / 2, y, w, markH)
-            g.restore()
+            const at = y
+            decor(cx, g, () => {
+                g.shadowColor = alpha(look.edge, 0.6)
+                g.shadowBlur = 30 * k
+                g.drawImage(logo, W / 2 - w / 2, at, w, markH)
+            })
             y += markH + px * 0.25
         }
         if (first) {
-            const cy = y + px / 2
-            face(g, look, px, 900)
-            g.save()
-            g.shadowColor = alpha(look.edge, 0.6)
-            g.shadowBlur = 30 * k
-            g.shadowOffsetY = 12 * k
-            g.lineJoin = 'round'
-            g.lineWidth = 16 * k * kl
-            g.strokeStyle = look.edge
-            g.strokeText(first, W / 2, cy + 3 * k)
-            g.restore()
-            const grad = g.createLinearGradient(0, cy - px / 2, 0, cy + px / 2)
-            grad.addColorStop(0.1, look.light)
-            grad.addColorStop(0.55, look.accent)
-            grad.addColorStop(1, darker(look.accent, 0.2))
-            g.fillStyle = grad
-            g.fillText(first, W / 2, cy)
+            const p = own({ ...base(px, 900), fill: [look.light, look.accent, darker(look.accent, 0.2)], outline: { w: 16 * k * kl, color: look.edge, dy: 3 * k }, shadow: { blur: 30 * k, dy: 12 * k, color: alpha(look.edge, 0.6) } })
+            ink(cx, g, p, first, W / 2, y + px / 2)
             y += px
         }
         if (more.length) {
-            face(g, look, subPx, 800)
-            ;(g as unknown as { letterSpacing: string }).letterSpacing = `${Math.round(subPx * 0.42)}px`
-            g.shadowColor = alpha(look.edge, 0.9)
-            g.shadowBlur = subPx * 0.42
-            g.fillStyle = look.light
-            g.fillText(more.join(' ').toUpperCase(), W / 2, y + subPx)
+            const sub: Paint = { ...base(subPx, d.fx?.weight ?? (d.family ? 400 : 800)), ...(d.family ? { family: d.family } : {}), spacing: subPx * 0.42, shadow: { blur: subPx * 0.42, dy: 0, color: alpha(look.edge, 0.9) } }
+            ink(cx, g, sub, more.join(' ').toUpperCase(), W / 2 + (subPx * 0.42) / 2, y + subPx)
         }
     } else if (style === 'big') {
-        // a strong display line in the upper third: light words in a thick edge outline, an accent under-glow
-        const px = 112 * k
-        face(g, look, px, 900)
+        // a strong display line in the upper third: light words in a thick edge outline, an accent stroke inside it
+        const p = own({ ...base((d.fx?.size ?? 112) * k, 900), outline: { w: 22 * k, color: look.edge }, inner: { w: 8 * k, color: look.accent }, shadow: { blur: 26 * k, dy: 10 * k, color: alpha(look.edge, 0.55) } })
+        setFace(g, p)
         const lines = wrap(g, [first, ...more].join(' '), W * 0.82)
-        lines.forEach((l, i) => {
-            const y = H * 0.26 + (i - (lines.length - 1) / 2) * px * 1.12
-            g.save()
-            g.shadowColor = alpha(look.edge, 0.55)
-            g.shadowBlur = 26 * k
-            g.shadowOffsetY = 10 * k
-            g.lineJoin = 'round'
-            g.lineWidth = 22 * k
-            g.strokeStyle = look.edge
-            g.strokeText(l, W / 2, y)
-            g.restore()
-            g.lineWidth = 8 * k
-            g.strokeStyle = look.accent
-            g.strokeText(l, W / 2, y)
-            g.fillStyle = look.light
-            g.fillText(l, W / 2, y)
-        })
+        lines.forEach((l, i) => ink(cx, g, p, l, W / 2, H * 0.26 + (i - (lines.length - 1) / 2) * p.px * 1.12))
     } else if (style === 'line') {
         // a tagline: light words centred low on a soft dark band, no plate, the frame stays the picture
-        const px = 64 * k
-        face(g, look, px)
+        const p = own({ ...base((d.fx?.size ?? 64) * k, look.font.weight), outline: { w: 9 * k, color: alpha(look.edge, 0.82) }, shadow: { blur: 18 * k, dy: 4 * k, color: alpha(look.edge, 0.85) } })
+        setFace(g, p)
         const lines = more.length > 0 ? [first, ...more] : wrap(g, first, W * 0.7)
-        const lh = px * 1.3
+        const lh = p.px * 1.3
         const cy = top ? H * 0.2 : H * 0.8
         const span = lh * lines.length + 80 * k
-        const band = g.createLinearGradient(0, cy - span, 0, cy + span)
-        band.addColorStop(0, alpha(look.edge, 0))
-        band.addColorStop(0.5, alpha(look.edge, 0.42))
-        band.addColorStop(1, alpha(look.edge, 0))
-        g.fillStyle = band
-        g.fillRect(0, cy - span, W, 2 * span)
-        lines.forEach((l, i) => {
-            const y = cy + (i - (lines.length - 1) / 2) * lh
-            // `*word*` is a key word in the accent, the rest light
-            const parts = l.split('*').map((t, n) => ({ text: t, key: n % 2 === 1 }))
-            const plain = parts.map((p) => p.text).join('')
-            let x = W / 2 - g.measureText(plain).width / 2
-            g.textAlign = 'left'
-            g.save()
-            g.shadowColor = alpha(look.edge, 0.85)
-            g.shadowBlur = 18 * k
-            g.shadowOffsetY = 4 * k
-            g.lineJoin = 'round'
-            g.lineWidth = 9 * k
-            g.strokeStyle = alpha(look.edge, 0.82)
-            g.strokeText(plain, x, y)
-            g.restore()
-            for (const p of parts) {
-                g.fillStyle = p.key ? look.accent : look.light
-                g.fillText(p.text, x, y)
-                x += g.measureText(p.text).width
-            }
-            g.textAlign = 'center'
-        })
+        band(cx, g, look, cy - span, cy + span, W, 0.42)
+        lines.forEach((l, i) => ink(cx, g, p, l, W / 2, cy + (i - (lines.length - 1) / 2) * lh))
     } else if (style === 'caption') {
         // the plate: its fill, its outline, its ink, an accent dot leading it
-        const px = 46 * k
-        face(g, look, px, 900)
+        const p = own({ ...base((d.fx?.size ?? 46) * k, 900), fill: look.plate.ink })
+        setFace(g, p)
         const lines = wrap(g, [first, ...more].join(' '), W * 0.66)
-        const lh = px * 1.28
+        const lh = p.px * 1.28
         const dot = 14 * k
-        const bw = Math.max(...lines.map((l) => g.measureText(l).width)) + 96 * k + dot * 2
+        const bw = Math.max(...lines.map((l) => g.measureText(l.replaceAll('*', '')).width)) + 96 * k + dot * 2
         const bh = lines.length * lh + 34 * k
         const cy = top ? H * 0.12 : H * 0.83
-        plate(g, W / 2 - bw / 2, cy - bh / 2, bw, bh, Math.min(bh / 2, 30 * k), k, look.plate.fill, look.plate.line, look.edge)
-        g.fillStyle = look.accent
-        g.beginPath()
-        g.arc(W / 2 - bw / 2 + 34 * k, cy, dot / 2 + 2 * k, 0, Math.PI * 2)
-        g.fill()
-        g.fillStyle = look.plate.ink
-        lines.forEach((l, i) => g.fillText(l, W / 2 + dot, cy + (i - (lines.length - 1) / 2) * lh + 2 * k))
+        decor(cx, g, () => {
+            plate(g, W / 2 - bw / 2, cy - bh / 2, bw, bh, Math.min(bh / 2, 30 * k), k, look.plate.fill, look.plate.line, look.edge)
+            g.fillStyle = look.accent
+            g.beginPath()
+            g.arc(W / 2 - bw / 2 + 34 * k, cy, dot / 2 + 2 * k, 0, Math.PI * 2)
+            g.fill()
+        })
+        lines.forEach((l, i) => ink(cx, g, p, l, W / 2 + dot, cy + (i - (lines.length - 1) / 2) * lh + 2 * k))
     } else {
         // corner: a word chip, bottom left (top left when placed at the top)
-        const px = 54 * k
-        face(g, look, px, 900)
+        const p = own({ ...base((d.fx?.size ?? 54) * k, 900), fill: look.chip.ink })
+        setFace(g, p)
         const t = [first, ...more].join(' ')
-        const w = g.measureText(t).width + 72 * k
-        const h = px * 1.5
+        const w = g.measureText(t.replaceAll('*', '')).width + 72 * k
+        const h = p.px * 1.5
         const x = 72 * k
         const y = top ? 80 * k : H - 80 * k - h
-        plate(g, x, y, w, h, h / 2, k, look.chip.fill, darker(look.chip.fill, 0.15), look.edge)
-        g.fillStyle = look.chip.ink
-        g.textAlign = 'left'
-        g.fillText(t, x + 36 * k, y + h / 2 + 2 * k)
+        decor(cx, g, () => plate(g, x, y, w, h, h / 2, k, look.chip.fill, darker(look.chip.fill, 0.15), look.edge))
+        ink(cx, g, p, t, x + 36 * k, y + h / 2 + 2 * k, 'left')
     }
+}
+
+/** one title at rest over a transparent frame, as a PNG */
+export function drawTitle(text: string, style: TitleStyle, size: readonly [number, number], place: TitlePlace, look: TrailerLook, logo: Image | null, step?: Title['step'], fx?: TitleFx, family: string | null = null): Buffer {
+    const c = createCanvas(size[0], size[1])
+    drawInto(c.getContext('2d'), { text, style, place, look, logo, family, ...(step ? { step } : {}), ...(fx ? { fx } : {}) }, size, restCtx())
     return Buffer.from(c.toBuffer('image/png'))
 }
 
@@ -337,32 +437,148 @@ export function drawCard([W, H]: readonly [number, number], look: TrailerLook):
 
 const key = (parts: unknown): string => new Bun.CryptoHasher('sha1').update(JSON.stringify([DRAWING, parts])).digest('hex').slice(0, 16)
 
+const fileState = (f: string | null, root: string): unknown => {
+    if (!f) return null
+    const abs = f.startsWith('/') ? f : join(root, f)
+    return existsSync(abs) ? [f, statSync(abs).size, statSync(abs).mtimeMs] : [f, 'missing']
+}
+
 /** what the look reads from disk, as it stands: a new font or logo file draws every title again */
-export const lookFiles = (look: TrailerLook, root: string): unknown[] =>
-    [look.font.file, look.logo, look.short.font.file].map((f) => {
-        if (!f) return null
-        const abs = join(root, f)
-        return existsSync(abs) ? [f, statSync(abs).size, statSync(abs).mtimeMs] : [f, 'missing']
-    })
+export const lookFiles = (look: TrailerLook, root: string): unknown[] => [look.font.file, look.logo, look.short.font.file].map((f) => fileState(f, root))
+
+/** what one title draws: its words, style, frame, place, look, step, its own look words, its moves in frames, and the
+ *  font file its `font` word names */
+export interface TitleRequest {
+    root: string
+    text: string
+    style: TitleStyle
+    size: readonly [number, number]
+    place: TitlePlace
+    look: TrailerLook
+    step?: Title['step']
+    fx?: TitleFx
+    motion?: TitleMotion
+    /** the absolute file of its `font` word (a repo file or the cached Google face), null for the look's face */
+    font?: string | null
+}
+
+const keyParts = (r: TitleRequest): unknown[] => [r.text, r.style, r.size, r.place, r.look, lookFiles(r.look, r.root), r.step ? [r.step.i, r.step.n] : null, r.fx ?? null, r.motion ?? null, fileState(r.font ?? null, r.root)]
 
 /** a title's PNG file, named by what it draws */
-export const titleFile = (dir: string, root: string, text: string, style: TitleStyle, size: readonly [number, number], place: TitlePlace, look: TrailerLook, step?: Title['step']): string =>
-    join(dir, `title-${key([text, style, size, place, look, lookFiles(look, root), ...(step ? [step.i, step.n] : [])])}.png`)
+export const titleFile = (dir: string, r: TitleRequest): string => join(dir, `title-${key(keyParts(r))}.png`)
 
-/** the PNG of a title, drawn once per text, style, frame, place, look and step; its box on the frame in `<file>.json` beside it */
-export async function titlePng(dir: string, root: string, text: string, style: TitleStyle, size: readonly [number, number], place: TitlePlace, look: TrailerLook, step?: Title['step']): Promise<TitleImage> {
-    const file = titleFile(dir, root, text, style, size, place, look, step)
+/** the alpha box of a frame's pixels, null when it draws nothing */
+function boxOf(data: Uint8ClampedArray, W: number, H: number): { x: number; y: number; w: number; h: number } | null {
+    let [x0, y0, x1, y1] = [W, H, -1, -1]
+    for (let y = 0; y < H; y++) {
+        const row = y * W * 4
+        for (let x = 0; x < W; x++)
+            if (data[row + x * 4 + 3]! > 0) {
+                if (x < x0) x0 = x
+                if (x > x1) x1 = x
+                if (y < y0) y0 = y
+                y1 = y
+            }
+    }
+    return x1 < 0 ? null : { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 }
+}
+
+/** the rows of `box` out of a frame W wide */
+function crop(data: Uint8ClampedArray, W: number, box: { x: number; y: number; w: number; h: number }): Uint8ClampedArray {
+    const out = new Uint8ClampedArray(box.w * box.h * 4)
+    for (let y = 0; y < box.h; y++) out.set(data.subarray(((box.y + y) * W + box.x) * 4, ((box.y + y) * W + box.x + box.w) * 4), y * box.w * 4)
+    return out
+}
+
+/** the drawn title moved as a whole: its alpha, offset, scale and turn about its box's middle, a blur, a wipe from the
+ *  left with a soft edge */
+function moved(g: SKRSContext2D, src: Canvas, w: Whole, mid: readonly [number, number], box: { x: number; w: number }, k: number): void {
+    g.save()
+    g.globalAlpha = w.a
+    if (w.blur > 0.3) g.filter = `blur(${w.blur.toFixed(2)}px)`
+    g.translate(mid[0] + w.dx, mid[1] + w.dy)
+    g.rotate(w.rot)
+    g.scale(w.s, w.s)
+    g.translate(-mid[0], -mid[1])
+    g.drawImage(src, 0, 0)
+    g.restore()
+    if (w.wipe < 1) {
+        // the wipe's soft edge: what it shows stays, a feather of a tenth of the box fades, the rest goes
+        const feather = Math.max(24 * k, box.w * 0.1)
+        const edge = box.x + w.wipe * (box.w + feather)
+        const m = g.createLinearGradient(edge - feather, 0, edge, 0)
+        m.addColorStop(0, 'rgba(0,0,0,1)')
+        m.addColorStop(1, 'rgba(0,0,0,0)')
+        g.save()
+        g.globalCompositeOperation = 'destination-in'
+        g.fillStyle = m
+        g.fillRect(0, 0, g.canvas.width, g.canvas.height)
+        g.restore()
+    }
+}
+
+/** the PNG of a title at rest and the frames of its entrance and exit, all cut to one box, drawn once per what they
+ *  draw; the box and the frame counts in `<file>.json` beside it */
+export async function titlePng(dir: string, r: TitleRequest): Promise<TitleImage> {
+    const file = titleFile(dir, r)
     const where = `${file}.json`
     if (!existsSync(file) || !existsSync(where)) {
         mkdirSync(dir, { recursive: true })
-        registerFace(look, root)
-        const logo = style === 'logo' && look.logo && existsSync(join(root, look.logo)) ? await loadImage(join(root, look.logo)) : null
-        const { data, info } = await sharp(drawTitle(text, style, size, place, look, logo, step)).trim({ threshold: 0 }).png().toBuffer({ resolveWithObject: true })
-        writeFileSync(file, data)
-        writeFileSync(where, JSON.stringify({ x: -(info.trimOffsetLeft ?? 0), y: -(info.trimOffsetTop ?? 0), w: info.width, h: info.height }))
+        registerFace(r.look, r.root)
+        const family = r.font ? registerFont(r.font) : null
+        const logo = r.style === 'logo' && r.look.logo && existsSync(join(r.root, r.look.logo)) ? await loadImage(join(r.root, r.look.logo)) : null
+        const [W, H] = r.size
+        const k = Math.min(W, H) / 1080
+        const d: TitleDraw = { text: r.text, style: r.style, place: r.place, look: r.look, logo, family, ...(r.step ? { step: r.step } : {}), ...(r.fx ? { fx: r.fx } : {}) }
+        const still = createCanvas(W, H)
+        const rest = restCtx()
+        drawInto(still.getContext('2d'), d, r.size, rest)
+        const n = rest.i
+        const stillData = still.getContext('2d').getImageData(0, 0, W, H).data
+        const at = boxOf(stillData, W, H) ?? { x: 0, y: 0, w: 1, h: 1 }
+        const mid = [at.x + at.w / 2, at.y + at.h / 2] as const
+        const px = (r.fx?.size ?? 80) * k
+        const m = r.motion ?? { in: { kind: 'none', frames: 0 }, out: { kind: 'none', frames: 0 } }
+        const frameOf = (f: TitleFrame): Uint8ClampedArray => {
+            const c = createCanvas(W, H)
+            const g = c.getContext('2d')
+            let src: Canvas = still
+            if (f.glyph) {
+                src = createCanvas(W, H)
+                drawInto(src.getContext('2d'), d, r.size, { glyph: f.glyph, n, i: 0, decor: f.decor })
+            }
+            if (f.whole === STILL) g.drawImage(src, 0, 0)
+            else moved(g, src, f.whole, mid, at, k)
+            return g.getImageData(0, 0, W, H).data
+        }
+        // each frame kept as its own box only: a logo's frames are each the whole frame
+        const frames: { box: ReturnType<typeof boxOf>; data: Uint8ClampedArray; name: string }[] = []
+        const keep = (data: Uint8ClampedArray, name: string): void => {
+            const box = boxOf(data, W, H)
+            frames.push({ box, data: box ? crop(data, W, box) : new Uint8ClampedArray(0), name })
+        }
+        const nth = (pattern: string, j: number): string => pattern.replace('%04d', String(j).padStart(4, '0'))
+        keep(stillData, file)
+        const inKind = m.in.kind
+        for (let j = 0; j < m.in.frames; j++) keep(frameOf(inFrame(inKind, j, m.in.frames, r.size, px)), nth(inFrames(file), j))
+        for (let j = 0; j < m.out.frames; j++) keep(frameOf(outFrame(m.out.kind, j, m.out.frames, r.size, px)), nth(outFrames(file), j))
+        // one box for every frame, even sides for the encoder
+        const boxes = frames.flatMap((f) => (f.box ? [f.box] : []))
+        const x0 = Math.min(...boxes.map((b) => b.x))
+        const y0 = Math.min(...boxes.map((b) => b.y))
+        const x1 = Math.max(...boxes.map((b) => b.x + b.w))
+        const y1 = Math.max(...boxes.map((b) => b.y + b.h))
+        const u = boxes.length ? { x: x0, y: y0, w: Math.min(W - x0, x1 - x0 + ((x1 - x0) % 2)), h: Math.min(H - y0, y1 - y0 + ((y1 - y0) % 2)) } : { x: 0, y: 0, w: 2, h: 2 }
+        await Promise.all(
+            frames.map(async (f) => {
+                const out = new Uint8ClampedArray(u.w * u.h * 4)
+                if (f.box) for (let y = 0; y < f.box.h; y++) out.set(f.data.subarray(y * f.box.w * 4, (y + 1) * f.box.w * 4), ((f.box.y - u.y + y) * u.w + (f.box.x - u.x)) * 4)
+                writeFileSync(f.name, await sharp(Buffer.from(out.buffer), { raw: { width: u.w, height: u.h, channels: 4 } }).png({ compressionLevel: 1, adaptiveFiltering: false }).toBuffer())
+            }),
+        )
+        writeFileSync(where, JSON.stringify({ x: u.x, y: u.y, w: u.w, h: u.h, in: m.in.frames, out: m.out.frames }))
     }
-    const { x, y, w, h } = JSON.parse(readFileSync(where, 'utf8')) as TitleImage
-    return { file, x, y, w, h }
+    return { file, ...(JSON.parse(readFileSync(where, 'utf8')) as Omit<TitleImage, 'file'>) }
 }
 
 /** the card's ground's PNG file for a frame and a look */