rvlib-shipkit 2.5.0 → 2.7.0

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')}` : ''}`)