rvlib-shipkit 2.4.0 → 2.6.0

package/src/trailer/score/dsp.ts

@@ -126,45 +126,105 @@ function staticCurve(c: CompressorDef): { saturate: (x: number) => number; makeu
     return { saturate, makeup: (1 / saturate(1)) ** 0.6 }
 }
 
-/** a stereo compressor in place, 6 ms of lookahead: the gain follows the louder channel, falling at `attack` and
- *  rising at `release`, in dB */
+/** the release a browser compressor takes at 15, 10, 5 and 0 dB from its target, shares of its release time */
+const RELEASE_ZONES = [0.09, 0.16, 0.42, 0.98] as const
+/** a browser compressor sets its envelope's rate once a division of this many frames */
+const DIVISION = 32
+
+/** a stereo compressor in place, as a browser's (its dynamics compressor kernel): 6 ms of lookahead; a detector on the
+ *  louder channel's attenuation that lets go over 2.5 ms; a gain that attacks at a rate set by the deepest attenuation
+ *  it chases and releases faster the more it compresses (a curve through the four release zones); a sine warp on the
+ *  gain, the makeup on top */
 export function compress(l: Float32Array, r: Float32Array, rate: number, c: CompressorDef): void {
     const { saturate, makeup } = staticCurve(c)
-    const n = l.length
-    // the curve sampled in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
+    // the attenuation in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
     const lo = -60
     const step = 0.05
     const table = new Float32Array(Math.ceil((24 - lo) / step) + 2)
     for (let i = 0; i < table.length; i++) {
         const x = lin(lo + i * step)
-        table[i] = dbOf(saturate(x) / x)
+        table[i] = -dbOf(saturate(x) / x)
     }
-    compressRun(l, r, n, Math.round(0.006 * rate), Math.exp(-1 / (Math.max(1e-4, c.attack) * rate)), Math.exp(-1 / (Math.max(1e-4, c.release) * rate)), table, lo, step, makeup)
+    const [y1, y2, y3, y4] = RELEASE_ZONES.map((z) => z * rate * c.release) as [number, number, number, number]
+    // the 4th order polynomial through (0, y1), (1, y2), (2, y3), (3, y4), the browser's own coefficients
+    const poly: Poly = [
+        0.9999999999999998 * y1 + 1.8432219684323923e-16 * y2 - 1.9373394351676423e-16 * y3 + 8.824516011816245e-18 * y4,
+        -1.5788320352845888 * y1 + 2.3305837032074286 * y2 - 0.9141194204840429 * y3 + 0.1623677525612032 * y4,
+        0.5334142869106424 * y1 - 1.272736789213631 * y2 + 0.9258856042207512 * y3 - 0.18656310191776226 * y4,
+        0.08783463138207234 * y1 - 0.1694162967925622 * y2 + 0.08588057951595272 * y3 - 0.00429891410546283 * y4,
+        -0.042416883008123074 * y1 + 0.1115693827987602 * y2 - 0.09764676325265872 * y3 + 0.028494263462021576 * y4,
+    ]
+    compressRun(l, r, { delay: Math.round(0.006 * rate), attack: Math.max(0.001, c.attack) * rate, detectorRelease: 0.0025 * rate, poly, table, lo, step, makeup })
+}
+
+type Poly = [number, number, number, number, number]
+
+interface Kernel {
+    /** frames of lookahead */
+    delay: number
+    /** frames */
+    attack: number
+    detectorRelease: number
+    poly: Poly
+    /** attenuation in dB by input dB, from `lo` a `step` apart */
+    table: Float32Array
+    lo: number
+    step: number
+    makeup: number
 }
 
-function compressRun(l: Float32Array, r: Float32Array, n: number, delay: number, att: number, rel: number, table: Float32Array, lo: number, step: number, makeup: number): void {
-    const dl = new Float32Array(delay)
-    const dr = new Float32Array(delay)
-    let env = 0
+function compressRun(l: Float32Array, r: Float32Array, k: Kernel): void {
+    const n = l.length
+    const dl = new Float32Array(k.delay)
+    const dr = new Float32Array(k.delay)
+    const { table, lo, step } = k
     const last = table.length - 1
-    for (let i = 0; i < n; i++) {
-        const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
-        let target = 0
-        if (x > 1e-3) {
-            const p = (20 * Math.log10(x) - lo) / step
-            const j = Math.min(last - 1, Math.max(0, p | 0))
-            const f = Math.min(1, Math.max(0, p - j))
-            target = table[j]! + (table[j + 1]! - table[j]!) * f
+    const [ka, kb, kc, kd, ke] = k.poly
+    let detector = 0
+    let gain = 1
+    let maxAttackDb = -1
+    for (let d0 = 0; d0 < n; d0 += DIVISION) {
+        // pre warped so the sine warp below lands on the detector's gain
+        const desired = Math.asin(Math.min(1, detector)) / (Math.PI / 2)
+        let envRate: number
+        if (desired > gain) {
+            maxAttackDb = -1
+            let diff = dbOf(gain / desired)
+            if (!Number.isFinite(diff)) diff = -1
+            const x = 0.25 * (Math.min(0, Math.max(-12, diff)) + 12)
+            const frames = ka + kb * x + kc * x * x + kd * x * x * x + ke * x * x * x * x
+            envRate = lin(5 / frames)
+        } else {
+            let diff = desired > 0 ? dbOf(gain / desired) : 1
+            if (!Number.isFinite(diff)) diff = 1
+            if (maxAttackDb === -1 || maxAttackDb < diff) maxAttackDb = diff
+            envRate = 1 - (0.25 / Math.max(0.5, maxAttackDb)) ** (1 / k.attack)
+        }
+        const end = Math.min(n, d0 + DIVISION)
+        for (let i = d0; i < end; i++) {
+            const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
+            let att = 1
+            let attDb = 0
+            if (x > 1e-4) {
+                const p = (20 * Math.log10(x) - lo) / step
+                const j = Math.min(last - 1, Math.max(0, p | 0))
+                const f = Math.min(1, Math.max(0, p - j))
+                attDb = table[j]! + (table[j + 1]! - table[j]!) * f
+                att = lin(-attDb)
+            }
+            const release = lin(Math.max(2, attDb) / k.detectorRelease) - 1
+            detector = Math.min(1, detector + (att - detector) * (att > detector ? release : 1))
+            if (envRate < 1) gain += (desired - gain) * envRate
+            else gain = Math.min(1, gain * envRate)
+            const g = k.makeup * Math.sin((Math.PI / 2) * gain)
+            const at = i % k.delay
+            const yl = dl[at]!
+            const yr = dr[at]!
+            dl[at] = l[i]!
+            dr[at] = r[i]!
+            l[i] = yl * g
+            r[i] = yr * g
         }
-        env = target < env ? target + (env - target) * att : target + (env - target) * rel
-        const g = makeup * 10 ** (env / 20)
-        const k = i % delay
-        const yl = dl[k]!
-        const yr = dr[k]!
-        dl[k] = l[i]!
-        dr[k] = r[i]!
-        l[i] = yl * g
-        r[i] = yr * g
     }
 }
 

package/src/trailer/score/pattern.ts

@@ -3,7 +3,7 @@
 
 /** oscillator families: chiptune roots (pulse, wave, noise) plus the smoother modern ones; `gm` a General MIDI
  *  program the soundfont plays (gm.ts) */
-export type Osc = 'pulse' | 'saw' | 'triangle' | 'sine' | 'wave' | 'noise' | 'gm'
+export type Osc = 'pulse' | 'saw' | 'triangle' | 'square' | 'sine' | 'wave' | 'noise' | 'gm'
 
 export interface InstrumentDef {
     osc: Osc

package/src/trailer/score/synth.ts

@@ -74,6 +74,14 @@ function sawCoefficients(): Coefficients {
     return { real, imag }
 }
 
+/** the browser's own square wave, which a score names by its web audio type; never softened */
+function squareCoefficients(): Coefficients {
+    const real = new Float64Array(HARMONICS + 1)
+    const imag = new Float64Array(HARMONICS + 1)
+    for (let k = 1; k <= HARMONICS; k += 2) imag[k] = 4 / (Math.PI * k)
+    return { real, imag }
+}
+
 function triangleCoefficients(): Coefficients {
     const real = new Float64Array(HARMONICS + 1)
     const imag = new Float64Array(HARMONICS + 1)
@@ -186,6 +194,7 @@ class Waves {
                 : osc === 'saw' ? sawCoefficients()
                 : osc === 'wave' ? waveCoefficients(inst.wave!)
                 : osc === 'triangle' ? triangleCoefficients()
+                : osc === 'square' ? squareCoefficients()
                 : { real: new Float64Array(2), imag: Float64Array.of(0, 1) }
             t = tableOf(c, bandHz(band), tone, this.rate)
             this.tables.set(key, t)
@@ -204,11 +213,21 @@ interface Pitch {
 
 const pitchAt = (p: Pitch, t: number): number => (p.over <= 0 || t >= p.over ? p.to : p.from * (p.to / p.from) ** (Math.max(0, t) / p.over))
 
-/** one oscillator voice added into `buf`: a table read at a moving pitch, its detune and vibrato in cents */
-function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, table: Float32Array, p: Pitch, cents: number, vib: InstrumentDef['vibrato'] | null, gain: number): void {
+/** a browser renders in blocks of this many frames */
+const QUANTUM = 128
+/** an oscillator's frequency before its first automation event: the browser's default */
+const DEFAULT_HZ = 440
+
+/** one oscillator voice added into `buf`: a table read at a moving pitch, its detune and vibrato in cents. `lead` is
+ *  how far into its 128 frame block the note starts: in that first block a browser oscillator reads its frequency from
+ *  the block's start, so it runs at the default 440 Hz for `lead` frames and its pitch curve lags by `lead` frames. That
+ *  sets the phase every later frame carries, and two notes of one pitch that overlap add or cancel by it */
+function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, table: Float32Array, p: Pitch, cents: number, vib: InstrumentDef['vibrato'] | null, gain: number, lead: number): void {
     const LN = Math.LN2 / 1200
     const steady = p.over <= 0 && !vib
     const fixed = (p.to * Math.exp(cents * LN)) / rate
+    const early = (DEFAULT_HZ * Math.exp(cents * LN)) / rate
+    const first = lead > 0 ? QUANTUM - lead : 0
     let phase = Math.max(0, t0) * (p.over <= 0 ? p.to : p.from) * Math.exp(cents * LN)
     phase -= Math.floor(phase)
     for (let i = 0; i < n; i++) {
@@ -216,9 +235,11 @@ function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, t
         const j = x | 0
         const v = table[j]!
         buf[i] = buf[i]! + gain * (v + (table[j + 1]! - v) * (x - j))
+        const at = i < first ? i - lead : i
         let inc = fixed
-        if (!steady) {
-            const t = t0 + i / rate
+        if (at < 0) inc = early
+        else if (!steady) {
+            const t = t0 + at / rate
             let c = cents
             if (vib) {
                 const on = Math.max(0, vib.delay)
@@ -288,7 +309,7 @@ function playNote(bus: Bus, waves: Waves, inst: InstrumentDef, note: ScheduledNo
         const table = waves.table(inst, hz)
         for (let v = 0; v < voices; v++) {
             const cents = voices === 1 ? spread : spread * ((2 * v) / (voices - 1) - 1)
-            oscillatorRun(buf, n, t0, rate, table, pitch, cents, vib, 1 / Math.sqrt(voices))
+            oscillatorRun(buf, n, t0, rate, table, pitch, cents, vib, 1 / Math.sqrt(voices), i0 % QUANTUM)
         }
     }
     applyEnvelope(buf, n, t0, rate, pts)

package/src/trailer/titles.ts

@@ -58,14 +58,16 @@ export const face = (g: SKRSContext2D, look: TrailerLook, px: number, weight = l
     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 */
+/** how one run of words is painted: its face, its fill (a colour, or stops top to bottom, each `colour[@share]`), the
+ *  accent of its `*word*`, and the passes under the fill: a glow, a drop (a solid copy below the words, the shadow under
+ *  it), an outline (the shadow under it when there is no drop), an inner stroke */
 export interface Paint {
     family: string
     weight: number
     px: number
     fill: string | string[]
     key: string
+    drop?: { dy: number; color: string } | null
     outline: { w: number; color: string; dy?: number } | null
     inner: { w: number; color: string } | null
     shadow: { blur: number; dy: number; color: string } | null
@@ -134,7 +136,10 @@ function ink(cx: Ctx, g: SKRSContext2D, p: Paint, text: string, x: number, y: nu
         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))
+        p.fill.forEach((c, k) => {
+            const [colour = c, at] = c.split('@')
+            grad.addColorStop(at === undefined ? 0.1 + (0.9 * k) / Math.max(1, p.fill.length - 1) : Number(at), colour)
+        })
         return grad as unknown as CanvasGradient
     }
     const pass = (draw: (u: (typeof units)[number]) => void): void => {
@@ -172,10 +177,18 @@ function ink(cx: Ctx, g: SKRSContext2D, p: Paint, text: string, x: number, y: nu
             g.fillText(u.text, u.x, y)
         })
     }
+    if (p.drop) {
+        const o = p.drop
+        pass((u) => {
+            shadowed(p.shadow)
+            g.fillStyle = o.color
+            g.fillText(u.text, u.x, y + o.dy)
+        })
+    }
     if (p.outline) {
         const o = p.outline
         pass((u) => {
-            shadowed(p.shadow)
+            if (!p.drop) shadowed(p.shadow)
             g.lineWidth = o.w
             g.strokeStyle = o.color
             g.strokeText(u.text, u.x, y + (o.dy ?? 0))
@@ -190,7 +203,7 @@ function ink(cx: Ctx, g: SKRSContext2D, p: Paint, text: string, x: number, y: nu
         })
     }
     pass((u) => {
-        if (!p.outline) shadowed(p.shadow)
+        if (!p.outline && !p.drop) shadowed(p.shadow)
         g.fillStyle = fill(u.key) as string
         g.fillText(u.text, u.x, y)
     })
@@ -208,11 +221,18 @@ export function paintWith(base: Paint, fx: TitleFx | undefined, look: TrailerLoo
     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) }
+    if (fx.gradient)
+        p.fill = fx.gradient.map((x) => {
+            const [colour, at] = x.split('@')
+            return at === undefined ? c(colour, look.light) : `${c(colour, look.light)}@${at}`
+        })
+    // an outline word keeps the style's offset under the words
+    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), ...(base.outline?.dy ? { dy: base.outline.dy } : {}) }
     // 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.inner) p.inner = fx.inner.px === 0 ? null : { w: fx.inner.px * k, color: c(fx.inner.color, base.inner?.color ?? look.accent) }
+    if (fx.drop) p.drop = fx.drop.px === 0 ? null : { dy: fx.drop.px * k, color: c(fx.drop.color, base.outline?.color ?? look.edge) }
+    if (fx.shadow) p.shadow = fx.shadow.px === 0 ? null : { blur: fx.shadow.px * k, dy: (fx.shadow.dy ?? fx.shadow.px / 3) * k, 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
 }
@@ -235,9 +255,9 @@ function wrap(g: SKRSContext2D, text: string, max: number): string[] {
 }
 
 /** a rounded plate with a soft drop under it */
-function plate(g: SKRSContext2D, x: number, y: number, w: number, h: number, r: number, k: number, fill: string, line: string, edge: string): void {
+function plate(g: SKRSContext2D, x: number, y: number, w: number, h: number, r: number, k: number, fill: string, line: string, shadow: string): void {
     g.save()
-    g.shadowColor = alpha(edge, 0.4)
+    g.shadowColor = shadow
     g.shadowBlur = 18 * k
     g.shadowOffsetY = 6 * k
     g.fillStyle = fill
@@ -252,13 +272,13 @@ function plate(g: SKRSContext2D, x: number, y: number, w: number, h: number, r:
     g.stroke()
 }
 
-/** a soft band of the edge's shade across the frame, behind words */
+/** a soft band of the look'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))
+        b.addColorStop(0, alpha(look.band, 0))
+        b.addColorStop(0.5, alpha(look.band, a))
+        b.addColorStop(1, alpha(look.band, 0))
         g.fillStyle = b
         g.fillRect(0, y0, W, y1 - y0)
     })
@@ -315,7 +335,7 @@ function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, numb
                     const nx = (W - width) / 2 + j * (nw + gap)
                     g.save()
                     if (j === i - 1) {
-                        g.shadowColor = alpha(sl.accent, 0.9)
+                        g.shadowColor = alpha(look.short.lit, 0.9)
                         g.shadowBlur = 22 * ks
                     }
                     g.beginPath()
@@ -332,22 +352,29 @@ function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, numb
             })
         }
     } else if (style === 'logo') {
-        // 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
+        // the logo image over the word, the word in a light to accent ramp over a dropped edge, the subtitle spaced
+        // under; the block's middle at 0.48 of the height, or the word's at its `middle`, a soft shade round that anchor
+        const fx = d.fx
+        const S = 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 kl = Math.min(1, (W * (fx?.fit ?? 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 subPx = S * (fx?.sub ?? 0.2) * k * Math.max(kl, 0.7)
+        const gap = fx?.gap !== undefined ? fx.gap * px : subPx / 2
+        const markGap = markH ? px * 0.25 : 0
+        const block = markH + markGap + (first ? px : 0) + (more.length ? gap + subPx * 1.5 : 0)
+        const anchor = fx?.middle !== undefined ? H * fx.middle : H * 0.48
+        let y = fx?.middle !== undefined ? anchor - px / 2 - markGap - markH : anchor - block / 2
+        const shade = fx?.shade ?? 0.45
+        if (shade > 0)
+            decor(cx, g, () => {
+                const glow = g.createRadialGradient(W / 2, anchor, 0, W / 2, anchor, Math.max(W, H) * shade)
+                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 logo = d.logo
         if (logo) {
             const w = (logo.width / logo.height) * markH
@@ -357,16 +384,18 @@ function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, numb
                 g.shadowBlur = 30 * k
                 g.drawImage(logo, W / 2 - w / 2, at, w, markH)
             })
-            y += markH + px * 0.25
+            y += markH + markGap
         }
         if (first) {
-            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) } })
+            // the word's own words scale with it as it shrinks to fit
+            const kw = k * kl
+            const p = paintWith({ ...base(px, 900), fill: [look.light, look.accent, darker(look.accent, 0.2)], outline: { w: 16 * kw, color: look.edge, dy: 3 * kw }, shadow: { blur: 30 * kw, dy: 12 * kw, color: alpha(look.edge, 0.6) } }, fx, look, kw, d.family)
             ink(cx, g, p, first, W / 2, y + px / 2)
             y += px
         }
         if (more.length) {
-            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)
+            const sub: Paint = { ...base(subPx, fx?.weight ?? (d.family ? 400 : 800)), ...(d.family ? { family: d.family } : {}), fill: look.subtitle.color, spacing: subPx * 0.42, shadow: { blur: subPx * 0.42, dy: 0, color: alpha(look.subtitle.glow, 0.9) } }
+            ink(cx, g, sub, more.join(' ').toUpperCase(), W / 2 + (subPx * 0.42) / 2, y + gap + subPx / 2)
         }
     } else if (style === 'big') {
         // a strong display line in the upper third: light words in a thick edge outline, an accent stroke inside it
@@ -395,7 +424,7 @@ function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, numb
         const bh = lines.length * lh + 34 * k
         const cy = top ? H * 0.12 : H * 0.83
         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)
+            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.plate.shadow)
             g.fillStyle = look.accent
             g.beginPath()
             g.arc(W / 2 - bw / 2 + 34 * k, cy, dot / 2 + 2 * k, 0, Math.PI * 2)
@@ -411,7 +440,7 @@ function drawInto(g: SKRSContext2D, d: TitleDraw, [W, H]: readonly [number, numb
         const h = p.px * 1.5
         const x = 72 * k
         const y = top ? 80 * k : H - 80 * k - h
-        decor(cx, g, () => plate(g, x, y, w, h, h / 2, k, look.chip.fill, darker(look.chip.fill, 0.15), look.edge))
+        decor(cx, g, () => plate(g, x, y, w, h, h / 2, k, look.chip.fill, look.chip.line, look.plate.shadow))
         ink(cx, g, p, t, x + 36 * k, y + h / 2 + 2 * k, 'left')
     }
 }

package/src/trailer/vocab.ts

@@ -1,8 +1,9 @@
 // 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'
+// film (build.ts load), so a cut of core films never spawns anything; an answer that names its `sources` is kept in
+// rows.json and asked again only when the content of one of them changes
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import type { FilmVerb } from './grammar.ts'
 import { type Words, wordsProblem } from './words.ts'
 
@@ -47,22 +48,80 @@ export function filmRows(json: unknown): FilmVerb[] {
 
 const asked = new Map<string, FilmVerb[]>()
 
+/** the CLI's last answer, kept with the content of each file it named as its `sources` */
+interface Kept {
+    cli: string
+    sources: Record<string, string>
+    answer: unknown
+}
+
+export const rowsFile = (root: string): string => join(root, '.shipkit', 'cache', 'trailer', 'rows.json')
+
+const digest = (file: string): string | null => {
+    try {
+        return Bun.hash(readFileSync(file)).toString(36)
+    } catch {
+        return null
+    }
+}
+
+/** the kept answer while every source holds the content it had, else null */
+function keptAnswer(root: string, cli: string): unknown {
+    let k: Kept
+    try {
+        k = JSON.parse(readFileSync(rowsFile(root), 'utf8')) as Kept
+    } catch {
+        return null
+    }
+    if (k.cli !== cli || typeof k.sources !== 'object' || k.sources === null) return null
+    for (const [p, h] of Object.entries(k.sources)) if (digest(resolve(root, p)) !== h) return null
+    return k.answer ?? null
+}
+
+/** the answer kept when it names its sources and none of them was written while the CLI ran */
+function keep(root: string, cli: string, answer: unknown, asked: number): void {
+    const named = (answer as { sources?: unknown } | null)?.sources
+    if (!Array.isArray(named) || named.length === 0) return
+    const sources: Record<string, string> = {}
+    for (const p of named.map(String)) {
+        const abs = resolve(root, p)
+        const h = digest(abs)
+        if (h === null || statSync(abs).mtimeMs >= asked) return
+        sources[p] = h
+    }
+    const file = rowsFile(root)
+    mkdirSync(dirname(file), { recursive: true })
+    const part = `${file}.${process.pid}.part`
+    writeFileSync(part, JSON.stringify({ cli, sources, answer } satisfies Kept))
+    renameSync(part, file)
+}
+
 /** 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 */
+ *  once per process (the prune and a watch read many cuts), and not at all while its last answer's sources hold */
 export function readVocab(root: string, cli: readonly string[] | null): FilmVerb[] | null {
     if (cli === null) return null
-    const k = `${root}\0${cli.join(' ')}`
+    const line = cli.join(' ')
+    const k = `${root}\0${line}`
     const had = asked.get(k)
     if (had) return had
+    const kept = keptAnswer(root, line)
+    if (kept !== null) {
+        const rows = filmRows(kept)
+        asked.set(k, rows)
+        return rows
+    }
+    const at = Date.now()
     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}`)
-        const rows = filmRows(JSON.parse(text))
+        const answer: unknown = JSON.parse(text)
+        const rows = filmRows(answer)
         asked.set(k, rows)
+        keep(root, line, answer, at)
         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')}` : ''}`)