rvlib-shipkit 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.6.0
+
+- **A trailer's score sounds as the game's browser synth, section for section.** A note that starts inside a 128 frame block takes the phase the browser gives it (it runs at the default 440 Hz until its own frame of that block), so overlapping notes of one pitch, a timpani roll, add or cancel as in the browser; `osc: 'square'` is the browser's own square wave, no longer a sine; the master's compressor and limiter are the browser's kernel (32 frame divisions, adaptive release, the sine warp on the gain). pkm-multi's main4 score: 38 of 38 sections within 0.1 dB of the game's render (were 18), each octave band within 0.15 dB. Every score renders again once.
+
 ## 2.5.0
 
 - **A review card hands itself to any agent session.** A small copy icon on the card's header (or C) copies one block: its title and state, its repo, `cd <repo> && sk review show <id>`, its link here and on the phone when the repo has a public host; a toast says what was copied. `sk review show <id> --paste` prints the same block.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/trailer/build.ts

@@ -629,10 +629,11 @@ function shelve(l: Loaded, takes: readonly Take[]): void {
 
 /** the cache trimmed after a stitch, said in one line */
 async function pruneAfter(root: string, say: Say): Promise<void> {
-    const { prune, sayPruned } = await import('./prune.ts')
+    const { pruneIfMoved, sayPruned } = await import('./prune.ts')
     // the cut is written: a prune that fails is said, never the build's failure
     try {
-        for (const line of sayPruned(await prune(root, { dry: false }), false, true)) say(line)
+        const p = await pruneIfMoved(root)
+        for (const line of p === null ? ['cache prune skipped: nothing it reads moved since the last one'] : sayPruned(p, false, true)) say(line)
     } catch (e) {
         say(`WARN the cache prune failed, the cut is written: ${(e as Error).message}`)
     }

package/src/trailer/grammar.ts

@@ -167,11 +167,12 @@ export interface Title {
 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 colour as a line writes it: `#rgb`, `#rrggbb`, or one of the look's (titles.ts resolves it) */
+/** a colour as a line writes it: `#rgb`, `#rrggbb`, `#rrggbbaa`, or one of the look's (titles.ts resolves it) */
 export const LOOK_COLOURS = ['light', 'edge', 'accent'] as const
 
 /** a title's look over its style's: its face (a font file or a Google Fonts family), weight, size in pixels of a frame
- *  1080 tall, fill, and its outline, shadow and glow, each a size in those pixels and a colour */
+ *  1080 tall, fill (a gradient's colours each `colour[@share]`, top to bottom), and its outline, inner stroke, drop,
+ *  shadow (and its fall) and glow, each a size in those pixels and a colour; a logo's layout (LOGO_WORDS) */
 export interface TitleFx {
     font?: string
     weight?: number
@@ -179,10 +180,25 @@ export interface TitleFx {
     color?: string
     gradient?: string[]
     outline?: { px: number; color?: string }
-    shadow?: { px: number; color?: string }
+    inner?: { px: number; color?: string }
+    drop?: { px: number; color?: string }
+    shadow?: { px: number; color?: string; dy?: number }
     glow?: { px: number; color?: string }
+    /** the widest share of the frame's width the word takes */
+    fit?: number
+    /** the subtitle's height to the word's */
+    sub?: number
+    /** the space between the word and its subtitle, a share of the word's height */
+    gap?: number
+    /** the word's middle at this share of the frame's height (default: the whole block's middle at 0.48) */
+    middle?: number
+    /** the soft shade round the logo, its radius a share of the frame's longer side; 0 for none */
+    shade?: number
 }
 
+/** the look words only a logo title reads */
+export const LOGO_WORDS = ['fit', 'sub', 'gap', 'middle', 'shade'] as const
+
 /** how a made sound is made (design call 9): its seed, the voice or engine it is made `by`, its length (`for`), an sfx
  *  trimmed to its first `hit` */
 export interface SoundGen {
@@ -403,8 +419,8 @@ interface Word {
 
 /** a line's words: a quoted run is one word (quoted), `#` outside quotes ends the line. Only double quotes quote, as in
  *  the full language, so a word opening on a single quote is refused: it would reach a command with the quotes inside */
-/** a hex colour at `k` (`#rgb`, `#rrggbb`, then the word's end or a comma): a word, never a comment */
-const colourAt = (line: string, k: number): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6})(?=[\s,"]|$)/i.test(line.slice(k))
+/** a hex colour at `k` (`#rgb`, `#rrggbb`, `#rrggbbaa`, then the word's end, a comma or a gradient place `@`): a word, never a comment */
+const colourAt = (line: string, k: number): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})(?=[\s,"@]|$)/i.test(line.slice(k))
 
 export function tokens(line: string): { words: Word[] } | { error: string } {
     const words: Word[] = []
@@ -511,9 +527,9 @@ const sizeWord = (what: string, w: Word | undefined, lo: number, hi: number): [n
     return [x, y]
 }
 
-/** a colour word: `#rgb`, `#rrggbb`, or the look's light, edge or accent */
+/** a colour word: `#rgb`, `#rrggbb`, `#rrggbbaa` (its last two digits the alpha), or the look's light, edge or accent */
 const colour = (k: string, text: string | undefined): string => {
-    if (!text || !/^(#[0-9a-f]{3}|#[0-9a-f]{6}|light|edge|accent)$/i.test(text)) return bad(`${k} wants a colour: #rgb, #rrggbb, ${LOOK_COLOURS.join(', ')}${text ? `, got ${text}` : ''}`)
+    if (!text || !/^(#[0-9a-f]{3}|#[0-9a-f]{6}|#[0-9a-f]{8}|light|edge|accent)$/i.test(text)) return bad(`${k} wants a colour: #rgb, #rrggbb, #rrggbbaa, ${LOOK_COLOURS.join(', ')}${text ? `, got ${text}` : ''}`)
     return text
 }
 /** `<px>[,<colour>]`: an outline, a shadow or a glow, its size in pixels of a frame 1080 tall */
@@ -524,8 +540,19 @@ const sized = (w: Word | undefined, k: string): { px: number; color?: string } =
     if (!Number.isFinite(px) || px < 0 || px > 300 || more !== undefined) return bad(`${k} wants <px>[,<colour>], its size 0 to 300, got ${w.text}`)
     return { px, ...(c !== undefined ? { color: colour(k, c) } : {}) }
 }
+/** `<px>[,<colour>[,<fall>]]`: a shadow's blur, its colour and how far it falls (default a third of its blur) */
+const shadowWord = (w: Word | undefined, k: string): { px: number; color?: string; dy?: number } => {
+    const [head, ...fall] = w && !w.quoted ? w.text.split(',') : []
+    const wrong = (): never => bad(`${k} wants <px>[,<colour>[,<fall>]], its fall 0 to 300, got ${w!.text}`)
+    if (fall.length > 2) return wrong()
+    const base = sized(w && fall.length === 2 ? { ...w, text: `${head},${fall[0]}` } : w, k)
+    if (fall.length < 2) return base
+    const dy = Number(fall[1])
+    if (!/^\d+(\.\d+)?$/.test(fall[1]!) || dy > 300) return wrong()
+    return { ...base, dy }
+}
 /** a title's look words, in TitleFx */
-const FX_WORDS = ['font', 'weight', 'size', 'color', 'gradient', 'outline', 'shadow', 'glow'] as const
+const FX_WORDS = ['font', 'weight', 'size', 'color', 'gradient', 'outline', 'inner', 'drop', 'shadow', 'glow', ...LOGO_WORDS] as const
 const TITLE_WORDS: Record<string, (w: Word | undefined, k: string) => unknown> = {
     style: (w, k) => word(k, w, /^[a-z][a-z0-9-]*$/),
     at: when,
@@ -544,12 +571,23 @@ const TITLE_WORDS: Record<string, (w: Word | undefined, k: string) => unknown> =
     color: (w, k) => colour(k, w && !w.quoted ? w.text : undefined),
     gradient: (w, k) => {
         const cs = w && !w.quoted ? w.text.split(',') : []
-        if (cs.length < 2 || cs.length > 4) bad(`${k} wants two to four colours, top to bottom: light,accent`)
-        return cs.map((c) => colour(k, c))
+        if (cs.length < 2 || cs.length > 4) bad(`${k} wants two to four colours, top to bottom: light,accent (a colour's place colour@0.6)`)
+        return cs.map((c) => {
+            const [col, at] = c.split('@')
+            if (at !== undefined && !/^(0(\.\d+)?|1(\.0+)?)$/.test(at)) bad(`${k}: a colour's place is a share from 0 to 1, got ${c}`)
+            return at === undefined ? colour(k, col) : `${colour(k, col)}@${at}`
+        })
     },
     outline: sized,
-    shadow: sized,
+    inner: sized,
+    drop: sized,
+    shadow: shadowWord,
     glow: sized,
+    fit: (w, k) => num(k, w, 0.1, 1),
+    sub: (w, k) => num(k, w, 0.05, 1),
+    gap: (w, k) => num(k, w, 0, 1),
+    middle: (w, k) => num(k, w, 0, 1),
+    shade: (w, k) => num(k, w, 0, 2),
 }
 
 /** a title's words, in order, each `+<preset>` in place; `in` and `out` take a move and, when the next word is a
@@ -589,6 +627,11 @@ function readTitleWords(raw: Word[], presets: ReadonlyMap<string, Word[]>, what
 /** a title's look words out of read values */
 const fxOf = (v: Record<string, unknown>): TitleFx => Object.fromEntries(FX_WORDS.filter((k) => v[k] !== undefined).map((k) => [k, v[k]])) as TitleFx
 const builtInStyle = (st: string): st is TitleStyle => (TITLE_STYLES as readonly string[]).includes(st)
+/** a logo word on a title of another style fails: nothing would read it */
+const logoOnly = (style: TitleStyle, fx: TitleFx | undefined): void => {
+    const odd = LOGO_WORDS.filter((w) => fx?.[w] !== undefined)
+    if (style !== 'logo' && odd.length > 0) bad(`title ${odd.join(', ')}: a logo's words, this title is ${style}`)
+}
 
 /** the brand's text styles (`trailer.styles`, each a title's words by name) laid under each title: the defaults of
  *  its built in style, then the brand style it names, then its own words, a later one winning. A brand style names
@@ -621,6 +664,7 @@ export function resolveStyles(t: Pick<Trailer, 'shots'>, styles: Readonly<Record
                 const under = { ...defaults, ...named }
                 ti.style = base as TitleStyle
                 const fx = { ...fxOf(under), ...ti.fx }
+                logoOnly(ti.style, fx)
                 if (Object.keys(fx).length > 0) ti.fx = fx
                 if (under.place && !ti.place) ti.place = under.place as 'top' | 'bottom'
                 if (under.in && !ti.in) ti.in = under.in as Move
@@ -1323,6 +1367,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                         ...(p.out ? { out: p.out as Move } : {}),
                     }
                     const fx = fxOf(p)
+                    if (!ti.named) logoOnly(ti.style, fx)
                     if (Object.keys(fx).length > 0) ti.fx = fx
                     if (ti.knock !== undefined && ti.out) bad('title: knock is its exit, give out or knock, not both')
                     ti.at = landAt(p.at, n, s, (v) => (ti.at = v))

package/src/trailer/look.ts

@@ -8,18 +8,26 @@ export interface TrailerLookInput {
     light?: string
     /** the dark edge under words over footage (default: the ground's edge) */
     edge?: string
+    /** the soft band of shade behind a `line` title's words (default: the edge) */
+    band?: string
     /** the key colour: the caption's dot, a `line` title's `*word*`, the corner chip (default: the palette's accent) */
     accent?: string
-    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) */
-    plate?: { fill?: string; line?: string; ink?: string }
-    /** the corner chip (default: the accent, ink of the palette's bg) */
-    chip?: { fill?: string; ink?: string }
+    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) and the soft drop under it
+     *  and under the chip (default: the edge) */
+    plate?: { fill?: string; line?: string; ink?: string; shadow?: string }
+    /** the corner chip (default: the accent, ink of the palette's bg, an outline a shade darker than its fill) */
+    chip?: { fill?: string; ink?: string; line?: string }
     /** the face: a font file (repo relative, .ttf .otf .woff2) or a family the machine has, and its heavy weight */
     font?: { file?: string; family?: string; weight?: number }
-    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present) */
-    logo?: string
-    /** the words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left out */
-    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string }
+    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present);
+     *  `false`: the word alone */
+    logo?: string | false
+    /** a `logo` title's subtitle: its colour (default: the light) and the colour of its soft glow (default: the edge) */
+    subtitle?: { color?: string; glow?: string }
+    /** the words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left
+     *  out; `band` the shade behind them (default: their edge), `lit` the glow round a progress bar's newest notch
+     *  (default: their accent) */
+    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string; band?: string; lit?: string }
     /** the vertical short's look (a `vertical` cut), each part `false` to leave it out (vertical.ts) */
     vertical?: VerticalLookInput
     /** text styles by name, each a title line's words (`style big font "Bebas Neue" in letters`): a title's `style`
@@ -44,13 +52,15 @@ export interface TrailerLook {
     ground: [string, string]
     light: string
     edge: string
+    band: string
     accent: string
-    plate: { fill: string; line: string; ink: string }
-    chip: { fill: string; ink: string }
+    plate: { fill: string; line: string; ink: string; shadow: string }
+    chip: { fill: string; ink: string; line: string }
     font: { file: string | null; family: string; weight: number }
     logo: string | null
+    subtitle: { color: string; glow: string }
     /** the short's words: their face and colours */
-    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string }
+    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string; band: string; lit: string }
 }
 
 export interface BrandLike {
@@ -108,20 +118,25 @@ export function lookOf(brand: BrandLike | null, webLogo: string | null = null):
     const light = i.light ?? (luminance(p.ink) > 0.45 ? p.ink : '#ffffff')
     const edge = i.edge ?? (luminance(ground[1]) < 0.2 ? ground[1] : darker(p.bg, 0.8))
     const accent = i.accent ?? p.accent
+    const chipFill = i.chip?.fill ?? p.accent
     const sh = i.short ?? {}
+    const shortEdge = sh.edge ?? edge
+    const shortAccent = sh.accent ?? accent
     const shortFont = sh.font ? { file: sh.font.file ?? null, family: sh.font.family ?? (sh.font.file ? 'TrailerShortFace' : font.family), weight: sh.font.weight ?? font.weight } : font
     return {
         ground,
         light,
         edge,
+        band: i.band ?? edge,
         accent,
-        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink },
-        chip: { fill: i.chip?.fill ?? p.accent, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff') },
+        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink, shadow: i.plate?.shadow ?? alpha(edge, 0.4) },
+        chip: { fill: chipFill, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff'), line: i.chip?.line ?? darker(chipFill, 0.15) },
         font: { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 },
-        logo: i.logo ?? webLogo,
-        short: { font: shortFont, light: sh.light ?? light, edge: sh.edge ?? edge, accent: sh.accent ?? accent },
+        logo: i.logo === false ? null : (i.logo ?? webLogo),
+        subtitle: { color: i.subtitle?.color ?? light, glow: i.subtitle?.glow ?? edge },
+        short: { font: shortFont, light: sh.light ?? light, edge: shortEdge, accent: shortAccent, band: sh.band ?? shortEdge, lit: sh.lit ?? shortAccent },
     }
 }
 
 /** the look a short's words wear: the look with the short's face and colours in place */
-export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent })
+export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent, band: look.short.band })

package/src/trailer/prune.ts

@@ -1,7 +1,8 @@
 // the trailer's cache kept small (wiki build/trailer.md, The cache): what the cuts of every trailer folder still use
-// stays, the rest goes. Runs after every stitch and by hand (`sk trailer prune [--dry]`). What a cut uses is named by the
-// build's own key functions; a file younger than an hour is never deleted: another build may be writing or reading it
-import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+// stays, the rest goes. Runs after a stitch when what it reads moved, and by hand (`sk trailer prune [--dry]`). What a
+// cut uses is named by the build's own key functions; a file younger than an hour is never deleted: another build may
+// be writing or reading it
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { basename, join, relative } from 'node:path'
 import { cutFiles, load } from './build.ts'
 import { SCORE, musicCues } from './grammar.ts'
@@ -159,12 +160,10 @@ function filesUnder(dir: string): string[] {
     return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)]))
 }
 
-/** plans every folder's prune, then deletes unless `dry` */
-export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
-    const now = o.now ?? Date.now()
-    const [{ trailerCache }, { viewsToDrop }] = await Promise.all([import('./footage.ts'), import('../review/trailer-desk.ts')])
-    const cache = join(trailerCache(root, 'footage'), '..')
-    const live = await liveSet(root)
+const cacheOf = async (root: string): Promise<string> => join((await import('./footage.ts')).trailerCache(root, 'footage'), '..')
+
+/** each folder's files that go, as of `now`; `now` Infinity names the files only their age keeps too */
+function planOf(cache: string, live: Live, views: readonly string[], now: number): [string, Doomed[]][] {
     const whole = live.broken.length === 0
     // titles/ holds the vertical's drawings too: only a title's and a card's files are the prune's
     const ownTitle = (n: string): boolean => /^(title|card)-[0-9a-f]{16}\./.test(n)
@@ -177,10 +176,58 @@ export async function prune(root: string, o: { dry: boolean; now?: number }): Pr
     ]
     const dead = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name)) : []
     for (const d of dead) plan.push([`${d.name}/ (dead)`, filesUnder(join(cache, d.name)).map(doomed)])
-    plan.push(['trailer-view/', viewsToDrop(root).filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
-    if (!o.dry) {
+    plan.push(['trailer-view/', views.filter((f) => existsSync(f) && now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
+    return plan
+}
+
+/** what the last whole prune read, and when the first file it spared for its age comes of age */
+interface Stamp {
+    key: string
+    until: number
+}
+
+const stampFile = (cache: string): string => join(cache, 'prune.json')
+
+/** what the prune reads that a build can change: every cut's text, every file name in the cache's folders, the views
+ *  to drop. The same key and no spared file of age: the prune would find what it found */
+async function pruneKey(root: string, cache: string): Promise<string> {
+    const [{ cutFiles }, { viewsToDrop }] = await Promise.all([import('./build.ts'), import('../review/trailer-desk.ts')])
+    const h = new Bun.CryptoHasher('sha1')
+    for (const f of cutFiles(root)) h.update(`${f}\0`).update(readFileSync(f)).update('\0')
+    const folders = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory()) : []
+    for (const d of folders.map((e) => e.name).sort()) h.update(`${d}/\0${filesUnder(join(cache, d)).sort().join('\0')}\0`)
+    h.update(viewsToDrop(root).sort().join('\0'))
+    return h.digest('hex')
+}
+
+/** the prune after a build: skipped while nothing it reads moved and no file it spared has come of age */
+export async function pruneIfMoved(root: string, now = Date.now()): Promise<Pruned | null> {
+    const cache = await cacheOf(root)
+    let s: Stamp | null = null
+    try {
+        s = JSON.parse(readFileSync(stampFile(cache), 'utf8')) as Stamp
+    } catch {}
+    if (s !== null && now < s.until && s.key === (await pruneKey(root, cache))) return null
+    return prune(root, { dry: false, now })
+}
+
+/** plans every folder's prune, then deletes unless `dry`; a whole prune writes its stamp */
+export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
+    const now = o.now ?? Date.now()
+    const { viewsToDrop } = await import('../review/trailer-desk.ts')
+    const cache = await cacheOf(root)
+    const live = await liveSet(root)
+    const views = viewsToDrop(root)
+    const plan = planOf(cache, live, views, now)
+    if (!o.dry && existsSync(cache)) {
         for (const [, ds] of plan) for (const d of ds) rmSync(d.file, { force: true })
-        for (const d of dead) rmSync(join(cache, d.name), { recursive: true, force: true })
+        for (const d of readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name))) rmSync(join(cache, d.name), { recursive: true, force: true })
+        rmSync(stampFile(cache), { force: true })
+        if (live.broken.length === 0) {
+            const spared = planOf(cache, live, views, Number.POSITIVE_INFINITY).flatMap(([, ds]) => ds.filter((d) => existsSync(d.file)))
+            const until = Math.min(Number.MAX_SAFE_INTEGER, ...spared.map((d) => statSync(d.file).mtimeMs + RENDER_GRACE_MS))
+            writeFileSync(stampFile(cache), JSON.stringify({ key: await pruneKey(root, cache), until } satisfies Stamp))
+        }
     }
     return {
         freed: plan.map(([folder, ds]) => ({ folder, files: ds.length, bytes: ds.reduce((n, d) => n + (d.linked ? 0 : d.bytes), 0), linked: ds.reduce((n, d) => n + (d.linked ? d.bytes : 0), 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')}` : ''}`)