rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/titles.ts

@@ -1,17 +1,24 @@
 // 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). Five styles: logo, big, caption, corner, line. Cached on what they draw, so a title edit draws one PNG
+// 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'
 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 { alpha, darker, type TrailerLook } from './look.ts'
+import { alpha, darker, shortLook, type TrailerLook } from './look.ts'
 
 /** bump when a style's drawing changes: every cached title draws again */
 const DRAWING = 1
 
-export type TitlePlace = 'top' | 'bottom'
-export const placeOf = (ti: Title): TitlePlace => ti.place ?? 'bottom'
+/** 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')
+
+/** 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 */
 export interface TitleImage {
@@ -23,13 +30,15 @@ export interface TitleImage {
 }
 
 const registered = new Set<string>()
-/** the look's font file registered once under its family */
+/** the look's font files registered once under their families */
 export function registerFace(look: TrailerLook, root: string): void {
-    if (!look.font.file || registered.has(look.font.file)) return
-    const abs = join(root, look.font.file)
-    if (!existsSync(abs)) throw new Error(`the brand's trailer font ${look.font.file} is not in the repo`)
-    GlobalFonts.registerFromPath(abs, look.font.family)
-    registered.add(look.font.file)
+    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)
+    }
 }
 
 export const face = (g: SKRSContext2D, look: TrailerLook, px: number, weight = look.font.weight): void => {
@@ -72,8 +81,93 @@ 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 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()
+    }
+}
+
 /** 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): Buffer {
+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')
@@ -81,7 +175,11 @@ export function drawTitle(text: string, style: TitleStyle, [W, H]: readonly [num
     g.textAlign = 'center'
     g.textBaseline = 'middle'
     const [first = '', ...more] = text.split('\\n')
-    if (style === 'logo') {
+    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)
+    } 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))
@@ -241,21 +339,25 @@ const key = (parts: unknown): string => new Bun.CryptoHasher('sha1').update(JSON
 
 /** 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].map((f) => {
+    [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']
     })
 
-/** the PNG of a title, drawn once per text, style, frame, place and look; 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): Promise<TitleImage> {
-    const file = join(dir, `title-${key([text, style, size, place, look, lookFiles(look, root)])}.png`)
+/** 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`)
+
+/** 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)
     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)).trim({ threshold: 0 }).png().toBuffer({ resolveWithObject: true })
+        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 }))
     }
@@ -263,9 +365,12 @@ export async function titlePng(dir: string, root: string, text: string, style: T
     return { file, x, y, w, h }
 }
 
+/** the card's ground's PNG file for a frame and a look */
+export const cardFile = (dir: string, size: readonly [number, number], look: TrailerLook): string => join(dir, `card-${key(['card', size, look.ground])}.png`)
+
 /** the PNG of the card's ground for a frame and a look */
 export function cardPng(dir: string, size: readonly [number, number], look: TrailerLook): string {
-    const file = join(dir, `card-${key(['card', size, look.ground])}.png`)
+    const file = cardFile(dir, size, look)
     if (!existsSync(file)) {
         mkdirSync(dir, { recursive: true })
         writeFileSync(file, drawCard(size, look))

package/src/trailer/vocab.ts

@@ -18,22 +18,41 @@ export function projectCli(root: string): string[] | null {
 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 }
+        const o = r as { path?: unknown; film?: unknown; version?: unknown; length?: 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 } : {}) }]
+        return [
+            {
+                path,
+                film: o.film,
+                ...(typeof o.version === 'number' || typeof o.version === 'string' ? { version: o.version } : {}),
+                ...(o.length === 'own' ? { length: 'own' as const } : {}),
+                ...(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 */
+const asked = new Map<string, FilmVerb[]>()
+
+/** the rows asked again on the next read: a watch builds as a fresh process would */
+export const forgetVocab = (): void => asked.clear()
+
+/** the project CLI's film rows; null when the repo has no project CLI. A CLI that does not answer is an error. Asked
+ *  once per process: the prune and a watch read many cuts */
 export function readVocab(root: string, cli: readonly string[] | null): FilmVerb[] | null {
     if (cli === null) return null
+    const k = `${root}\0${cli.join(' ')}`
+    const had = asked.get(k)
+    if (had) return had
     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))
+        const rows = filmRows(JSON.parse(text))
+        asked.set(k, rows)
+        return rows
     } 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')}` : ''}`)
     }

package/src/trailer/words.ts

@@ -0,0 +1,254 @@
+// a film row's declared words (wiki build/trailer.md, A row's words): the row says which words it takes and their
+// types, the core reads every word of a film line at its own line against that, refuses an unknown one with the row's
+// list, and hands the row its values made plain (argv stays the transport). Pure: times arrive as moments the grammar
+// resolves once the shots have landed
+
+export type WordType = 'number' | 'int' | 'enum' | 'point' | 'time' | 'cues' | 'file' | 'text' | 'word' | 'flag'
+export const WORD_TYPES: readonly WordType[] = ['number', 'int', 'enum', 'point', 'time', 'cues', 'file', 'text', 'word', 'flag']
+
+/** one word a row takes: its type and bounds; `arg: n` makes it the n-th positional */
+export interface WordSpec {
+    type: WordType
+    arg?: number
+    optional?: boolean
+    min?: number
+    max?: number
+    values?: string[]
+    /** a point's numbers, 2 by default */
+    count?: number
+    /** a word's shape, a regular expression */
+    pattern?: string
+    /** what it means, for the error that lists the row's words */
+    doc?: string
+}
+
+export type Words = Record<string, WordSpec>
+
+/** a word of a film line, with the line it sits on (an option line under the film line keeps its own) */
+export interface LineWord {
+    text: string
+    quoted: boolean
+    line: number
+}
+
+/** a time: seconds, or a section or mark of the cut and a time from it */
+export type Moment = number | { mark: string; offset: number }
+
+export interface Typed {
+    /** the row's path, then its words in the order written, each value plain; a time's slot is filled by `times` */
+    argv: string[]
+    /** argv slots made of moments: a time (`name` null) or cues (`name@seconds`, comma joined) */
+    times: { index: number; parts: { name: string | null; at: Moment; line: number }[] }[]
+    /** argv slots that are files, as written: the build finds them and keys their content */
+    files: number[]
+    errors: { line: number; message: string }[]
+}
+
+/** the row's words checked as a declaration: every type known, its bounds sane; null when it is one */
+export function wordsProblem(words: unknown): string | null {
+    if (typeof words !== 'object' || words === null) return 'words is a record of word → { type }'
+    for (const [k, v] of Object.entries(words as Record<string, unknown>)) {
+        const w = v as Partial<WordSpec> | null
+        if (!/^[a-z][a-z0-9-]*$/.test(k)) return `word ${k}: a word is lowercase letters, digits and -`
+        if (!w || !WORD_TYPES.includes(w.type as WordType)) return `word ${k}: type is one of ${WORD_TYPES.join(', ')}`
+        if (w.type === 'enum' && (!Array.isArray(w.values) || w.values.length === 0)) return `word ${k}: an enum names its values`
+        if (w.pattern !== undefined) {
+            try {
+                new RegExp(w.pattern)
+            } catch {
+                return `word ${k}: pattern ${w.pattern} is no regular expression`
+            }
+        }
+    }
+    return null
+}
+
+const n4 = (x: number): string => String(+x.toFixed(4))
+
+/** one value read by its type: its plain text, a moment, or why it does not fit */
+function valueOf(key: string, spec: WordSpec, w: LineWord, time: (text: string) => Moment | null): { text: string } | { at: Moment } | { error: string } {
+    const t = w.text
+    const what = `${key} wants ${describe(spec)}, got ${w.quoted ? `"${t}"` : t}`
+    switch (spec.type) {
+        case 'number':
+        case 'int': {
+            const v = w.quoted ? Number.NaN : Number(t)
+            if (!Number.isFinite(v) || (spec.type === 'int' && !Number.isInteger(v)) || (spec.min !== undefined && v < spec.min) || (spec.max !== undefined && v > spec.max)) return { error: what }
+            return { text: t }
+        }
+        case 'enum':
+            return !w.quoted && spec.values!.includes(t) ? { text: t } : { error: what }
+        case 'point': {
+            const parts = w.quoted ? [] : t.split(',')
+            const ok = parts.length === (spec.count ?? 2) && parts.every((p) => p !== '' && Number.isFinite(Number(p)))
+            return ok ? { text: t } : { error: what }
+        }
+        case 'time': {
+            const at = w.quoted ? null : time(t)
+            return at === null ? { error: what } : { at }
+        }
+        case 'file':
+        case 'word':
+            if (w.quoted || t === '' || (spec.pattern !== undefined && !new RegExp(spec.pattern).test(t))) return { error: what }
+            return { text: t }
+        case 'text':
+            return t.trim() === '' ? { error: `${key}: the text is empty` } : { text: t }
+        default:
+            return { error: what }
+    }
+}
+
+function describe(s: WordSpec): string {
+    switch (s.type) {
+        case 'number':
+        case 'int':
+            return `${s.type === 'int' ? 'a whole number' : 'a number'}${s.min !== undefined || s.max !== undefined ? ` from ${s.min ?? '-∞'} to ${s.max ?? '∞'}` : ''}`
+        case 'enum':
+            return s.values!.join('|')
+        case 'point':
+            return `${s.count ?? 2} numbers joined by commas`
+        case 'time':
+            return 'a time (1.5s, 400ms, 0:04, 2beats, a mark, mark+1beat)'
+        case 'cues':
+            return 'cues, name@<time> each'
+        case 'file':
+            return 'a file'
+        case 'word':
+            return `a word${s.pattern ? ` like ${s.pattern}` : ''}`
+        case 'text':
+            return 'a text'
+        case 'flag':
+            return 'no value'
+    }
+}
+
+/** the row's words, for an error: positionals in order, then keys */
+export const wordList = (words: Words): string =>
+    [
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg !== undefined)
+            .sort((a, b) => a[1].arg! - b[1].arg!)
+            .map(([k, s]) => `<${k}>${s.optional ? '?' : ''}`),
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg === undefined)
+            .map(([k]) => k),
+    ].join(' ')
+
+interface Entry {
+    key: string
+    /** a positional's words carry no key on the line */
+    positional: boolean
+    values: LineWord[]
+    line: number
+}
+
+/** the entries of a run of words: a word that names a key opens it (its value words follow), any other word fills the
+ *  next positional that takes it */
+function entriesOf(path: string, words: Words, ws: LineWord[], time: (text: string) => Moment | null, errors: Typed['errors']): Entry[] {
+    const args = Object.entries(words)
+        .filter(([, s]) => s.arg !== undefined)
+        .sort((a, b) => a[1].arg! - b[1].arg!)
+    let next = 0
+    const out: Entry[] = []
+    for (let i = 0; i < ws.length; i++) {
+        const w = ws[i]!
+        const spec = !w.quoted && words[w.text] && words[w.text]!.arg === undefined ? words[w.text]! : null
+        if (spec) {
+            if (spec.type === 'flag') out.push({ key: w.text, positional: false, values: [], line: w.line })
+            else if (spec.type === 'cues') {
+                const values: LineWord[] = []
+                while (i + 1 < ws.length && !ws[i + 1]!.quoted && /^[^@\s]+@\S+$/.test(ws[i + 1]!.text) && !words[ws[i + 1]!.text]) {
+                    const c = ws[++i]!
+                    for (const text of c.text.split(',')) values.push({ ...c, text })
+                }
+                if (values.length === 0) errors.push({ line: w.line, message: `film ${path} ${w.text} wants cues, name@<time> each` })
+                out.push({ key: w.text, positional: false, values, line: w.line })
+            } else {
+                const v = ws[i + 1]
+                if (!v || v.line !== w.line) errors.push({ line: w.line, message: `film ${path} ${w.text} wants ${describe(spec)}` })
+                else {
+                    out.push({ key: w.text, positional: false, values: [v], line: w.line })
+                    i++
+                }
+            }
+            continue
+        }
+        // the next positional that takes this word; an optional one that does not is passed over
+        let placed = false
+        while (next < args.length) {
+            const [k, s] = args[next++]!
+            if (!('error' in valueOf(k, s, w, time))) {
+                out.push({ key: k, positional: true, values: [w], line: w.line })
+                placed = true
+                break
+            }
+            if (!s.optional) {
+                errors.push({ line: w.line, message: `film ${path}: ${w.quoted ? `"${w.text}"` : w.text} fits no word here, <${k}> wants ${describe(s)} (${path} takes ${wordList(words)})` })
+                placed = true
+                break
+            }
+        }
+        if (!placed) {
+            errors.push({ line: w.line, message: `film ${path}: unknown word ${w.quoted ? `"${w.text}"` : w.text} (${path} takes ${wordList(words)})` })
+            // its value goes with it: one error a word
+            const v = ws[i + 1]
+            if (v && v.line === w.line && !(!v.quoted && words[v.text])) i++
+        }
+    }
+    return out
+}
+
+/**
+ * a film line of a row that declares its words: `ws` its words after the row's path, `defaults` its section's (a key
+ * the line gives itself wins). The plain argv, the slots that wait on a moment, the file slots, every error at its line
+ */
+export function typedFilm(path: string[], words: Words, ws: LineWord[], defaults: LineWord[], time: (text: string) => Moment | null): Typed {
+    const errors: Typed['errors'] = []
+    const own = entriesOf(path.join(' '), words, ws, time, errors)
+    const given = new Set(own.map((e) => e.key))
+    const fromDefaults = defaults.length > 0 ? entriesOf(path.join(' '), words, defaults, time, errors).filter((e) => !given.has(e.key)) : []
+    const all = [...fromDefaults, ...own]
+    const seen = new Set<string>()
+    const argv = [...path]
+    const times: Typed['times'] = []
+    const files: number[] = []
+    for (const e of all) {
+        if (seen.has(e.key)) {
+            errors.push({ line: e.line, message: `film ${path.join(' ')}: ${e.key} given twice` })
+            continue
+        }
+        seen.add(e.key)
+        const spec = words[e.key]!
+        if (!e.positional) argv.push(e.key)
+        if (spec.type === 'flag') continue
+        if (spec.type === 'cues') {
+            const parts: Typed['times'][number]['parts'] = []
+            for (const v of e.values) {
+                const at = v.text.indexOf('@')
+                const name = v.text.slice(0, at)
+                const m = time(v.text.slice(at + 1))
+                if (m === null) errors.push({ line: v.line, message: `film ${path.join(' ')} ${e.key}: ${v.text}, the time after @ is no time (1.5s, 2beats, a mark, mark+1beat)` })
+                else parts.push({ name, at: m, line: v.line })
+            }
+            times.push({ index: argv.length, parts })
+            argv.push('')
+            continue
+        }
+        const got = valueOf(e.key, spec, e.values[0]!, time)
+        if ('error' in got) {
+            errors.push({ line: e.values[0]!.line, message: `film ${path.join(' ')}: ${got.error}` })
+            argv.push(e.values[0]!.text)
+        } else if ('at' in got) {
+            times.push({ index: argv.length, parts: [{ name: null, at: got.at, line: e.values[0]!.line }] })
+            argv.push('')
+        } else {
+            if (spec.type === 'file') files.push(argv.length)
+            argv.push(got.text)
+        }
+    }
+    for (const [k, s] of Object.entries(words)) if (s.arg !== undefined && !s.optional && !seen.has(k)) errors.push({ line: ws[0]?.line ?? defaults[0]?.line ?? 0, message: `film ${path.join(' ')}: <${k}> is missing (${path.join(' ')} takes ${wordList(words)})` })
+    return { argv, times, files, errors }
+}
+
+/** a slot's text once its moments are seconds: a time, or cues joined by commas */
+export const slotText = (parts: readonly { name: string | null; seconds: number }[]): string => parts.map((p) => (p.name === null ? n4(p.seconds) : `${p.name}@${n4(p.seconds)}`)).join(',')