rvlib-shipkit 2.1.1 → 2.2.0

package/src/trailer/vertical-draw.ts

@@ -0,0 +1,286 @@
+// what the vertical short draws itself, full frame pngs ffmpeg lays over the cut (vertical.ts): the lockup at each
+// scale of its pop with the watermark, the watermark alone for the outro, the end card and its image apart (it hops
+// in). In the look's colours and face, sized by the frame's width; each cached on what it draws
+import { type Canvas, createCanvas, type Image, loadImage, type SKRSContext2D } from '@napi-rs/canvas'
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { alpha, luminance, type TrailerLook } from './look.ts'
+import { face, lookFiles, registerFace } from './titles.ts'
+import { POP_S, popScale, SAFE_BOTTOM, SAFE_TOP, type VerticalLook } from './vertical.ts'
+
+/** bump when a drawing changes: every cached frame draws again */
+const DRAWING = 1
+/** a wordmark's width in the lockup at 1080 px wide: small, and still read on a phone */
+const LOCKUP_W = 560
+const WATERMARK = { margin: 40, height: 72 } as const
+
+type Images = Map<string, Image>
+
+/** the images a look names, loaded once; a path the brand names that is not in the repo fails loud */
+async function images(root: string, vl: VerticalLook): Promise<Images> {
+    const out: Images = new Map()
+    for (const p of [vl.lockup?.image, vl.lockup?.logo, vl.watermark?.image, vl.end?.image]) {
+        if (!p || out.has(p)) continue
+        const abs = join(root, p)
+        if (!existsSync(abs)) throw new Error(`the brand's vertical look names ${p}, which is not in the repo (.shipkit/identity/brand.ts, trailer)`)
+        out.set(p, await loadImage(abs))
+    }
+    return out
+}
+
+const key = (parts: unknown): string => new Bun.CryptoHasher('sha1').update(JSON.stringify([DRAWING, parts])).digest('hex').slice(0, 16)
+
+/** what the drawings read from disk, as it stands: a new image draws again */
+const files = (root: string, look: TrailerLook, vl: VerticalLook): unknown[] => [
+    lookFiles(look, root),
+    ...[vl.lockup?.image, vl.watermark?.image, vl.end?.image].map((p) => (p && existsSync(join(root, p)) ? [p, statSync(join(root, p)).size, statSync(join(root, p)).mtimeMs] : p)),
+]
+
+const png = (c: Canvas, file: string): string => {
+    writeFileSync(file, c.toBuffer('image/png'))
+    return file
+}
+
+/** a line of words in the face and `fill`, `*word*` in the accent, centred on x */
+function words(g: SKRSContext2D, look: TrailerLook, text: string, cx: number, cy: number, px: number, fill: string): void {
+    face(g, look, px, 900)
+    const parts = text.split('*').map((t, i) => ({ t, key: i % 2 === 1 }))
+    let x = cx - g.measureText(parts.map((p) => p.t).join('')).width / 2
+    g.textAlign = 'left'
+    g.textBaseline = 'middle'
+    for (const p of parts) {
+        g.fillStyle = p.key ? look.accent : fill
+        g.fillText(p.t, x, cy)
+        x += g.measureText(p.t).width
+    }
+}
+
+/** a name as the `logo` title draws it: the edge under it, light into the accent down its height */
+function name(g: SKRSContext2D, look: TrailerLook, text: string, x: number, cy: number, px: number, align: 'left' | 'center'): void {
+    face(g, look, px, 900)
+    g.textAlign = align
+    g.textBaseline = 'middle'
+    g.save()
+    g.lineJoin = 'round'
+    g.lineWidth = px * 0.14
+    g.strokeStyle = look.edge
+    g.shadowColor = alpha(look.edge, 0.55)
+    g.shadowBlur = px * 0.25
+    g.shadowOffsetY = px * 0.06
+    g.strokeText(text, x, cy)
+    g.restore()
+    const grad = g.createLinearGradient(0, cy - px / 2, 0, cy + px / 2)
+    grad.addColorStop(0.1, look.light)
+    grad.addColorStop(0.6, look.accent)
+    g.fillStyle = grad
+    g.fillText(text, x, cy)
+}
+
+/** the lockup from `top` at `scale`, centred: the wordmark, else the logo and the name in a row; its tag under it.
+ *  Returns where it ends */
+function lockup(g: SKRSContext2D, look: TrailerLook, lk: NonNullable<VerticalLook['lockup']>, img: Images, W: number, top: number, scale: number): number {
+    const k = (W / 1080) * scale
+    let y = top
+    const mark = lk.image ? img.get(lk.image) : undefined
+    if (mark) {
+        const w = LOCKUP_W * k
+        const h = (w * mark.height) / mark.width
+        g.drawImage(mark, (W - w) / 2, y, w, h)
+        y += h + 10 * k
+    } else {
+        const logo = lk.logo ? img.get(lk.logo) : undefined
+        const iconH = logo ? 112 * k : 0
+        const iconW = logo ? (iconH * logo.width) / logo.height : 0
+        const gap = logo ? 26 * k : 0
+        face(g, look, 88 * k, 900)
+        const room = W * 0.84 - iconW - gap
+        const px = 88 * k * Math.min(1, room / Math.max(1, g.measureText(lk.name).width))
+        face(g, look, px, 900)
+        const tw = g.measureText(lk.name).width
+        const rowH = Math.max(iconH, px * 1.15)
+        const x0 = (W - (iconW + gap + tw)) / 2
+        if (logo) {
+            g.save()
+            g.shadowColor = alpha(look.edge, 0.6)
+            g.shadowBlur = 20 * k
+            g.drawImage(logo, x0, y + (rowH - iconH) / 2, iconW, iconH)
+            g.restore()
+        }
+        name(g, look, lk.name, x0 + iconW + gap, y + rowH / 2, px, 'left')
+        y += rowH + 14 * k
+    }
+    if (!lk.tag) return y
+    const size = 30 * k
+    face(g, look, size, 900)
+    const tag = lk.tag.toUpperCase()
+    const spacing = 3 * k
+    const tw = [...tag].reduce((n, ch) => n + g.measureText(ch).width + spacing, -spacing)
+    const [pw, ph] = [tw + size * 1.2, Math.round(size * 1.5)]
+    const x = (W - pw) / 2
+    g.fillStyle = look.chip.fill
+    g.strokeStyle = look.edge
+    g.lineWidth = 4 * k
+    g.beginPath()
+    g.roundRect(x, y, pw, ph, ph / 2)
+    g.fill()
+    g.stroke()
+    g.fillStyle = look.chip.ink
+    g.textAlign = 'left'
+    g.textBaseline = 'middle'
+    let tx = x + size * 0.6
+    for (const ch of tag) {
+        g.fillText(ch, tx, y + ph / 2 + 2 * k)
+        tx += g.measureText(ch).width + spacing
+    }
+    return y + ph
+}
+
+/** the watermark in its bottom corner: the image, the word beside it */
+function watermark(g: SKRSContext2D, look: TrailerLook, wm: NonNullable<VerticalLook['watermark']>, img: Images, [W, H]: readonly [number, number]): void {
+    const k = W / 1080
+    const h = WATERMARK.height * k
+    const m = WATERMARK.margin * k
+    const pic = wm.image ? img.get(wm.image) : undefined
+    const pw = pic ? (h * pic.width) / pic.height : 0
+    const px = h * 0.46
+    face(g, look, px, 900)
+    const tw = wm.text ? g.measureText(wm.text).width : 0
+    const gap = pic && wm.text ? 12 * k : 0
+    const width = pw + gap + tw
+    const x = wm.corner === 'left' ? m : W - m - width
+    const top = H - m - h
+    g.save()
+    g.globalAlpha = 0.92
+    g.shadowColor = alpha(look.edge, 0.5)
+    g.shadowBlur = 12 * k
+    if (pic) g.drawImage(pic, x, top, pw, h)
+    if (wm.text) {
+        g.textAlign = 'left'
+        g.textBaseline = 'middle'
+        g.fillStyle = look.light
+        g.fillText(wm.text, x + pw + gap, top + h / 2)
+    }
+    g.restore()
+}
+
+/** what the short wears, frame by frame of the lockup's pop (one frame when it has no lockup), the watermark drawn
+ *  in: `wear-<key>-NN.png`; null when it wears nothing */
+export async function drawWear(dir: string, root: string, look: TrailerLook, vl: VerticalLook, size: readonly [number, number], fps: number): Promise<{ pattern: string; frames: number } | null> {
+    if (!vl.lockup && !vl.watermark) return null
+    const frames = vl.lockup ? Math.round(POP_S * fps) + 1 : 1
+    const stem = `wear-${key([size, fps, look, vl.lockup, vl.watermark, files(root, look, vl)])}`
+    const pattern = join(dir, `${stem}-%02d.png`)
+    const at = (f: number): string => join(dir, `${stem}-${String(f).padStart(2, '0')}.png`)
+    if (existsSync(at(frames - 1))) return { pattern, frames }
+    mkdirSync(dir, { recursive: true })
+    registerFace(look, root)
+    const img = await images(root, vl)
+    const [W, H] = size
+    const top = Math.round(H * SAFE_TOP) + 8 * (W / 1080)
+    const probe = createCanvas(W, H).getContext('2d')
+    const h1 = vl.lockup ? lockup(probe, look, vl.lockup, img, W, 0, 1) : 0
+    for (let f = 0; f < frames; f++) {
+        const c = createCanvas(W, H)
+        const g = c.getContext('2d')
+        if (vl.lockup) {
+            // a soft shade from the top, then the lockup scaled about its middle: the pop grows in place
+            const shade = g.createLinearGradient(0, 0, 0, top + h1 + 120)
+            shade.addColorStop(0, alpha(look.edge, 0.5))
+            shade.addColorStop(1, alpha(look.edge, 0))
+            g.fillStyle = shade
+            g.fillRect(0, 0, W, top + h1 + 120)
+            const s = popScale(f / fps)
+            const hk = lockup(probe, look, vl.lockup, img, W, 0, s)
+            lockup(g, look, vl.lockup, img, W, top + (h1 - hk) / 2, s)
+        }
+        if (vl.watermark) watermark(g, look, vl.watermark, img, size)
+        png(c, at(f))
+    }
+    return { pattern, frames }
+}
+
+/** the watermark alone, laid over the outro; null without one */
+export async function drawMark(dir: string, root: string, look: TrailerLook, vl: VerticalLook, size: readonly [number, number]): Promise<string | null> {
+    if (!vl.watermark) return null
+    const file = join(dir, `mark-${key([size, look, vl.watermark, files(root, look, vl)])}.png`)
+    if (existsSync(file)) return file
+    mkdirSync(dir, { recursive: true })
+    registerFace(look, root)
+    const c = createCanvas(size[0], size[1])
+    watermark(c.getContext('2d'), look, vl.watermark, await images(root, vl), size)
+    return png(c, file)
+}
+
+/** the end card: the look's ground, a seam round it, a glow where its image lands, the name, a rule, the lines; the
+ *  image apart, which ffmpeg hops in at `at` */
+export async function drawEnd(dir: string, root: string, look: TrailerLook, vl: VerticalLook, size: readonly [number, number]): Promise<{ card: string; hero: { file: string; x: number; y: number } | null } | null> {
+    const end = vl.end
+    if (!end) return null
+    const stem = `end-${key([size, look, end, files(root, look, vl)])}`
+    const [cardFile, heroFile, whereFile] = ['card.png', 'hero.png', 'json'].map((x) => join(dir, `${stem}.${x}`)) as [string, string, string]
+    if (existsSync(cardFile) && existsSync(whereFile)) return { card: cardFile, hero: JSON.parse(await Bun.file(whereFile).text()) as { file: string; x: number; y: number } | null }
+    mkdirSync(dir, { recursive: true })
+    registerFace(look, root)
+    const img = await images(root, vl)
+    const [W, H] = size
+    const k = W / 1080
+    const c = createCanvas(W, H)
+    const g = c.getContext('2d')
+    const ground = g.createRadialGradient(W / 2, H * 0.45, 0, W / 2, H * 0.45, Math.hypot(W, H) * 0.6)
+    ground.addColorStop(0, look.ground[0])
+    ground.addColorStop(1, look.ground[1])
+    g.fillStyle = ground
+    g.fillRect(0, 0, W, H)
+    const pic = end.image ? img.get(end.image) : undefined
+    let [pw, ph] = pic ? [520 * k, (520 * k * pic.height) / pic.width] : [0, 0]
+    if (ph > H * 0.24) [pw, ph] = [(pw * H * 0.24) / ph, H * 0.24]
+    // the lines as large as the card's width allows, read on a phone
+    let linePx = 64 * k
+    for (; linePx > 40 * k; linePx -= 2 * k) {
+        face(g, look, linePx, 900)
+        if (Math.max(0, ...end.lines.map((l) => g.measureText(l.replaceAll('*', '')).width)) <= W - 200 * k) break
+    }
+    const lineStep = Math.round(linePx * 1.5)
+    face(g, look, 120 * k, 900)
+    const namePx = 120 * k * Math.min(1, (W * 0.72) / Math.max(1, g.measureText(end.name).width))
+    const block = (pic ? ph + 40 * k : 0) + namePx * 1.1 + 24 * k + 8 * k + (end.lines.length ? 50 * k + end.lines.length * lineStep : 0)
+    const top = Math.round(H * SAFE_TOP + (H * (1 - SAFE_TOP - SAFE_BOTTOM) - block) / 2)
+    const at = { x: Math.round((W - pw) / 2), y: top }
+    if (pic) {
+        const glow = g.createRadialGradient(W / 2, top + ph * 0.55, 20 * k, W / 2, top + ph * 0.55, 460 * k)
+        glow.addColorStop(0, alpha(look.accent, 0.38))
+        glow.addColorStop(1, alpha(look.accent, 0))
+        g.fillStyle = glow
+        g.fillRect(0, 0, W, H)
+    }
+    g.setLineDash([22 * k, 14 * k])
+    g.lineWidth = 6 * k
+    g.strokeStyle = alpha(look.accent, 0.75)
+    g.beginPath()
+    g.roundRect(44 * k, 44 * k, W - 88 * k, H - 88 * k, 56 * k)
+    g.stroke()
+    g.setLineDash([])
+    // the lines in the plate's ink on a light ground, else in the light
+    const ink = luminance(look.ground[0]) > 0.5 ? look.plate.ink : look.light
+    let y = top + (pic ? ph + 40 * k : 0)
+    name(g, look, end.name, W / 2, y + (namePx * 1.1) / 2, namePx, 'center')
+    y += namePx * 1.1 + 24 * k
+    g.fillStyle = look.accent
+    g.beginPath()
+    g.roundRect(W / 2 - 60 * k, y, 120 * k, 8 * k, 4 * k)
+    g.fill()
+    y += 8 * k + 50 * k
+    for (const l of end.lines) {
+        words(g, look, l, W / 2, y + lineStep / 2, linePx, ink)
+        y += lineStep
+    }
+    png(c, cardFile)
+    let hero: { file: string; x: number; y: number } | null = null
+    if (pic) {
+        const hc = createCanvas(Math.round(pw), Math.round(ph))
+        hc.getContext('2d').drawImage(pic, 0, 0, Math.round(pw), Math.round(ph))
+        hero = { file: png(hc, heroFile), ...at }
+    }
+    writeFileSync(whereFile, JSON.stringify(hero))
+    return { card: cardFile, hero }
+}

package/src/trailer/vertical.ts

@@ -0,0 +1,148 @@
+// the vertical short: the stitched cut finished with what the brand's `trailer.vertical` data draws (a lockup popping
+// in over every frame, a watermark in a bottom corner), then an outro clip and the end card its image hops onto. The
+// look resolved from that data and the ffmpeg arguments of the finish, as data. Pure: vertical-draw.ts draws the
+// frames, build.ts runs the arguments
+import type { Vertical } from './grammar.ts'
+import { ENCODERS, type Encoder } from './graph.ts'
+import type { BrandLike, TrailerLook } from './look.ts'
+
+/** the platforms' own overlays: their tabs over the top tenth, the caption and the buttons over the bottom quarter */
+export const SAFE_TOP = 0.1
+export const SAFE_BOTTOM = 0.25
+
+/** the lockup's elastic pop as the short opens: from 0.8 through about 1.06 at 0.12 s, settled to 1 by POP_S */
+export const POP_S = 0.42
+export const popScale = (t: number): number => (t >= POP_S ? 1 : 1 - 0.2 * Math.exp(-t / 0.1) * Math.cos((2 * Math.PI * t) / 0.24))
+
+/** the cross fade into the end card, and the card's length with it: a 1.2 s hold */
+export const END_FADE = 0.5
+export const END_S = END_FADE + 1.2
+
+export interface VerticalLook {
+    lockup: { image: string | null; logo: string | null; name: string; tag: string | null } | null
+    watermark: { image: string | null; text: string | null; corner: 'left' | 'right' } | null
+    end: { image: string | null; name: string; lines: string[]; seconds: number } | null
+}
+
+/** the brand's vertical data with every value it leaves out filled: the logo, the brand's name (`name` for a repo
+ *  with no brand), its tagline; `mark` the cut's own corner for the watermark */
+export function verticalOf(brand: BrandLike | null, look: TrailerLook, name: string, mark?: Vertical['mark']): VerticalLook {
+    const v = brand?.trailer?.vertical ?? {}
+    const named = brand?.name ?? name
+    const lk = v.lockup === false ? null : (v.lockup ?? {})
+    const wm = v.watermark === false ? null : (v.watermark ?? {})
+    const end = v.end === false ? null : (v.end ?? {})
+    const markImage = wm && ('image' in wm ? (wm.image ?? null) : look.logo)
+    return {
+        lockup: lk && { image: lk.image ?? null, logo: look.logo, name: lk.name ?? named, tag: lk.tag ?? null },
+        watermark: wm && { image: markImage, text: 'text' in wm ? (wm.text ?? null) : markImage ? null : named, corner: mark ?? wm.corner ?? 'left' },
+        end: end && { image: end.image ?? look.logo, name: end.name ?? named, lines: end.lines ?? (brand?.tagline ? [brand.tagline] : []), seconds: end.seconds ?? END_S },
+    }
+}
+
+/** what the finish reads: the cut, the frames drawn over it, the outro clip, the end card */
+export interface FinishInput {
+    cut: string
+    /** the cut's length, seconds */
+    seconds: number
+    size: readonly [number, number]
+    fps: number
+    /** the lockup's pop, frame by frame, the watermark drawn in (`%02d`), its last frame held; null: nothing over the cut */
+    wear: { pattern: string; frames: number } | null
+    /** the watermark alone, a full frame png laid over the outro */
+    mark: string | null
+    outro: { clip: string; seconds: number; audio: boolean } | null
+    end: { card: string; seconds: number; hero: { file: string; x: number; y: number } | null } | null
+    encoder: Encoder
+}
+
+const n3 = (x: number): string => (+x.toFixed(4)).toString()
+
+/** the image of the end card hops in once its fade is under way: up from below, eased, then two small bounces settling */
+export function hopY(y: number, k: number): string {
+    const p0 = END_FADE * 0.6
+    const land = p0 + 0.45
+    return `${y}+${n3(90 * k)}*pow(1-min(max(t-${n3(p0)},0)/0.45,1),3)-${n3(26 * k)}*abs(sin(PI*max(t-${n3(land)},0)/0.42))*exp(-2.2*max(t-${n3(land)},0))*gte(t,${n3(land)})`
+}
+
+/** the ffmpeg arguments of the finish: the cut under what it wears, a hard cut into the outro, a cross fade into the
+ *  end card, the sound carried under each and faded out with the card */
+export function finishArgs(a: FinishInput, out: string): string[] {
+    const [W, H] = a.size
+    const fps = a.fps
+    const inputs: string[] = []
+    const graph: string[] = []
+    let n = 0
+    const input = (...args: string[]): number => {
+        inputs.push(...args)
+        return n++
+    }
+    const held = (seconds: number, file: string): number => input('-loop', '1', '-framerate', String(fps), '-t', n3(seconds), '-i', file)
+    const even = `setsar=1,format=yuv420p,settb=AVTB,fps=${fps}`
+
+    const c = input('-i', a.cut)
+    if (a.wear) {
+        // a still overlay is one frame held (eof_action repeat), never a looped stream: no frames queue in the graph
+        const w = input('-framerate', String(fps), '-i', a.wear.pattern)
+        graph.push(`[${c}:v][${w}:v]overlay=0:0:eof_action=repeat,${even}[v0]`)
+    } else graph.push(`[${c}:v]${even}[v0]`)
+    graph.push(`[${c}:a]aresample=48000,aformat=channel_layouts=stereo,apad,atrim=duration=${n3(a.seconds)}[a0]`)
+    const lengths = [a.seconds]
+    const fades = [0]
+
+    if (a.outro) {
+        const i = lengths.length
+        const o = input('-i', a.outro.clip)
+        const fit = `[${o}:v]scale=${W}:${H}:force_original_aspect_ratio=increase,crop=${W}:${H},setsar=1,fps=${fps},trim=duration=${n3(a.outro.seconds)},setpts=PTS-STARTPTS`
+        if (a.mark) {
+            const m = input('-i', a.mark)
+            graph.push(`${fit}[ov${i}]`, `[ov${i}][${m}:v]overlay=0:0:eof_action=repeat,${even}[v${i}]`)
+        } else graph.push(`${fit},${even}[v${i}]`)
+        graph.push(
+            a.outro.audio
+                ? `[${o}:a]aresample=48000,aformat=channel_layouts=stereo,apad,atrim=duration=${n3(a.outro.seconds)}[a${i}]`
+                : `anullsrc=r=48000:cl=stereo,atrim=duration=${n3(a.outro.seconds)}[a${i}]`,
+        )
+        lengths.push(a.outro.seconds)
+        fades.push(0)
+    }
+
+    if (a.end) {
+        const i = lengths.length
+        const s = a.end.seconds
+        const card = held(s, a.end.card)
+        if (a.end.hero) {
+            const h = held(s, a.end.hero.file)
+            graph.push(`[${h}:v]format=rgba,fade=in:st=${n3(END_FADE * 0.6)}:d=0.3:alpha=1[hero]`)
+            graph.push(`[${card}:v][hero]overlay=x=${a.end.hero.x}:y='${hopY(a.end.hero.y, W / 1080)}':eval=frame:shortest=1,${even}[v${i}]`)
+        } else graph.push(`[${card}:v]${even}[v${i}]`)
+        graph.push(`anullsrc=r=48000:cl=stereo,atrim=duration=${n3(s)}[a${i}]`)
+        lengths.push(s)
+        fades.push(Math.min(END_FADE, s / 2))
+    }
+
+    let v = 'v0'
+    let au = 'a0'
+    let offset = 0
+    for (let i = 1; i < lengths.length; i++) {
+        const fade = fades[i]!
+        offset += lengths[i - 1]! - fade
+        if (fade === 0) graph.push(`[${v}][v${i}]concat=n=2:v=1:a=0,settb=AVTB,fps=${fps}[xv${i}]`, `[${au}][a${i}]concat=n=2:v=0:a=1[xa${i}]`)
+        else graph.push(`[${v}][v${i}]xfade=transition=fade:duration=${n3(fade)}:offset=${n3(offset)}[xv${i}]`, `[${au}][a${i}]acrossfade=d=${n3(fade)}[xa${i}]`)
+        v = `xv${i}`
+        au = `xa${i}`
+    }
+    return [
+        '-hide_banner', '-loglevel', 'error', '-y',
+        ...inputs,
+        '-filter_complex', graph.join(';\n'),
+        '-map', `[${v}]`, '-map', `[${au}]`,
+        ...ENCODERS[a.encoder], '-r', String(fps),
+        '-c:a', 'aac', '-b:a', '160k', '-movflags', '+faststart',
+        out,
+    ]
+}
+
+/** the finished short's length */
+export const finishSeconds = (a: Pick<FinishInput, 'seconds' | 'outro' | 'end'>): number =>
+    a.seconds + (a.outro?.seconds ?? 0) + (a.end ? a.end.seconds - Math.min(END_FADE, a.end.seconds / 2) : 0)

package/src/trailer/vocab.ts

@@ -0,0 +1,40 @@
+// the film words of a repo: its project CLI's film rows (the CLI kit's `film: 'still' | 'clip'` mark), read from
+// `<cli> commands --json`, the `cli` script of package.json. Read only when a film line does not read as a core
+// film (build.ts load), so a cut of core films never spawns anything
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { FilmVerb } from './grammar.ts'
+
+/** the project CLI's argv from the `cli` script of package.json, null when there is none */
+export function projectCli(root: string): string[] | null {
+    const pkg = join(root, 'package.json')
+    if (!existsSync(pkg)) return null
+    const cli = (JSON.parse(readFileSync(pkg, 'utf8')) as { scripts?: Record<string, string> }).scripts?.cli
+    if (typeof cli !== 'string' || cli.trim() === '') return null
+    return cli.trim().split(/\s+/)
+}
+
+/** the film rows in a `commands --json` answer: an array of rows, or `{ commands: [...] }` */
+export function filmRows(json: unknown): FilmVerb[] {
+    const rows = Array.isArray(json) ? json : Array.isArray((json as { commands?: unknown })?.commands) ? (json as { commands: unknown[] }).commands : []
+    return rows.flatMap((r) => {
+        const o = r as { path?: unknown; film?: unknown; description?: unknown }
+        if (o.film !== 'still' && o.film !== 'clip') return []
+        const path = Array.isArray(o.path) ? o.path.map(String) : typeof o.path === 'string' ? o.path.trim().split(/\s+/) : []
+        if (path.length === 0) return []
+        return [{ path, film: o.film, ...(typeof o.description === 'string' ? { description: o.description } : {}) }]
+    })
+}
+
+/** the project CLI's film rows; null when the repo has no project CLI. A CLI that does not answer is an error */
+export function readVocab(root: string, cli: readonly string[] | null): FilmVerb[] | null {
+    if (cli === null) return null
+    const r = Bun.spawnSync([...cli, 'commands', '--json'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const text = r.stdout.toString()
+    try {
+        if (r.exitCode !== 0) throw new Error(`exit ${r.exitCode}`)
+        return filmRows(JSON.parse(text))
+    } catch (e) {
+        throw new Error(`the project CLI (${cli.join(' ')}) did not answer \`commands --json\` with its rows: ${(e as Error).message}${r.stderr.length ? `\n${r.stderr.toString().trim().split('\n').slice(-4).join('\n')}` : ''}`)
+    }
+}