rvlib-shipkit 2.4.0 → 2.6.0

package/src/serve/run-serve.ts

@@ -5,7 +5,11 @@
 import { basename } from 'path'
 import { reclaimPreviousImage } from '../core/instance.ts'
 import { isLinkedWorktree } from '../core/git-root.ts'
+import { heldNow, heldText, OWN_LIB, setHeld } from '../core/last-good.ts'
 import { diskLibVersion, LIB_VERSION } from '../core/lib-version.ts'
+import { bootEntries, probeLoad, TreeProbe } from '../core/load-probe.ts'
+import { LibWatch } from '../home/lib-watch.ts'
+import type { LoadVerdict } from './stale-restart.ts'
 import { reexecBlocker, reexecSelf } from '../core/reexec.ts'
 import { attachToHome } from '../home/attach.ts'
 import { daemonUp, WORKER_ENV } from '../home/home-paths.ts'
@@ -21,6 +25,14 @@ export type { ServeIo }
 /** how often a hub of its own looks at its plan */
 export const PLAN_TICK_MS = 2_000
 
+/** does the lib this hub would restart onto load: probed again after every
+ *  write to its tree, not only when the version moves */
+export function serveProbe(lib: string): { loads: () => LoadVerdict; stop: () => void } {
+    const w = new LibWatch(lib)
+    const p = new TreeProbe(() => probeLoad(lib, bootEntries(lib, 'serve')), () => `${w.seq}|${diskLibVersion()}`)
+    return { loads: () => p.loads(), stop: () => w.close() }
+}
+
 /** what a `shipkit serve` does with its hub. On a machine with a home, no
  *  hub runs outside it: a home that answers takes it, and an installed one
  *  that does not is started first. `serve` only inside the home, a linked
@@ -104,6 +116,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     // a file table the watch restarts leaked: it re-executes itself in
     // place (same pid, argv, port) once no run is in flight. Only a
     // restart that throws is said, in the hub's own status
+    const probe = serveProbe(OWN_LIB)
     const stale = new StaleRestart({
         boot: LIB_VERSION,
         disk: diskLibVersion,
@@ -114,6 +127,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             if (blocked != null) throw new Error(blocked)
             io.print(`ok: ${why}: restarting in place`)
             stale.stop()
+            probe.stop()
             clearInterval(planClock)
             rt.stop()
             hub.stop()
@@ -126,6 +140,16 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             }
         },
         say: (text) => deps.hubProblems?.set('stale', text == null ? null : { text, severity: 'red' }),
+        // a version move restarts only onto code that loads; the held line is the hub's (serve-hub.ts)
+        loads: () => probe.loads(),
+        hold: (v) => {
+            if (v == null) return setHeld(null)
+            const was = heldNow()
+            if (was?.file === v.file && was.error === v.error) return
+            const h = { since: was?.since ?? Date.now(), file: v.file, error: v.error, from: OWN_LIB, copyAt: null }
+            io.printErr(`WARN ${heldText(h)}`)
+            setHeld(h)
+        },
     })
     stale.start()
     // a watch restart that leaked sheds it before the first run spawns anything
@@ -140,6 +164,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     for (const sig of ['SIGINT', 'SIGTERM'] as const)
         process.on(sig, () => {
             stale.stop()
+            probe.stop()
             clearInterval(planClock)
             plan.stop()
             rt.stop()

package/src/serve/serve-hub.ts

@@ -31,6 +31,7 @@ import { RUN_EXIT } from '../home/home-words.ts'
 import { projectGutter } from './project-gutter-route.ts'
 import { sameOrigin } from './same-origin.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { heldNow, heldText } from '../core/last-good.ts'
 import { WarmCell } from './warm-cell.ts'
 import { readmeRoutes } from './readme-route.ts'
 import { reviewRoutes } from '../review/routes.ts'
@@ -246,7 +247,7 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
                     collections: r.collections,
                     resources: r.resources,
                     planned: d.planned?.() ?? null,
-                    hub: d.hubProblems?.list() ?? [],
+                    hub: [...(d.hubProblems?.list() ?? []), ...heldProblem()],
                 })
             }
             // the previous address, answered while pages opened before the
@@ -427,6 +428,12 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
     }
 }
 
+/** the machine runs older code than its tree: every hub's header says so */
+const heldProblem = (): { id: string; text: string; severity: 'yellow' }[] => {
+    const h = heldNow()
+    return h == null ? [] : [{ id: 'last-good', text: heldText(h), severity: 'yellow' }]
+}
+
 export function serveHub(d: HubDeps, h: HubHandler = hubHandler(d)): Hub {
     const server: Server = Bun.serve({
         hostname: '127.0.0.1',

package/src/serve/stale-restart.ts

@@ -7,10 +7,14 @@
 // watch fds, and a full table fails every spawn with EBADF. Either way it
 // re-executes in place (core/reexec.ts) once no run is in flight, which is a
 // clean table too. Only a restart that throws reaches a human, once, through
-// `say`.
+// `say`. With `loads`, it restarts only onto code that loads: while the tree
+// fails, it keeps the running image and tells `hold` why.
 import { assertLeakHealable, FD_HEALED_ENV, fdTableLeak } from '../core/fd-table.ts'
 
-export type StaleTick = 'fresh' | 'busy' | 'restarted' | 'impossible'
+export type StaleTick = 'fresh' | 'busy' | 'probing' | 'held' | 'restarted' | 'impossible'
+
+/** does the code a restart would run load: `pending` while a probe runs */
+export type LoadVerdict = 'ok' | 'pending' | { file: string; error: string }
 
 export type StaleRestartOpts = {
     /** the version this process booted with */
@@ -30,6 +34,10 @@ export type StaleRestartOpts = {
     /** the hub's status line: a text when the restart is impossible, null
      *  once there is nothing to say */
     say: (text: string | null) => void
+    /** asked once a restart is due, never before (core/load-probe.ts) */
+    loads?: () => LoadVerdict
+    /** why the due restart waits: a file of the tree fails to load. Null once it loads */
+    hold?: (why: { file: string; error: string } | null) => void
     everyMs?: number
 }
 
@@ -47,6 +55,15 @@ export class StaleRestart {
         }
         if (this.failed != null) return 'impossible'
         if (this.o.busy()) return 'busy'
+        if (this.o.loads != null) {
+            const v = this.o.loads()
+            if (v === 'pending') return 'probing'
+            if (v !== 'ok') {
+                this.o.hold?.(v)
+                return 'held'
+            }
+            this.o.hold?.(null)
+        }
         try {
             if (stale.leak) {
                 assertLeakHealable()

package/src/trailer/build.ts

@@ -504,7 +504,7 @@ export async function scoreFile(l: Loaded, seconds: number, say: Say): Promise<s
 /** everything the stitch reads but its output: sources, titles, sounds, the look */
 async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Shot[], silent: boolean, say: Say = () => undefined) {
     const { gridMask, splitMasks } = await import('./stitch.ts')
-    const [{ cardPng, titlePng }, { lookOf }, { duration }, { trailerCache }, { loadBrand, identityLogo }] = await Promise.all([
+    const [{ cardPng, titlePng }, { lookOf }, { durationOf }, { trailerCache }, { loadBrand, identityLogo }] = await Promise.all([
         import('./titles.ts'),
         import('./look.ts'),
         import('./ffmpeg.ts'),
@@ -534,7 +534,7 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
         if (f.kind === 'image') return { image: fileOf(f.path, l)! }
         if (f.kind === 'clip') {
             const file = fileOf(f.path, l)!
-            return { footage: file, seconds: duration(file) }
+            return { footage: file, seconds: await durationOf(file) }
         }
         const tk = takeOf(s)!
         return tk.stamp!.seconds === 0 ? { image: tk.file } : { footage: tk.file, seconds: tk.stamp!.seconds }
@@ -556,11 +556,11 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
     )
     const sfx = await Promise.all(shots.map((s) => Promise.all(s.sfx.map(async (x) => {
         const file = isFileSound(x.id, x) ? fileOf(x.id, l)! : await resolve(ask('sfx', x.id, x))
-        return { file, seconds: duration(file) }
+        return { file, seconds: await durationOf(file) }
     }))))
     const voices = await Promise.all(shots.map((s) => Promise.all(s.voices.map(async (v) => {
         const file = v.file ? fileOf(v.file, l)! : await resolve(ask('voice', v.text ?? 'run', v))
-        return { file, seconds: duration(file) }
+        return { file, seconds: await durationOf(file) }
     }))))
     return { ...base, sources, titles: drawn, music, sfx, voices }
 }
@@ -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}`)
     }
@@ -655,7 +656,15 @@ export async function build(l: Loaded, o: BuildOptions): Promise<string> {
     const done = await stitch({ ...input, t: l.t, out: cut, cache: trailerCache(l.root, 'pieces'), encoder: o.final ? 'final' : 'draft' })
     const finished = l.t.vertical ? await finishVertical(l, input, done, cut, out, o.final) : null
     const stripFile = join(outDir(l), `${l.t.name}.strip.png`)
-    await strip(done.pieces, stripFile)
+    // the strip is drawn from the pieces' thumbs: the same pieces draw the same strip, so a build that rendered no
+    // section keeps it
+    const stripKey = join(trailerCache(l.root, 'pieces'), `${l.t.name}.strip.key`)
+    const key = done.pieces.map((p) => p.thumbs).join('\n')
+    const drawn = (): string => `${key}\n${statSync(stripFile).mtimeMs}`
+    if (!existsSync(stripFile) || !existsSync(stripKey) || readFileSync(stripKey, 'utf8') !== drawn()) {
+        await strip(done.pieces, stripFile)
+        writeFileSync(stripKey, drawn())
+    }
     writeFileSync(join(outDir(l), `${l.t.name}.montage.md`), montage(l.t, basename(l.file)))
     for (const line of timeline(l, takes, world, o.cwd)) o.say(line)
     o.say(`ok: ${out} (${(finished?.seconds ?? total(l.t)).toFixed(2)} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s: filming ${((tFilm - t0) / 1000).toFixed(1)} s, ${rendered(done)}${finished ? `, ${finished.note}` : ''}`)

package/src/trailer/ffmpeg.ts

@@ -1,7 +1,7 @@
 // the one way the trailer spawns ffmpeg and ffprobe: a run that fails loud with ffmpeg's own words, a probe, the nine
 // frame sheet. The binaries resolve once, with the homebrew path for processes started without it
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 const FFMPEG = Bun.which('ffmpeg') ?? '/opt/homebrew/bin/ffmpeg'
@@ -38,6 +38,26 @@ export function duration(file: string): number {
     return d
 }
 
+const probed = new Map<string, Promise<number>>()
+
+/** a media file's length like `duration`, probed once per file and state in this process, the probes side by side: a
+ *  cut that plays one sfx on many lines asks once */
+export function durationOf(file: string): Promise<number> {
+    const st = statSync(file)
+    const k = `${file}\0${st.size}\0${st.mtimeMs}`
+    const had = probed.get(k)
+    if (had) return had
+    const p = (async () => {
+        const r = Bun.spawn([FFPROBE, '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })
+        const [out, err, code] = await Promise.all([new Response(r.stdout).text(), new Response(r.stderr).text(), r.exited])
+        const d = Number(out.trim())
+        if (code !== 0 || !(d > 0)) throw new Error(`ffprobe ${file}: ${err.trim() || 'no length'}`)
+        return d
+    })()
+    probed.set(k, p)
+    return p
+}
+
 /** the media file carries a sound stream */
 export function hasAudio(file: string): boolean {
     const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })

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) })),