rvlib-shipkit 2.2.0 → 2.4.0

package/src/repo-config.ts

@@ -57,6 +57,9 @@ export type ServeConfig = {
          *  one failed, green when all passed. Default: the built-in md lint
          *  (orphans and dangling refs) over the repo root */
         lint?: string[]
+        /** the folder its node ids are relative to, where the wikis page reads
+         *  a page to search and preview (default: the repo root) */
+        dir?: string
     }
     /** agent/ graph entrypoint (default: index.md AND README.md) */
     agentIndex?: string

package/src/review/anim.ts

@@ -0,0 +1,228 @@
+// a card's before and after as a looping animation to send (wiki build/shipkit/review.md, Verbs on the store): the one
+// function behind the hub's « animation » and `sk review anim`. One cycle is drawn by ffmpeg's own filters (no per pixel
+// expression: a card renders in a few seconds), an mp4 then repeats it with no second encode
+import { createCanvas, GlobalFonts } from '@napi-rs/canvas'
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { ffmpeg } from '../trailer/ffmpeg.ts'
+import { sizeOf } from './media.ts'
+import { isGallery, isPair } from './model.ts'
+import { imageFile, readItem } from './store.ts'
+
+export const ANIM_MODES = ['cut', 'fade', 'wipe'] as const
+export type AnimMode = (typeof ANIM_MODES)[number]
+export const ANIM_FORMATS = ['mp4', 'gif'] as const
+export type AnimFormat = (typeof ANIM_FORMATS)[number]
+/** the corner labels' language, or none */
+export const ANIM_LABELS = ['en', 'fr', 'none'] as const
+export type AnimLabels = (typeof ANIM_LABELS)[number]
+const LABEL_WORDS: Record<Exclude<AnimLabels, 'none'>, [string, string]> = { en: ['before', 'after'], fr: ['avant', 'après'] }
+
+export interface AnimAsk {
+    /** the view's index on the card, 0 the first */
+    view: number
+    mode: AnimMode
+    format: AnimFormat
+    labels: AnimLabels
+    /** a font file the labels are drawn in; the system sans serif without one */
+    font?: string
+}
+
+export interface Anim {
+    file: string
+    /** the name it is saved under: the card's title in ascii, the view past the first, the mode */
+    name: string
+    /** 0 when the cached file served */
+    ms: number
+}
+
+/** bump when a mode's look changes: every cached animation draws again */
+const LOOK = 1
+
+/** seconds: a hold on one image, the cross fade, the wipe */
+const HOLD = 1.2
+const FADE = 0.5
+const WIPE_HOLD = 1.0
+const WIPE = 1.2
+const LOOPS = 3
+const MP4 = { fps: 30, maxW: 1920, crf: 20 }
+/** a gif stays a few MB: at most this wide, fewer frames (20 a second: a whole 5 cs each) */
+const GIF = { fps: 20, maxW: 960 }
+
+/** the cycle's length in seconds */
+const cycleOf = (mode: AnimMode): number => (mode === 'cut' ? 2 * HOLD : mode === 'fade' ? 2 * (HOLD + FADE) : 2 * (WIPE_HOLD + WIPE))
+
+export const isAnimMode = (s: unknown): s is AnimMode => ANIM_MODES.includes(s as AnimMode)
+export const isAnimFormat = (s: unknown): s is AnimFormat => ANIM_FORMATS.includes(s as AnimFormat)
+export const isAnimLabels = (s: unknown): s is AnimLabels => ANIM_LABELS.includes(s as AnimLabels)
+
+/** the title as a file name: ascii, lowercase, words joined by a hyphen */
+export const asciiName = (s: string, max = 60): string =>
+    s
+        .normalize('NFKD')
+        .replace(/[^\x20-\x7e]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, max)
+        .replace(/^-+|-+$/g, '') || 'before-after'
+
+const fonts = new Set<string>()
+/** one corner label, cream on a soft dark pill, as a png of its own size */
+function labelPng(text: string, px: number, out: string, font: string | undefined): void {
+    let face = 'sans-serif'
+    if (font) {
+        if (!fonts.has(font)) {
+            if (!existsSync(font)) throw new Error(`anim.font ${font}: no such file`)
+            GlobalFonts.registerFromPath(font, 'ReviewAnim')
+            fonts.add(font)
+        }
+        face = 'ReviewAnim'
+    }
+    const probe = createCanvas(4, 4).getContext('2d')
+    probe.font = `800 ${px}px ${face}`
+    const padX = Math.round(px * 0.7)
+    const padY = Math.round(px * 0.32)
+    const w = Math.ceil(probe.measureText(text).width) + 2 * padX
+    const h = Math.round(px * 1.25) + 2 * padY
+    const c = createCanvas(w, h)
+    const g = c.getContext('2d')
+    g.fillStyle = 'rgba(42, 27, 15, 0.62)'
+    g.beginPath()
+    g.roundRect(0, 0, w, h, h / 2)
+    g.fill()
+    g.font = `800 ${px}px ${face}`
+    g.fillStyle = '#FCEFD4'
+    g.textAlign = 'center'
+    g.textBaseline = 'middle'
+    g.fillText(text, w / 2, h / 2 + px * 0.04)
+    writeFileSync(out, c.toBuffer('image/png'))
+}
+
+/** the share of the after shown at time `t` of a wipe, as an ffmpeg expression: hold, an eased wipe, hold, back */
+function shownExpr(): string {
+    const u = `mod(t,${cycleOf('wipe')})`
+    const ease = (v: string): string => `(${v})*(${v})*(3-2*(${v}))`
+    const a = WIPE_HOLD
+    const b = a + WIPE
+    const c = b + WIPE_HOLD
+    return `if(lt(${u},${a}),0,if(lt(${u},${b}),${ease(`(${u}-${a})/${WIPE}`)},if(lt(${u},${c}),1,1-${ease(`(${u}-${c})/${WIPE}`)})))`
+}
+
+/** the filter graph of one cycle: [0] before and [1] after scaled, labelled ([2] and [3]), then the mode, out [v]; `pix`
+ *  the frames' format through the mode: the mp4's own yuv420p (half the work of rgb at 1080p), rgb for a gif's palette */
+function graph(mode: AnimMode, w: number, h: number, fps: number, labels: boolean, pix: 'yuv420p' | 'gbrp'): string {
+    const m = Math.round(w * 0.018)
+    const prep = (i: number, label: number, at: string, out: string): string =>
+        `[${i}:v]scale=${w}:${h}:flags=lanczos,setsar=1,format=rgba${labels ? `[p${i}];[p${i}][${label}:v]overlay=${at}` : ''},format=${pix}[${out}]`
+    // a wipe's after comes in from the left, so its label takes the top left and the before's the bottom right
+    const [early, late] = [`${m}:${m}`, `W-w-${m}:H-h-${m}`]
+    const parts = mode === 'wipe' ? [prep(0, 2, late, 'b'), prep(1, 3, early, 'a')] : [prep(0, 2, early, 'b'), prep(1, 3, late, 'a')]
+    const cut = (from: string, d: number, out: string): string => `[${from}]trim=duration=${d},setpts=PTS-STARTPTS[${out}]`
+    if (mode === 'cut') {
+        parts.push(cut('b', HOLD, 'x0'), cut('a', HOLD, 'x1'), '[x0][x1]concat=n=2:v=1:a=0[v]')
+    } else if (mode === 'fade') {
+        parts.push(
+            '[b]split[b1][b2]',
+            cut('b1', HOLD + FADE, 'x0'),
+            cut('a', 2 * FADE + HOLD, 'x1'),
+            cut('b2', FADE, 'x2'),
+            `[x0][x1]xfade=transition=fade:duration=${FADE}:offset=${HOLD}[y]`,
+            `[y][x2]xfade=transition=fade:duration=${FADE}:offset=${2 * HOLD + FADE}[v]`,
+        )
+    } else {
+        // the before keeps the right of the seam: a mask black then white, twice as wide, slid by a crop
+        const d = cycleOf('wipe')
+        const shown = shownExpr()
+        const seam = `${w}*${shown}`
+        const line = Math.max(2, Math.round(w / 640))
+        const glow = line + 4
+        // the line only while the seam moves: off screen on a hold
+        const at = (lw: number): string => `if(gt(${shown},0)*lt(${shown},1),${seam}-${lw / 2},-100)`
+        parts.push(
+            `color=c=white:s=${w}x${h}:r=${fps}:d=${d}[mw]`,
+            `color=c=black:s=${w}x${h}:r=${fps}:d=${d}[mb]`,
+            `[mb][mw]hstack,format=gray,crop=w=${w}:h=${h}:x='${w}-(${seam})':y=0[mask]`,
+            '[b][mask]alphamerge[ba]',
+            `[a][ba]overlay=0:0:shortest=1[c0]`,
+            `color=c=black@0.28:s=${glow}x${h}:r=${fps}:d=${d},format=rgba[g]`,
+            `color=c=0xFFF6DA:s=${line}x${h}:r=${fps}:d=${d},format=rgba[l]`,
+            `[c0][g]overlay=x='${at(glow)}':y=0:shortest=1[c1]`,
+            `[c1][l]overlay=x='${at(line)}':y=0:shortest=1[v]`,
+        )
+    }
+    return parts.join(';')
+}
+
+const making = new Map<string, Promise<Anim>>()
+
+/** the animation of view `ask.view` of card `id`, made once and kept under `<dir>/.anims/` (readAll skips dot names) */
+export function pairAnimation(dir: string, id: string, ask: AnimAsk): Promise<Anim> {
+    const x = readItem(dir, id)
+    if (!x) return Promise.reject(new Error(`no card ${id}`))
+    const v = x.item.views[ask.view]
+    if (!v) return Promise.reject(new Error(`card ${id} has no view ${ask.view} (it has ${x.item.views.length})`))
+    if (isGallery(v) || !isPair(v.files)) return Promise.reject(new Error(`view ${ask.view} of ${id} is not a before and after`))
+    if (v.clip) return Promise.reject(new Error(`view ${ask.view} of ${id} is a pair of clips: no animation`))
+    if (v.audio) return Promise.reject(new Error(`view ${ask.view} of ${id} is a pair of sounds: no animation`))
+    const before = imageFile(dir, id, v.files.before)
+    const after = imageFile(dir, id, v.files.after)
+    if (!before || !after) return Promise.reject(new Error(`view ${ask.view} of ${id}: an image is missing`))
+    const viewPart = ask.view > 0 ? `-${asciiName(v.label || `view-${ask.view + 1}`, 30)}` : ''
+    const name = `${asciiName(x.item.title)}${viewPart}-${ask.mode}.${ask.format}`
+    const out = join(dir, '.anims', id, `L${LOOK}-v${ask.view}-${ask.mode}-${ask.labels}.${ask.format}`)
+    const newest = Math.max(statSync(before).mtimeMs, statSync(after).mtimeMs)
+    if (existsSync(out) && statSync(out).mtimeMs >= newest) return Promise.resolve({ file: out, name, ms: 0 })
+    const pending = making.get(out)
+    if (pending) return pending
+    const job = render(before, after, out, v.size, ask)
+        .then((ms) => ({ file: out, name, ms }))
+        .finally(() => making.delete(out))
+    making.set(out, job)
+    return job
+}
+
+/** the same animation from two images of one size, no card: drawn each time under `scratch`, named after the after */
+export async function fileAnimation(before: string, after: string, ask: AnimAsk, scratch: string): Promise<Anim> {
+    const [b, a] = await Promise.all([sizeOf(before), sizeOf(after)])
+    if (b.w !== a.w || b.h !== a.h) throw new Error(`before ${b.w}x${b.h} and after ${a.w}x${a.h} differ in size`)
+    const name = `${asciiName(basename(after).replace(/\.[a-z]+$/i, ''))}-${ask.mode}.${ask.format}`
+    mkdirSync(scratch, { recursive: true })
+    const out = join(scratch, `${process.pid}-${name}`)
+    const ms = await render(resolve(before), resolve(after), out, a, ask)
+    return { file: out, name, ms }
+}
+
+/** draws one animation into `out`; its time in ms */
+async function render(before: string, after: string, out: string, size: { w: number; h: number }, ask: AnimAsk): Promise<number> {
+    const t0 = performance.now()
+    const spec = ask.format === 'mp4' ? MP4 : GIF
+    const w = Math.min(spec.maxW, size.w) & ~1
+    const h = Math.round((size.h * w) / size.w / 2) * 2
+    const work = `${out}.${process.pid}.tmp`
+    mkdirSync(work, { recursive: true })
+    try {
+        const d = cycleOf(ask.mode)
+        const still = (f: string): string[] => ['-loop', '1', '-framerate', String(spec.fps), '-t', String(d), '-i', f]
+        const inputs = [...still(before), ...still(after)]
+        if (ask.labels !== 'none') {
+            const px = Math.max(14, Math.round(w * 0.019))
+            const [was, now] = LABEL_WORDS[ask.labels]
+            labelPng(was, px, join(work, 'before.png'), ask.font)
+            labelPng(now, px, join(work, 'after.png'), ask.font)
+            inputs.push('-i', join(work, 'before.png'), '-i', join(work, 'after.png'))
+        }
+        const g = graph(ask.mode, w, h, spec.fps, ask.labels !== 'none', ask.format === 'mp4' ? 'yuv420p' : 'gbrp')
+        const done = join(work, `out.${ask.format}`)
+        if (ask.format === 'gif') {
+            await ffmpeg([...inputs, '-filter_complex', `${g};[v]split[s0][s1];[s0]palettegen=max_colors=256:stats_mode=full[pal];[s1][pal]paletteuse=dither=bayer:bayer_scale=4[o]`, '-map', '[o]', '-t', String(d), '-r', String(spec.fps), '-loop', '0', done])
+        } else {
+            const one = join(work, 'one.mp4')
+            await ffmpeg([...inputs, '-filter_complex', `${g};[v]format=yuv420p[o]`, '-map', '[o]', '-t', String(d), '-r', String(spec.fps), '-an', '-c:v', 'libx264', '-crf', String(MP4.crf), '-preset', 'veryfast', '-pix_fmt', 'yuv420p', one])
+            await ffmpeg(['-stream_loop', String(LOOPS - 1), '-i', one, '-c', 'copy', '-movflags', '+faststart', done])
+        }
+        renameSync(done, out)
+        return Math.round(performance.now() - t0)
+    } finally {
+        rmSync(work, { recursive: true, force: true })
+    }
+}

package/src/review/auto.ts

@@ -0,0 +1,141 @@
+// auto rules (wiki build/shipkit/review.md, A project's parts): a rule of the repo's review unit answers on a clock, and
+// its answer is raised as an item to a lane, open from the start. One open item a rule and key. The hub's daemon runs
+// them (startAuto), `sk review auto` reads their logs and runs one now
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { stateOf, type ReviewItem } from './model.ts'
+import { raiseItem } from './store.ts'
+import { followedIds } from './threads.ts'
+import type { AutoRule, Raise } from './unit.ts'
+
+/** a `when` slower than this prints a loud line: it runs inside the daemon */
+export const AUTO_BUDGET_MS = 50
+
+/** what one raise came to: a new item, held by the open item of its rule and key, or a dry run's */
+export type Outcome = { raise: Raise; key: string } & ({ raised: string } | { held: string } | { dry: true })
+
+/** one rule's log, `.shipkit/review-auto/<id>.json`: its last run and answer, the last item it raised */
+export interface AutoLog {
+    at: string
+    ms: number
+    answer: string
+    error?: string
+    lastRaised?: { id: string; at: string }
+}
+
+/** the logs sit beside the store, out of its watch */
+export const autoLogDir = (dir: string): string => join(dir, '..', 'review-auto')
+
+export function readAutoLog(dir: string, id: string): AutoLog | null {
+    try {
+        return JSON.parse(readFileSync(join(autoLogDir(dir), `${id}.json`), 'utf8')) as AutoLog
+    } catch {
+        return null
+    }
+}
+
+function writeAutoLog(dir: string, id: string, log: AutoLog): void {
+    const folder = autoLogDir(dir)
+    mkdirSync(folder, { recursive: true })
+    const file = join(folder, `${id}.json`)
+    writeFileSync(`${file}.tmp`, `${JSON.stringify(log, null, 2)}\n`)
+    renameSync(`${file}.tmp`, file)
+}
+
+export function everyMs(every: string): number {
+    const m = /^(\d+(?:\.\d+)?)m$/.exec(every)
+    const n = m ? Number(m[1]) : Number.NaN
+    if (!(n > 0)) throw new Error(`every: « ${every} » is no period, give minutes like '10m'`)
+    return n * 60_000
+}
+
+/** the item of this rule and key that is not closed, the one that holds a new raise */
+function openOf(items: readonly ReviewItem[], rule: string, key: string): ReviewItem | undefined {
+    const followed = followedIds(items)
+    return items.find((x) => {
+        const o = x.item.origin
+        return o.by === 'auto' && o.rule === rule && o.key === key && stateOf(x, followed.has(x.item.id)).state !== 'closed'
+    })
+}
+
+const answerText = (outcomes: readonly Outcome[]): string =>
+    outcomes.length === 0 ? 'nothing' : outcomes.map((o) => ('raised' in o ? `raised ${o.raised}` : 'held' in o ? `held by ${o.held}` : `would raise « ${o.raise.title} »`)).join('; ')
+
+/** one rule evaluated now: its raises written as items, unless an open one holds the key; `dry` writes nothing, the log
+ *  included. A rule that throws is logged and rethrown */
+export async function runRule(dir: string, rule: AutoRule, o: { items: readonly ReviewItem[]; now?: Date; dry?: boolean }): Promise<Outcome[]> {
+    const now = o.now ?? new Date()
+    const before = readAutoLog(dir, rule.id)
+    const t0 = performance.now()
+    let answer: Raise | readonly Raise[] | null
+    try {
+        answer = rule.when({ items: o.items, now })
+    } catch (e) {
+        if (!o.dry) writeAutoLog(dir, rule.id, { ...before, at: now.toISOString(), ms: performance.now() - t0, answer: 'threw', error: String(e) })
+        throw e
+    }
+    const ms = performance.now() - t0
+    if (ms > AUTO_BUDGET_MS) console.error(`FAIL: review auto: rule ${rule.id} took ${ms.toFixed(0)} ms, past ${AUTO_BUDGET_MS} ms: it runs inside the daemon`)
+    const raises: readonly Raise[] = answer === null ? [] : Array.isArray(answer) ? answer : [answer as Raise]
+    const outcomes: Outcome[] = []
+    const taken = new Map<string, string>()
+    for (const raise of raises) {
+        const key = raise.key ?? rule.id
+        const held = taken.get(key) ?? openOf(o.items, rule.id, key)?.item.id
+        if (held !== undefined) outcomes.push({ raise, key, held })
+        else if (o.dry) {
+            outcomes.push({ raise, key, dry: true })
+            taken.set(key, 'this run')
+        } else {
+            const x = await raiseItem(dir, { subject: raise.subject, origin: { by: 'auto', rule: rule.id, key, lane: raise.lane }, title: raise.title, what: raise.what, now })
+            taken.set(key, x.item.id)
+            outcomes.push({ raise, key, raised: x.item.id })
+        }
+    }
+    if (!o.dry) {
+        const raised = outcomes.flatMap((x) => ('raised' in x ? [x.raised] : []))
+        const last = raised.at(-1)
+        const lastRaised = last !== undefined ? { id: last, at: now.toISOString() } : before?.lastRaised
+        writeAutoLog(dir, rule.id, { at: now.toISOString(), ms, answer: answerText(outcomes), ...(lastRaised ? { lastRaised } : {}) })
+    }
+    return outcomes
+}
+
+/** when a rule runs next: once its last run is `every` old, never before `from` */
+export const nextRun = (rule: AutoRule, log: AutoLog | null, from: number): number => Math.max(from, log ? Date.parse(log.at) + everyMs(rule.every) : from)
+
+/** one scheduled run: what it raised printed, a rule that throws printed loud and skipped, never thrown on */
+export async function autoTick(dir: string, rule: AutoRule, items: () => readonly ReviewItem[], say: (l: string) => void = console.log): Promise<void> {
+    try {
+        for (const o of await runRule(dir, rule, { items: items() })) if ('raised' in o) say(`review auto: ${rule.id} raised ${o.raised} to ${o.raise.lane}: ${o.raise.title}`)
+    } catch (e) {
+        console.error(`FAIL: review auto: rule ${rule.id} threw, skipped until its next run: ${String(e)}`)
+    }
+}
+
+/** a schedule of a store's rules: each on its own timer, never holding the process open, the first run once its last is
+ *  `every` old. `stop` clears every timer (the unit changed, the hub closed) */
+export function startAuto(dir: string, rules: readonly AutoRule[], items: () => readonly ReviewItem[]): { stop(): void } {
+    const timers = new Set<ReturnType<typeof setTimeout>>()
+    let stopped = false
+    // a start pays its boot first: no rule runs in its first seconds
+    const from = Date.now() + 5_000
+    for (const rule of rules) {
+        const tick = (): void =>
+            void autoTick(dir, rule, items).then(() => {
+                if (stopped) return
+                const t = setTimeout(tick, everyMs(rule.every))
+                t.unref()
+                timers.add(t)
+            })
+        const t = setTimeout(tick, nextRun(rule, readAutoLog(dir, rule.id), from) - Date.now())
+        t.unref()
+        timers.add(t)
+    }
+    return {
+        stop(): void {
+            stopped = true
+            for (const t of timers) clearTimeout(t)
+        },
+    }
+}

package/src/review/format.ts

@@ -0,0 +1,158 @@
+// what `sk review inbox`, `show`, `watch`, `next` and `board` print of an item and its answer (wiki build/shipkit/review.md):
+// one record per thread, rectangles normalized and in pixels, a frame note's cut, shot and time into it, and the lines the
+// repo's unit adds (a kind's facts, a source's), handed in as `more` so this module stays pure
+import { aboutText, isFrame, isGallery, isPair, NO_SPEC, placeText, stateOf, unreadBy, verdictOf, type Message, type Rect, type ReviewItem, type Spec, type Subject } from './model.ts'
+import { answererOf, conversationOf, openingOf, type Thread } from './threads.ts'
+
+/** the lines a repo's unit adds under an item's head, and its spec for the words */
+export interface Say {
+    spec: Spec
+    more: (x: ReviewItem) => string[]
+}
+
+const PLAIN: Say = { spec: NO_SPEC, more: () => [] }
+
+const flat = (t: string): string => t.replace(/\s+/g, ' ').trim()
+
+/** a rectangle's clip time, ` at 1.25 s`; nothing on an image */
+const atText = (t: number | undefined): string => (t === undefined ? '' : ` at ${t.toFixed(2)} s`)
+
+/** each reaction to one view or tile: its place by label, its status, its comment */
+const reactionTexts = (x: ReviewItem): string[] =>
+    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.stars ? ` ★${q.stars}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+
+/** the view he picked on a choice card, `picked [voice 1]`; null when he picked none */
+const pickText = (x: ReviewItem): string | null => {
+    const p = verdictOf(x)?.pick
+    return p === undefined ? null : `picked ${placeText({ view: p }, x.item.views)}`
+}
+
+/** one line per feedback, for a monitor: the status, the overall comment, each view's reaction, then each rectangle's comment */
+export function line(x: ReviewItem): string {
+    const f = verdictOf(x)
+    if (!f) return x.item.id
+    const views = x.item.views
+    const many = views.length > 1
+    const rects = f.rects.map((q, i) => `#${i + 1}${many ? ` ${placeText(q, views)}` : ''}${q.side ? ` ${q.side}` : ''}${atText(q.t)} ${flat(q.comment) || '(no comment)'}`)
+    const pick = pickText(x)
+    const parts = [...(pick ? [pick] : []), ...reactionTexts(x), ...rects]
+    return `${x.item.id} ${f.status} "${x.item.title}": ${flat(f.comment) || '(no overall comment)'}${parts.length ? ` | ${parts.join(' | ')}` : ''}`
+}
+
+/** a raised item as the owner names it: `live#85` for a player's report, else its id */
+export const refOf = (x: ReviewItem): string => (x.item.origin.by === 'player' ? `${x.item.origin.server}#${x.item.origin.serverId}` : x.item.id)
+
+/** one owner reply, for a monitor; on an item a card answers, it reads on the card's thread */
+export const replyLine = (x: ReviewItem, m: Message, card: ReviewItem | null = null): string =>
+    `${(card ?? x).item.id} reply "${(card ?? x).item.title}"${card ? ` (on ${refOf(x)})` : ''}: ${flat(m.text ?? '')}${m.image ? ` [image thread/${m.image}]` : ''}`
+
+/** what watch prints of an item, each with the key it prints once under: an unseen feedback (again when sent again), each unseen reply */
+export function watchLines(x: ReviewItem, items: readonly ReviewItem[] = []): { key: string; text: string }[] {
+    const out: { key: string; text: string }[] = []
+    const f = verdictOf(x)
+    if (f && !f.seen) out.push({ key: `${x.item.id}@${f.at}`, text: line(x) })
+    const card = x.item.origin.by === 'agent' ? null : answererOf(x.item.id, items)
+    // the words that raised an item the card answers are what the card answers
+    const opening = card ? openingOf(x) : undefined
+    for (const m of unreadBy(x, 'agent')) if (m !== opening) out.push({ key: `${x.item.id}#${m.id}`, text: replyLine(x, m, card) })
+    return out
+}
+
+/** an auto item waiting on a taker, for its lane's watch: it carries no message to print (what he or a player raised
+ *  prints through its words, an unread reply) */
+export function raisedLine(x: ReviewItem): { key: string; text: string } | null {
+    const o = x.item.origin
+    if (o.by !== 'auto' || stateOf(x, false).state !== 'open') return null
+    return { key: `raised ${x.item.id}`, text: `${x.item.id} raised "${x.item.title}" (auto rule ${o.rule}, key ${o.key}) to ${o.lane}: take it: sk review next --lane ${o.lane}` }
+}
+
+/** an item nobody takes, for a watch and the inbox */
+export const untakenLine = (x: ReviewItem, why: string, lane: string | null): string =>
+    `${x.item.id} untaken "${x.item.title}" (${why}): ask the other sessions (ListAgents, then SendMessage) whether one of them wants it; if none answers, claim it: sk review claim ${x.item.id} --as ${lane ?? '<your lane>'}`
+
+/** one thread as one record: each item the card answers, then the card, its older versions, and with `full` the whole conversation */
+export function threadDetail(t: Thread, dir: string, full = false, say: Say = PLAIN): string {
+    if (t.answers.length === 0 && t.versions.length === 1 && !full) return detail(t.head, dir, false, false, say)
+    const out: string[] = []
+    for (const r of t.answers) out.push(`answers ${refOf(r)}:`, detail(r, dir, false, true, say), '')
+    out.push(detail(t.head, dir, full, false, say))
+    const older = t.versions.slice(1)
+    if (older.length > 0) out.push(`  versions: ${older.map((x) => x.item.id).join(' ')}`)
+    if (full) {
+        const conv = conversationOf(t)
+        if (conv.length > 0) out.push('  thread:')
+        for (const m of conv) out.push(`    ${m.who} ${m.at}${m.on === t.head.item.id ? '' : ` [on ${m.on}]`}: ${flat(m.text ?? '')}${m.image ? ` [image ${dir}/${m.on}/thread/${m.image}]` : ''}`)
+    }
+    return out.join('\n')
+}
+
+/** `m:ss.cc` */
+const clock = (t: number): string => `${Math.floor(t / 60)}:${(t % 60).toFixed(2).padStart(5, '0')}`
+
+/** what the subject says beyond its kind: a frame's cut, shot and time into it */
+function subjectText(s: Subject): string | null {
+    if (isFrame(s)) return `  frame: ${s.trailer}/${s.cut} at ${clock(s.time)} (frame ${s.frame}), shot ${s.shot} at ${s.shotTime.toFixed(2)} s${s.section ? `, section ${s.section}` : ''}`
+    return null
+}
+
+const boxText = (b: { x0: number; y0: number; x1: number; y1: number }): string => `${b.x0},${b.y0}..${b.x1},${b.y1}`
+
+/** a rectangle's world box and the nodes under its middle, when the tool that drew it knew them */
+const rectPlace = (r: Rect): string => (r.world ? ` world ${boxText(r.world)}${r.nodes?.length ? ` nodes ${r.nodes.join(' < ')}` : ''}` : '')
+
+/** a pin or rectangle drawn with the raising words, on the item's image */
+const drawnText = (m: Message): string[] =>
+    (m.rects ?? []).map((q, i) =>
+        q.w === 0 && q.h === 0
+            ? `  pin #${i + 1} ${Math.round(q.x * 100)}%,${Math.round(q.y * 100)}%`
+            : `  #${i + 1} ${q.x.toFixed(3)},${q.y.toFixed(3)} ${q.w.toFixed(3)}x${q.h.toFixed(3)}${rectPlace(q)}: ${q.comment || '(no comment)'}`,
+    )
+
+const raisedBy = (o: ReviewItem['item']['origin']): string =>
+    o.by === 'auto' ? `auto rule ${o.rule} (key ${o.key}) to ${o.lane}` : o.by === 'player' ? `player ${o.player} (${o.server}#${o.serverId})` : o.by === 'owner' ? `owner from ${o.from}${o.lane ? ` to ${o.lane}` : ''}` : o.by
+
+/** one item: a raised one by its state and the raising words, a card by the owner's verdict; `followed`: a later card supersedes or answers it */
+export function detail(x: ReviewItem, dir: string, full = false, followed = false, say: Say = PLAIN): string {
+    const f = verdictOf(x)
+    const r = x.item
+    const head = `  "${r.title}" (${aboutText(r, say.spec)})`
+    const frame = subjectText(r.subject)
+    const sub = [...(frame ? [frame] : []), ...say.more(x)]
+    const replies = unreadBy(x, 'agent').map((m) => `  reply ${m.at}: ${m.text}${m.image ? ` [image ${dir}/${r.id}/thread/${m.image}]` : ''}`)
+    if (r.origin.by !== 'agent') {
+        const st = stateOf(x, followed)
+        const said = x.thread.filter((m) => m.who === 'owner' || m.who === 'player')
+        const words = full ? x.thread.filter((m) => (m.text !== undefined || m.op !== undefined) && m.op !== 'seen') : said.filter((m) => m.text !== undefined && m.op === undefined)
+        const pins = said.filter((m) => m.rects !== undefined).at(-1)
+        const first = r.views[0]
+        const image = first && 'files' in first ? Object.values(first.files) : []
+        return [
+            `${r.id}  ${st.state.toUpperCase()}${st.why ? ` (${st.why})` : ''}  raised by ${raisedBy(r.origin)} ${r.created}${r.commit ? ` at ${r.commit}` : ''}`,
+            head,
+            ...sub,
+            ...(r.origin.by === 'auto' && r.what ? r.what.split('\n').map((l) => `  ${l}`) : []),
+            ...(st.topic ? [`  topic ${st.topic}${st.worker ? `, claimed by ${st.worker}` : ''}${r.origin.by === 'owner' && r.origin.kind ? `, ${r.origin.kind}` : ''}`] : []),
+            ...words.map((m) => `  ${m.who} ${m.at}${m.op ? ` ${m.op}${m.topic ? ` ${m.topic}` : ''}` : ''}: ${m.text ?? m.note ?? ''}${m.fix ? ` (${m.fix.commit})` : ''}`),
+            ...(pins ? drawnText(pins) : []),
+            ...(image.length > 0 ? [`  image: ${image.map((n) => `${dir}/${r.id}/${n}`).join(' ')}`] : []),
+        ].join('\n')
+    }
+    if (!f) return [`${r.id}  NO VERDICT YET`, head, ...sub, ...replies].join('\n')
+    const pick = pickText(x)
+    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, ...(pick ? [`  ${pick}`] : []), `  comment: ${f.comment || '(none)'}`]
+    for (const t of reactionTexts(x)) out.push(`  view ${t}`)
+    const px = (v: number, of: number): number => Math.round(v * of)
+    const views = r.views
+    f.rects.forEach((q, i) => {
+        const v = views[q.view ?? 0] ?? views[0]
+        const size = v && !isGallery(v) ? v.size : { w: 0, h: 0 }
+        const on = q.view ? ` view ${q.view} "${v?.label ?? ''}"` : ''
+        const side = v && !isGallery(v) && isPair(v.files) ? ` ${q.side ?? '?'}` : ''
+        const norm = `${q.x.toFixed(3)},${q.y.toFixed(3)} ${q.w.toFixed(3)}x${q.h.toFixed(3)}`
+        const pix = `${px(q.x, size.w)},${px(q.y, size.h)} ${px(q.w, size.w)}x${px(q.h, size.h)} px`
+        out.push(`  #${i + 1}${on}${side} ${norm} (${pix})${atText(q.t)}: ${q.comment || '(no comment)'}`)
+    })
+    const files = views.flatMap((v) => (isGallery(v) ? v.gallery.map((t) => t.file) : Object.values(v.files)))
+    out.push(`  files: ${files.map((n) => `${dir}/${r.id}/${n}`).join(' ')}`, ...replies)
+    return out.join('\n')
+}

package/src/review/http.ts

@@ -0,0 +1,23 @@
+// the hub's http helpers the review and trailer routes share: an error answer, the cache headers, a file with byte ranges
+import { extname } from 'node:path'
+
+export const TYPES: Record<string, string> = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.webm': 'video/webm', '.mp4': 'video/mp4' }
+export const NO_STORE = { 'Cache-Control': 'no-store' }
+/** an item's files never change once written, nor a kept render under its version: a phone keeps what it fetched */
+export const KEEP = { 'Cache-Control': 'private, max-age=86400' }
+
+export const bad = (e: unknown, status = 400): Response => Response.json({ error: e instanceof Error ? e.message : String(e) }, { status, headers: NO_STORE })
+
+/** a file with byte ranges: a player seeks through them */
+export async function ranged(req: Request, path: string, headers: Record<string, string> = KEEP): Promise<Response> {
+    const file = Bun.file(path)
+    if (!(await file.exists())) return bad(`no ${path.split('/').pop()}`, 404)
+    const size = file.size
+    const head = { 'Content-Type': TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream', 'Accept-Ranges': 'bytes', ...headers }
+    const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.get('range') ?? '')
+    if (!range) return new Response(file, { headers: { ...head, 'Content-Length': String(size) } })
+    const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]))
+    const end = range[1] && range[2] ? Math.min(Number(range[2]), size - 1) : size - 1
+    if (start >= size || start > end) return new Response(null, { status: 416, headers: { 'Content-Range': `bytes */${size}` } })
+    return new Response(file.slice(start, end + 1), { status: 206, headers: { ...head, 'Content-Range': `bytes ${start}-${end}/${size}`, 'Content-Length': String(end - start + 1) } })
+}

package/src/review/marks.ts

@@ -0,0 +1,43 @@
+// the owner's marks kept in the store (wiki build/shipkit/review.md, Verbs on the store): a mark is a `rate` message of his
+// on a subject (stars, a mark word, a part's stars, a note); the latest is the mark, the older ones its history. Pure
+import { partyOf, subjectKey, type Message, type ReviewItem, type Spec } from './model.ts'
+
+/** one subject's mark now: its latest whole rate, each part's latest stars, the note said with it */
+export interface SubjectMark {
+    key: string
+    kind: string
+    rate: { stars?: number; mark?: string }
+    parts: Record<string, number>
+    text?: string
+    at: string
+    /** how many marks it was given, the latest included */
+    history: number
+}
+
+/** every subject's mark, the latest first; a mark cleared (no stars, no mark) leaves its subject out */
+export function marksOf(items: readonly ReviewItem[], spec: Spec): SubjectMark[] {
+    const rates: { key: string; kind: string; m: Message }[] = []
+    for (const x of items) {
+        const key = subjectKey(x.item.subject, spec)
+        if (key === null) continue
+        for (const m of x.thread) if (m.rate !== undefined && partyOf(m.who) === 'owner') rates.push({ key, kind: x.item.subject.kind, m })
+    }
+    rates.sort((a, b) => a.m.at.localeCompare(b.m.at) || a.m.id.localeCompare(b.m.id))
+    const out = new Map<string, SubjectMark>()
+    for (const { key, kind, m } of rates) {
+        const r = m.rate ?? {}
+        const e = out.get(key) ?? { key, kind, rate: {}, parts: {}, at: m.at, history: 0 }
+        e.history++
+        e.at = m.at
+        if (r.part) {
+            if (r.stars) e.parts[r.part] = r.stars
+            else delete e.parts[r.part]
+        } else {
+            e.rate = { ...(r.stars ? { stars: r.stars } : {}), ...(r.mark ? { mark: r.mark } : {}) }
+            if (m.text !== undefined) e.text = m.text
+            else delete e.text
+        }
+        out.set(key, e)
+    }
+    return [...out.values()].filter((e) => e.rate.stars !== undefined || e.rate.mark !== undefined || Object.keys(e.parts).length > 0).sort((a, b) => b.at.localeCompare(a.at))
+}

package/src/review/media.ts

@@ -0,0 +1,45 @@
+// the media facts the store and the trailer view read: a clip's length, size and rate (ffprobe), one still of a clip at
+// a time (ffmpeg, through the trailer core's one spawn), an image's size (sharp, loaded only by a writer)
+import { ffmpeg } from '../trailer/ffmpeg.ts'
+
+const FFPROBE = Bun.which('ffprobe') ?? '/opt/homebrew/bin/ffprobe'
+
+export interface Probe {
+    duration: number
+    video: { width: number; height: number; fps: number } | null
+    audio: boolean
+}
+
+/** `30000/1001` → 29.97 */
+const rate = (r: string | undefined): number => {
+    const [a = 0, b = 1] = (r ?? '').split('/').map(Number)
+    return b > 0 && a > 0 ? a / b : 0
+}
+
+/** one ffprobe of a media file; throws when ffprobe cannot read it or finds no length */
+export function probe(file: string): Probe {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-show_entries', 'stream=codec_type,width,height,r_frame_rate:format=duration', '-of', 'json', file], { stdout: 'pipe', stderr: 'pipe' })
+    if (r.exitCode !== 0) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`)
+    const j = JSON.parse(r.stdout.toString()) as { streams?: { codec_type?: string; width?: number; height?: number; r_frame_rate?: string }[]; format?: { duration?: string } }
+    const duration = Number(j.format?.duration)
+    if (!(duration > 0)) throw new Error(`ffprobe ${file}: no length`)
+    const v = j.streams?.find((s) => s.codec_type === 'video')
+    return {
+        duration,
+        video: v?.width && v.height ? { width: v.width, height: v.height, fps: rate(v.r_frame_rate) } : null,
+        audio: j.streams?.some((s) => s.codec_type === 'audio') ?? false,
+    }
+}
+
+/** the first frame at or after `seconds` of a clip, as a png */
+export async function stillAt(video: string, seconds: number, png: string): Promise<void> {
+    await ffmpeg(['-ss', Math.max(0, seconds).toFixed(5), '-i', video, '-frames:v', '1', '-update', '1', '-f', 'image2', '-c:v', 'png', png])
+}
+
+/** an image's size in pixels */
+export async function sizeOf(file: string): Promise<{ w: number; h: number }> {
+    const { default: sharp } = await import('sharp')
+    const m = await sharp(file).metadata()
+    if (!m.width || !m.height) throw new Error(`${file}: no image size`)
+    return { w: m.width, h: m.height }
+}