rvlib-shipkit 2.1.0 → 2.2.0

package/src/trailer/stitch.ts

@@ -0,0 +1,150 @@
+// the stitch: the cut rendered piece by piece (a piece = a section), each cached on its ffmpeg arguments and the size
+// and time of every file it reads, so an edit renders only the pieces it touches. The pieces join with no second
+// encode, the sound is mixed once (cached the same way) and muxed beside them, and the strip lays out each piece's row
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { availableParallelism } from 'node:os'
+import { dirname, join } from 'node:path'
+import sharp from 'sharp'
+import { ffmpeg } from './ffmpeg.ts'
+import { type Encoder, mixArgs, pieceArgs, type StitchInput, THUMB_W } from './graph.ts'
+import { type Piece, pieces } from './plan.ts'
+
+/** bump when the stitch changes what the same arguments make */
+const STITCH_VERSION = 1
+
+/** the files an ffmpeg command reads */
+const inputsOf = (args: string[]): string[] => args.flatMap((x, i) => (args[i - 1] === '-i' && existsSync(x) ? [x] : []))
+
+/** a render's key: its arguments (the outputs named alike) and every file it reads as it stands: a refilm rewrites a
+ *  take in place, so its size and time count */
+function keyOf(args: string[]): string {
+    const reads = inputsOf(args).map((f) => {
+        const s = statSync(f)
+        return [f, s.size, s.mtimeMs]
+    })
+    return new Bun.CryptoHasher('sha1').update(JSON.stringify([STITCH_VERSION, args, reads])).digest('hex').slice(0, 16)
+}
+
+/** a render kept under its key, one file per extension (the first always made, the others when the render has them):
+ *  made only when missing, written aside then moved in place, the first last */
+async function cached(dir: string, stem: string, exts: string[], make: (outs: string[]) => string[]): Promise<{ files: string[]; made: boolean }> {
+    return cachedAs(dir, stem, keyOf(make(exts.map((e) => `out.${e}`))), exts, make)
+}
+
+/** a render kept under a key its caller computed: for one whose inputs are rewritten by every build */
+export async function cachedAs(dir: string, stem: string, key: string, exts: string[], make: (outs: string[]) => string[]): Promise<{ files: string[]; made: boolean }> {
+    const files = exts.map((e) => join(dir, `${stem}-${key}.${e}`))
+    if (existsSync(files[0]!)) {
+        const now = new Date()
+        for (const f of files) if (existsSync(f)) utimesSync(f, now, now)
+        return { files, made: false }
+    }
+    mkdirSync(dir, { recursive: true })
+    const parts = exts.map((e) => join(dir, `${stem}-${key}.part.${e}`))
+    try {
+        await ffmpeg(make(parts), { nice: 10 })
+        for (let i = parts.length - 1; i >= 0; i--) if (existsSync(parts[i]!)) renameSync(parts[i]!, files[i]!)
+    } finally {
+        for (const f of parts) rmSync(f, { force: true })
+    }
+    return { files, made: true }
+}
+
+/** runs the jobs, at most `n` at once */
+export async function pool<T>(jobs: (() => Promise<T>)[], n: number): Promise<T[]> {
+    const out: T[] = []
+    let next = 0
+    const lane = async (): Promise<void> => {
+        while (next < jobs.length) {
+            const i = next++
+            out[i] = await jobs[i]!()
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(n, jobs.length) }, lane))
+    return out
+}
+
+/** how many pieces render at once: a graph runs mostly on one core */
+const LANES = Math.max(1, Math.min(4, Math.floor(availableParallelism() / 2)))
+
+export interface Stitched {
+    /** the pieces, each with whether this run rendered it, its video and its row of the contact strip */
+    pieces: (Piece & { made: boolean; file: string; thumbs: string })[]
+    /** the sound was mixed again */
+    mixed: boolean
+    /** the mix file, null for a silent stitch */
+    mix: string | null
+}
+
+export interface StitchRun extends StitchInput {
+    out: string
+    /** where the rendered pieces and the mix are kept */
+    cache: string
+    encoder?: Encoder
+    /** no sound at all: a shot's preview */
+    silent?: boolean
+}
+
+async function renderPieces(a: StitchRun, ps: Piece[]): Promise<Stitched['pieces']> {
+    return pool(
+        ps.map((p) => async () => {
+            const { files, made } = await cached(a.cache, `${a.t.name}-${p.name}`, ['mp4', 'png'], ([video, row]) => pieceArgs(a, p, video!, a.encoder, row))
+            return { ...p, made, file: files[0]!, thumbs: files[1]! }
+        }),
+        LANES,
+    )
+}
+
+async function renderMix(a: StitchRun): Promise<{ file: string; made: boolean }> {
+    const { files, made } = await cached(join(a.cache, 'mix'), `mix-${a.t.name}`, ['m4a'], ([out]) => mixArgs(a, out!))
+    return { file: files[0]!, made }
+}
+
+/** the pieces joined as they are, no encode, with the sound beside them */
+async function joinPieces(files: string[], sound: string | null, out: string): Promise<void> {
+    mkdirSync(dirname(out), { recursive: true })
+    const list = `${out}.list.txt`
+    writeFileSync(list, files.map((f) => `file '${f.replaceAll("'", "'\\''")}'`).join('\n'))
+    const part = out.replace(/(\.\w+)$/, '.part$1')
+    try {
+        await ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, ...(sound ? ['-i', sound] : []), '-map', '0:v', ...(sound ? ['-map', '1:a', '-c:a', 'copy'] : []), '-c:v', 'copy', '-movflags', '+faststart', part], { nice: 10 })
+        renameSync(part, out)
+    } finally {
+        rmSync(list, { force: true })
+        rmSync(part, { force: true })
+    }
+}
+
+/** the whole cut: every piece (rendered where the cache misses it), joined, with its sound */
+export async function stitch(a: StitchRun): Promise<Stitched> {
+    const [ps, mix] = await Promise.all([renderPieces(a, pieces(a.t)), a.silent ? null : renderMix(a)])
+    await joinPieces(ps.map((p) => p.file), mix?.file ?? null, a.out)
+    return { pieces: ps, mixed: mix?.made ?? false, mix: mix?.file ?? null }
+}
+
+/** one frame from the middle of each shot, side by side, rows of six: the cut at a glance. Each piece drew its own
+ *  row as it rendered, so the strip only lays the rows out */
+export async function strip(ps: Pick<Stitched['pieces'][number], 'thumbs'>[], out: string): Promise<void> {
+    const rows = await Promise.all(ps.filter((p) => existsSync(p.thumbs)).map((p) => sharp(p.thumbs).removeAlpha().raw().toBuffer({ resolveWithObject: true })))
+    const h = rows[0]?.info.height ?? 0
+    const cells = rows.flatMap(({ data, info }) => Array.from({ length: Math.round(info.width / THUMB_W) }, (_, k) => ({ data, left: k * THUMB_W, width: info.width })))
+    if (cells.length === 0) return
+    const PAD = 6
+    const cols = Math.min(6, cells.length)
+    const W = cols * THUMB_W + (cols - 1) * PAD
+    const H = Math.ceil(cells.length / cols) * (h + PAD) - PAD
+    const grid = Buffer.alloc(W * H * 3)
+    cells.forEach((c, i) => {
+        const [x, y] = [(i % cols) * (THUMB_W + PAD), Math.floor(i / cols) * (h + PAD)]
+        for (let r = 0; r < h; r++) c.data.copy(grid, ((y + r) * W + x) * 3, (r * c.width + c.left) * 3, (r * c.width + c.left + THUMB_W) * 3)
+    })
+    await sharp(grid, { raw: { width: W, height: H, channels: 3 } }).png({ compressionLevel: 3 }).toFile(out)
+}
+
+/** which pieces a stitch rendered, in one phrase; the others came from the cache */
+export function rendered(d: Stitched): string {
+    const made = d.pieces.filter((p) => p.made).map((p) => p.name)
+    const all = d.pieces.length
+    const sound = d.mixed ? ', the sound mixed' : ''
+    return made.length === 0 ? `every section cached${sound}` : made.length === all ? `${all} section(s) rendered${sound}` : `rendered ${made.join(', ')}, ${all - made.length} of ${all} sections cached${sound}`
+}

package/src/trailer/titles.ts

@@ -0,0 +1,274 @@
+// the trailer's drawn frames: one transparent PNG per title, cut to what it draws, and the card's ground, in the repo's
+// look (look.ts). Five styles: logo, big, caption, corner, line. Cached on what they draw, so a title edit draws one PNG
+import { createCanvas, GlobalFonts, loadImage, type Image, type SKRSContext2D } from '@napi-rs/canvas'
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import sharp from 'sharp'
+import type { Title, TitleStyle } from './grammar.ts'
+import { alpha, darker, type TrailerLook } from './look.ts'
+
+/** bump when a style's drawing changes: every cached title draws again */
+const DRAWING = 1
+
+export type TitlePlace = 'top' | 'bottom'
+export const placeOf = (ti: Title): TitlePlace => ti.place ?? 'bottom'
+
+/** a title's PNG cut to what it draws, and where it sits on the frame: the stitch blends that box, never the whole frame */
+export interface TitleImage {
+    file: string
+    x: number
+    y: number
+    w: number
+    h: number
+}
+
+const registered = new Set<string>()
+/** the look's font file registered once under its family */
+export function registerFace(look: TrailerLook, root: string): void {
+    if (!look.font.file || registered.has(look.font.file)) return
+    const abs = join(root, look.font.file)
+    if (!existsSync(abs)) throw new Error(`the brand's trailer font ${look.font.file} is not in the repo`)
+    GlobalFonts.registerFromPath(abs, look.font.family)
+    registered.add(look.font.file)
+}
+
+export const face = (g: SKRSContext2D, look: TrailerLook, px: number, weight = look.font.weight): void => {
+    const fam = look.font.family.includes(',') ? look.font.family : `"${look.font.family}"`
+    g.font = `${weight} ${Math.round(px)}px ${fam}`
+}
+
+/** the text cut into lines no wider than `max`; `\n` breaks a line */
+function wrap(g: SKRSContext2D, text: string, max: number): string[] {
+    const out: string[] = []
+    for (const para of text.split('\\n')) {
+        let line = ''
+        for (const w of para.split(/\s+/).filter(Boolean)) {
+            const next = line ? `${line} ${w}` : w
+            if (line && g.measureText(next).width > max) {
+                out.push(line)
+                line = w
+            } else line = next
+        }
+        out.push(line)
+    }
+    return out
+}
+
+/** 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 {
+    g.save()
+    g.shadowColor = alpha(edge, 0.4)
+    g.shadowBlur = 18 * k
+    g.shadowOffsetY = 6 * k
+    g.fillStyle = fill
+    g.beginPath()
+    g.roundRect(x, y, w, h, r)
+    g.fill()
+    g.restore()
+    g.lineWidth = 3 * k
+    g.strokeStyle = line
+    g.beginPath()
+    g.roundRect(x, y, w, h, r)
+    g.stroke()
+}
+
+/** one title over a transparent frame. A title's `\n` breaks its line; a logo's second line is its subtitle */
+export function drawTitle(text: string, style: TitleStyle, [W, H]: readonly [number, number], place: TitlePlace, look: TrailerLook, logo: Image | null): Buffer {
+    const top = place === 'top'
+    const c = createCanvas(W, H)
+    const g = c.getContext('2d')
+    const k = Math.min(H, W) / 1080
+    g.textAlign = 'center'
+    g.textBaseline = 'middle'
+    const [first = '', ...more] = text.split('\\n')
+    if (style === 'logo') {
+        // the logo image over the word, the word in the accent over the edge and its soft drop, the subtitle spaced under it
+        const glow = g.createRadialGradient(W / 2, H * 0.48, 0, W / 2, H * 0.48, Math.max(W, H) * 0.45)
+        glow.addColorStop(0, alpha(look.edge, 0.45))
+        glow.addColorStop(1, alpha(look.edge, 0))
+        g.fillStyle = glow
+        g.fillRect(0, 0, W, H)
+        const markH = logo ? Math.min(H * 0.3, W * 0.3) : 0
+        face(g, look, 170 * k, 900)
+        const kl = Math.min(1, (W * 0.78) / (g.measureText(first).width + 16 * k))
+        const px = 170 * k * kl
+        const subPx = 34 * 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
+        if (logo) {
+            const w = (logo.width / logo.height) * markH
+            g.save()
+            g.shadowColor = alpha(look.edge, 0.6)
+            g.shadowBlur = 30 * k
+            g.drawImage(logo, W / 2 - w / 2, y, w, markH)
+            g.restore()
+            y += markH + px * 0.25
+        }
+        if (first) {
+            const cy = y + px / 2
+            face(g, look, px, 900)
+            g.save()
+            g.shadowColor = alpha(look.edge, 0.6)
+            g.shadowBlur = 30 * k
+            g.shadowOffsetY = 12 * k
+            g.lineJoin = 'round'
+            g.lineWidth = 16 * k * kl
+            g.strokeStyle = look.edge
+            g.strokeText(first, W / 2, cy + 3 * k)
+            g.restore()
+            const grad = g.createLinearGradient(0, cy - px / 2, 0, cy + px / 2)
+            grad.addColorStop(0.1, look.light)
+            grad.addColorStop(0.55, look.accent)
+            grad.addColorStop(1, darker(look.accent, 0.2))
+            g.fillStyle = grad
+            g.fillText(first, W / 2, cy)
+            y += px
+        }
+        if (more.length) {
+            face(g, look, subPx, 800)
+            ;(g as unknown as { letterSpacing: string }).letterSpacing = `${Math.round(subPx * 0.42)}px`
+            g.shadowColor = alpha(look.edge, 0.9)
+            g.shadowBlur = subPx * 0.42
+            g.fillStyle = look.light
+            g.fillText(more.join(' ').toUpperCase(), W / 2, y + subPx)
+        }
+    } else if (style === 'big') {
+        // a strong display line in the upper third: light words in a thick edge outline, an accent under-glow
+        const px = 112 * k
+        face(g, look, px, 900)
+        const lines = wrap(g, [first, ...more].join(' '), W * 0.82)
+        lines.forEach((l, i) => {
+            const y = H * 0.26 + (i - (lines.length - 1) / 2) * px * 1.12
+            g.save()
+            g.shadowColor = alpha(look.edge, 0.55)
+            g.shadowBlur = 26 * k
+            g.shadowOffsetY = 10 * k
+            g.lineJoin = 'round'
+            g.lineWidth = 22 * k
+            g.strokeStyle = look.edge
+            g.strokeText(l, W / 2, y)
+            g.restore()
+            g.lineWidth = 8 * k
+            g.strokeStyle = look.accent
+            g.strokeText(l, W / 2, y)
+            g.fillStyle = look.light
+            g.fillText(l, W / 2, y)
+        })
+    } else if (style === 'line') {
+        // a tagline: light words centred low on a soft dark band, no plate, the frame stays the picture
+        const px = 64 * k
+        face(g, look, px)
+        const lines = more.length > 0 ? [first, ...more] : wrap(g, first, W * 0.7)
+        const lh = px * 1.3
+        const cy = top ? H * 0.2 : H * 0.8
+        const span = lh * lines.length + 80 * k
+        const band = g.createLinearGradient(0, cy - span, 0, cy + span)
+        band.addColorStop(0, alpha(look.edge, 0))
+        band.addColorStop(0.5, alpha(look.edge, 0.42))
+        band.addColorStop(1, alpha(look.edge, 0))
+        g.fillStyle = band
+        g.fillRect(0, cy - span, W, 2 * span)
+        lines.forEach((l, i) => {
+            const y = cy + (i - (lines.length - 1) / 2) * lh
+            // `*word*` is a key word in the accent, the rest light
+            const parts = l.split('*').map((t, n) => ({ text: t, key: n % 2 === 1 }))
+            const plain = parts.map((p) => p.text).join('')
+            let x = W / 2 - g.measureText(plain).width / 2
+            g.textAlign = 'left'
+            g.save()
+            g.shadowColor = alpha(look.edge, 0.85)
+            g.shadowBlur = 18 * k
+            g.shadowOffsetY = 4 * k
+            g.lineJoin = 'round'
+            g.lineWidth = 9 * k
+            g.strokeStyle = alpha(look.edge, 0.82)
+            g.strokeText(plain, x, y)
+            g.restore()
+            for (const p of parts) {
+                g.fillStyle = p.key ? look.accent : look.light
+                g.fillText(p.text, x, y)
+                x += g.measureText(p.text).width
+            }
+            g.textAlign = 'center'
+        })
+    } else if (style === 'caption') {
+        // the plate: its fill, its outline, its ink, an accent dot leading it
+        const px = 46 * k
+        face(g, look, px, 900)
+        const lines = wrap(g, [first, ...more].join(' '), W * 0.66)
+        const lh = px * 1.28
+        const dot = 14 * k
+        const bw = Math.max(...lines.map((l) => g.measureText(l).width)) + 96 * k + dot * 2
+        const bh = lines.length * lh + 34 * k
+        const cy = top ? H * 0.12 : H * 0.83
+        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)
+        g.fillStyle = look.accent
+        g.beginPath()
+        g.arc(W / 2 - bw / 2 + 34 * k, cy, dot / 2 + 2 * k, 0, Math.PI * 2)
+        g.fill()
+        g.fillStyle = look.plate.ink
+        lines.forEach((l, i) => g.fillText(l, W / 2 + dot, cy + (i - (lines.length - 1) / 2) * lh + 2 * k))
+    } else {
+        // corner: a word chip, bottom left (top left when placed at the top)
+        const px = 54 * k
+        face(g, look, px, 900)
+        const t = [first, ...more].join(' ')
+        const w = g.measureText(t).width + 72 * k
+        const h = px * 1.5
+        const x = 72 * k
+        const y = top ? 80 * k : H - 80 * k - h
+        plate(g, x, y, w, h, h / 2, k, look.chip.fill, darker(look.chip.fill, 0.15), look.edge)
+        g.fillStyle = look.chip.ink
+        g.textAlign = 'left'
+        g.fillText(t, x + 36 * k, y + h / 2 + 2 * k)
+    }
+    return Buffer.from(c.toBuffer('image/png'))
+}
+
+/** the card's ground: the look's ground, darker at the edges */
+export function drawCard([W, H]: readonly [number, number], look: TrailerLook): Buffer {
+    const c = createCanvas(W, H)
+    const g = c.getContext('2d')
+    const grad = g.createRadialGradient(W / 2, H * 0.45, 0, W / 2, H * 0.45, Math.hypot(W, H) * 0.6)
+    grad.addColorStop(0, look.ground[0])
+    grad.addColorStop(1, look.ground[1])
+    g.fillStyle = grad
+    g.fillRect(0, 0, W, H)
+    return Buffer.from(c.toBuffer('image/png'))
+}
+
+const key = (parts: unknown): string => new Bun.CryptoHasher('sha1').update(JSON.stringify([DRAWING, parts])).digest('hex').slice(0, 16)
+
+/** what the look reads from disk, as it stands: a new font or logo file draws every title again */
+export const lookFiles = (look: TrailerLook, root: string): unknown[] =>
+    [look.font.file, look.logo].map((f) => {
+        if (!f) return null
+        const abs = join(root, f)
+        return existsSync(abs) ? [f, statSync(abs).size, statSync(abs).mtimeMs] : [f, 'missing']
+    })
+
+/** the PNG of a title, drawn once per text, style, frame, place and look; its box on the frame in `<file>.json` beside it */
+export async function titlePng(dir: string, root: string, text: string, style: TitleStyle, size: readonly [number, number], place: TitlePlace, look: TrailerLook): Promise<TitleImage> {
+    const file = join(dir, `title-${key([text, style, size, place, look, lookFiles(look, root)])}.png`)
+    const where = `${file}.json`
+    if (!existsSync(file) || !existsSync(where)) {
+        mkdirSync(dir, { recursive: true })
+        registerFace(look, root)
+        const logo = style === 'logo' && look.logo && existsSync(join(root, look.logo)) ? await loadImage(join(root, look.logo)) : null
+        const { data, info } = await sharp(drawTitle(text, style, size, place, look, logo)).trim({ threshold: 0 }).png().toBuffer({ resolveWithObject: true })
+        writeFileSync(file, data)
+        writeFileSync(where, JSON.stringify({ x: -(info.trimOffsetLeft ?? 0), y: -(info.trimOffsetTop ?? 0), w: info.width, h: info.height }))
+    }
+    const { x, y, w, h } = JSON.parse(readFileSync(where, 'utf8')) as TitleImage
+    return { file, x, y, w, h }
+}
+
+/** the PNG of the card's ground for a frame and a look */
+export function cardPng(dir: string, size: readonly [number, number], look: TrailerLook): string {
+    const file = join(dir, `card-${key(['card', size, look.ground])}.png`)
+    if (!existsSync(file)) {
+        mkdirSync(dir, { recursive: true })
+        writeFileSync(file, drawCard(size, look))
+    }
+    return file
+}

package/src/trailer/url.ts

@@ -0,0 +1,108 @@
+// a `film url` take: a route resolved against the repo's dev url (the url of its one global process, or of the one
+// `base <id>` names), the page filmed by the house shot service (shot/client.ts), its process started through pm when
+// it does not answer. Pure first, the io after
+import type { Film } from './grammar.ts'
+
+export type UrlFilm = Extract<Film, { kind: 'url' }>
+
+/** a global process of the repo that serves a url */
+export interface DevProcess {
+    id: string
+    url: string
+}
+
+/** the page a route films: an http url as written, else the route under the base's own path */
+export function urlOf(route: string, base: string): string {
+    return /^https?:\/\//.test(route) ? route : `${base.replace(/\/+$/, '')}${route}`
+}
+
+/** the process a cut's routes resolve against: the one `base <id>` names, else the repo's only one; or why none */
+export function pickBase(ps: readonly DevProcess[], base: string | null): DevProcess | { error: string } {
+    const listed = ps.map((p) => `${p.id} (${p.url})`).join(', ')
+    if (base !== null) return ps.find((p) => p.id === base) ?? { error: `base ${base}: no global process of this repo has that id and a url${ps.length ? `; it has ${listed}` : ''}` }
+    if (ps.length === 1) return ps[0]!
+    if (ps.length === 0) return { error: 'film url: no global process of this repo declares a url (a <name>.shipkit.ts with globalProcess({ id, cmd, url })); or film a full http url' }
+    return { error: `film url: this repo serves several urls, name the one its routes start from with a header line base <id>: ${listed}` }
+}
+
+/** a portrait cut films its page at a phone's css width */
+const PHONE_CSS_W = 430
+/** a landscape cut films its page no wider than this, in css pixels */
+const DESKTOP_CSS_W = 1920
+
+/** the css viewport and the pixel ratio that fill the cut's frame: a viewport given keeps its css size, the ratio
+ *  making up the frame's width (1 to 4); none: the frame itself, a portrait frame at a phone's width */
+export function viewportOf(size: readonly [number, number], viewport?: readonly [number, number]): { viewport: { width: number; height: number }; dpr: number } {
+    const [W, H] = size
+    if (viewport) return { viewport: { width: viewport[0], height: viewport[1] }, dpr: +Math.min(4, Math.max(1, W / viewport[0])).toFixed(4) }
+    const dpr = +Math.min(4, Math.max(1, W / (H > W ? PHONE_CSS_W : DESKTOP_CSS_W))).toFixed(4)
+    return { viewport: { width: Math.round(W / dpr), height: Math.round(H / dpr) }, dpr }
+}
+
+/** every global process of the repo that declares a url, by the walk every unit file takes */
+export async function devProcesses(root: string): Promise<DevProcess[]> {
+    const { importFresh, repoUnitFiles } = await import('../core/discover-checks.ts')
+    const out: DevProcess[] = []
+    for (const f of repoUnitFiles(root)) {
+        const d = (await importFresh(f)) as { kind?: unknown; id?: unknown; url?: unknown } | undefined
+        if (d?.kind === 'globalProcess' && typeof d.id === 'string' && typeof d.url === 'string') out.push({ id: d.id, url: d.url })
+    }
+    return out
+}
+
+/** any http answer, a 404 included, means the server is up */
+const answers = (url: string): Promise<boolean> =>
+    fetch(url, { signal: AbortSignal.timeout(2_000) }).then(
+        () => true,
+        () => false,
+    )
+
+async function resolveBase(root: string, base: string | null, say: (l: string) => void): Promise<string> {
+    const pick = pickBase(await devProcesses(root), base)
+    if ('error' in pick) throw new Error(pick.error)
+    if (await answers(pick.url)) return pick.url
+    const { pmUp, pmUrl } = await import('../home/home-paths.ts')
+    if (process.env['CI'] == null && process.env['SHIPKIT_NO_HOME'] == null && (await pmUp())) {
+        say(`  starting ${pick.id}: ${pick.url} does not answer (sk gp start ${pick.id})`)
+        const { pmSwitchDeps, switchProcess } = await import('../cli/cmd_GlobalProcesses.ts')
+        if ((await switchProcess(pick.id, 'start', pmSwitchDeps(say, pmUrl()), 120_000)) !== 0) throw new Error(`${pick.id} did not start through pm: sk gp shows where it stands`)
+        return pick.url
+    }
+    throw new Error(`${pick.url} does not answer and no pm runs here to start it: sk gp start ${pick.id}`)
+}
+
+/** the base of each repo's routes, resolved once per process: two takes filming at once start the process once */
+const bases = new Map<string, Promise<string>>()
+export function baseUrl(root: string, base: string | null, say: (l: string) => void): Promise<string> {
+    const k = `${root}\0${base ?? ''}`
+    let p = bases.get(k)
+    if (!p) {
+        p = resolveBase(root, base, say)
+        p.catch(() => bases.delete(k))
+        bases.set(k, p)
+    }
+    return p
+}
+
+export interface UrlTake {
+    root: string
+    base: string | null
+    size: readonly [number, number]
+    fps: number
+    /** null: a still */
+    seconds: number | null
+    /** absolute: a .png for a still, a .mp4 for a clip */
+    out: string
+    say: (l: string) => void
+}
+
+/** film the page of a `film url` line at `out`; the note says what was filmed and how */
+export async function filmUrl(f: UrlFilm, o: UrlTake): Promise<string> {
+    const url = /^https?:\/\//.test(f.route) ? f.route : urlOf(f.route, await baseUrl(o.root, o.base, o.say))
+    const { clipUrl, shotUrl } = await import('../shot/client.ts')
+    const { viewport, dpr } = viewportOf(o.size, f.viewport)
+    const wait = f.wait === undefined ? {} : { waitMs: Math.round(f.wait * 1000) }
+    const log = (l: string): void => o.say(`  ${l}`)
+    const r = o.seconds === null ? await shotUrl({ url, out: o.out, viewport, dpr, ...wait }, log) : await clipUrl({ url, out: o.out, viewport, dpr, seconds: o.seconds, fps: o.fps, ...wait }, log)
+    return `${url} at ${viewport.width}x${viewport.height}@${dpr}, ${r.via}, ${r.ms} ms${r.note ? `: ${r.note}` : ''}`
+}