rvlib-shipkit 2.2.0 → 2.3.0

package/src/reflect/prompt-corpus.ts

@@ -2,13 +2,12 @@
 // Transcripts live at <configRoot>/projects/<slug>/*.jsonl where <slug> is the
 // repo's absolute path with EVERY non-alphanumeric char replaced by '-'.
 //
-// A corpus is only as good as what it excludes: the harness writes many
-// user-role entries the human never typed (tool results, command wrappers,
-// compaction summaries, subagent prompts). Every filter below exists because
-// one of them polluted a real extraction pass.
+// What counts as typed is the shared transcript reader's call (transcript.ts):
+// this module finds the files, dedupes and renders.
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { basename, join, resolve } from 'path'
+import { isTypedPrompt, readTranscriptLine } from './transcript.ts'
 
 export type PromptEntry = {
     uuid: string
@@ -56,126 +55,23 @@ export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
 /** Claude Code slugs EVERY non-alphanumeric char to '-', not just '/' */
 export const projectSlug = (repoPath: string): string => resolve(repoPath).replace(/[^a-zA-Z0-9]/g, '-')
 
-// wrappers the harness injects as user-role entries — none of them are typed
-const NOISE_PREFIXES = [
-    '<local-command-caveat>',
-    '<local-command-stdout>',
-    '<command-name>',
-    '<command-message>',
-    '<system-reminder>',
-    '<task-notification>',
-    'Caveat: The messages below',
-    '[Request interrupted',
-    'This session is being continued from a previous conversation',
-    // model output parked in the queue (or wrapped as a meta entry): a
-    // sub-agent's hand-back, and a message another Claude session sent
-    '<agent-message',
-    '<cross-session-message',
-    'Another Claude session sent a message',
-]
-
-export function isTypedPrompt(text: string): boolean {
-    const trimmed = text.trim()
-    if (trimmed === '') return false
-    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
-}
-
-type RawEntry = {
-    type?: unknown
-    entrypoint?: unknown
-    uuid?: unknown
-    timestamp?: unknown
-    sessionId?: unknown
-    isMeta?: unknown
-    isSidechain?: unknown
-    isCompactSummary?: unknown
-    /** queue-operation entries only */
-    operation?: unknown
-    content?: unknown
-    message?: { role?: unknown; content?: unknown }
-}
-
-/** the typed prompt out of one transcript line, or null when the line is not one
- * he typed. isSidechain = a subagent prompt the AGENT wrote; isMeta and
- * isCompactSummary = harness-generated. Content is a string for a plain prompt,
- * an array of blocks when the message carried pastes or attachments (the text
- * blocks in there are still his). */
-export function promptTextOf(line: string): { text: string; entry: RawEntry } | null {
-    let parsed: unknown
-    try {
-        parsed = JSON.parse(line)
-    } catch {
-        return null // truncated tail line of a live session
-    }
-    if (parsed == null || typeof parsed !== 'object') return null
-    const entry = parsed as RawEntry
-    if (entry.type !== 'user') return null
-    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
-    if (entry.entrypoint === 'sdk-cli') return null // a script drove this session, nobody typed it
-    if (entry.message?.role !== 'user') return null
-    const content = entry.message.content
-    let text: string
-    if (typeof content === 'string') text = content
-    else if (Array.isArray(content)) {
-        const parts = content
-            .filter((b): b is { type: string; text: string } => b?.type === 'text' && typeof b?.text === 'string')
-            .map((b) => b.text)
-        if (parts.length === 0) return null // pure tool_result turn
-        text = parts.join('\n')
-    } else return null
-    // the harness appends reminder blocks INSIDE real prompts — strip, keep the text
-    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
-    // a slash-command entry is a harness WRAPPER around typed text:
-    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
-    // Dropping the whole entry throws away real instructions and repro pastes.
-    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
-    if (args?.[1] != null) {
-        const body = args[1].trim()
-        if (body === '') return null // bare invocation, nothing typed
-        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
-        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
-    }
-    if (!isTypedPrompt(text)) return null
-    return { text, entry }
-}
-
-/** A prompt he typed while the agent was still working: the harness parks it as
- * `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
- * first, it may NEVER become a user message. Skipping these loses exactly the
- * mid-flight corrections and standing conventions a retrospective is for */
-export function queuedTextOf(line: string): { text: string; entry: RawEntry } | null {
-    let parsed: unknown
-    try {
-        parsed = JSON.parse(line)
-    } catch {
-        return null
-    }
-    if (parsed == null || typeof parsed !== 'object') return null
-    const entry = parsed as RawEntry
-    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
-    if (typeof entry.content !== 'string') return null
-    const text = entry.content.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
-    if (!isTypedPrompt(text)) return null
-    return { text, entry }
-}
+export { isTypedPrompt } from './transcript.ts'
 
 export function extractPrompts(jsonl: string, ctx: { sessionId: string; account: string }): PromptEntry[] {
     const out: PromptEntry[] = []
     for (const line of jsonl.split('\n')) {
         if (line.trim() === '') continue
-        const queued = queuedTextOf(line)
-        const hit = queued ?? promptTextOf(line)
-        if (hit == null) continue
-        const timestamp = typeof hit.entry.timestamp === 'string' ? hit.entry.timestamp : ''
-        const fallbackId = `${queued == null ? 'typed' : 'queue'}:${ctx.sessionId}:${timestamp}`
-        out.push({
-            uuid: typeof hit.entry.uuid === 'string' ? hit.entry.uuid : fallbackId,
-            timestamp,
-            sessionId: typeof hit.entry.sessionId === 'string' ? hit.entry.sessionId : ctx.sessionId,
-            account: ctx.account,
-            text: hit.text,
-            origin: queued == null ? 'typed' : 'queued',
-        })
+        for (const ev of readTranscriptLine(line)) {
+            if (ev.kind !== 'prompt') continue
+            out.push({
+                uuid: ev.uuid ?? `${ev.origin === 'typed' ? 'typed' : 'queue'}:${ctx.sessionId}:${ev.timestamp}`,
+                timestamp: ev.timestamp,
+                sessionId: ev.sessionId ?? ctx.sessionId,
+                account: ctx.account,
+                text: ev.text,
+                origin: ev.origin,
+            })
+        }
     }
     return out
 }

package/src/reflect/transcript.ts

@@ -0,0 +1,254 @@
+// THE transcript reader: one Claude Code jsonl line in, the events it holds out.
+// `sk reflect` keeps the prompts, `sk time` keeps everything. One parser for
+// both, so a harness shape fixed here is fixed for every reader.
+//
+// A line is one entry. An assistant entry holds ONE content block (thinking,
+// text or tool_use), the user entry after a tool_use holds its tool_result,
+// and the harness writes many user-role entries the human never typed (tool
+// results, command wrappers, compaction summaries, sub-agent hand-backs).
+// Every prompt filter below exists because one of them polluted a real pass.
+
+export type PromptOrigin = 'typed' | 'queued'
+
+/** how a call was allowed: by the human (`user`), by the auto mode
+ *  classifier (a model call before the tool runs), by a rule or a hook, by the
+ *  permission mode, or not recorded */
+export type Perm = 'user' | 'classifier' | 'rule' | 'mode' | ''
+
+export function permOf(d: { source?: unknown; reasonType?: unknown } | undefined): Perm {
+    if (d == null) return ''
+    if (typeof d.source === 'string' && d.source.startsWith('user')) return 'user'
+    if (d.reasonType === 'classifier') return 'classifier'
+    if (d.reasonType === 'mode') return 'mode'
+    return typeof d.source === 'string' ? 'rule' : ''
+}
+
+/** the harness's wrapper around a message relayed into a running agent */
+const RELAYED = /^[^\n]{1,80}? sent (?:a new |a )?message while you were working\b/
+
+/** how a tool call ended, read from its tool_result */
+export type Outcome = 'ok' | 'exit' | 'timeout' | 'blocked' | 'denied' | 'interrupted' | 'error'
+
+export type TranscriptEvent =
+    /** a prompt the human typed; `queued` = typed while the agent worked */
+    | { kind: 'prompt'; at: number; timestamp: string; uuid: string | null; sessionId: string | null; text: string; origin: PromptOrigin }
+    /** a user-role turn nobody typed that wakes the agent: a task notification,
+     *  a sub-agent hand-back, a peer message, a script-driven prompt */
+    | { kind: 'wake'; at: number }
+    /** a message relayed into the agent (the coordinator, the human, another
+     *  session "sent a message while you were working"): it can end a park of
+     *  hours after the agent handed back */
+    | { kind: 'message'; at: number }
+    | { kind: 'use'; at: number; id: string; name: string; detail: string }
+    /** `perm`: how the call was allowed; `user` = it waited for the human, so its time is his */
+    | { kind: 'result'; at: number; id: string; outcome: Outcome; code: number | null; perm: Perm }
+    /** an assistant text block: the agent talking, which can end its turn */
+    | { kind: 'reply'; at: number }
+
+// wrappers the harness injects as user-role entries: none of them are typed
+const NOISE_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+    '<system-reminder>',
+    '<task-notification>',
+    'Caveat: The messages below',
+    '[Request interrupted',
+    'This session is being continued from a previous conversation',
+    // model output parked in the queue (or wrapped as a meta entry): a
+    // sub-agent's hand-back, and a message another Claude session sent
+    '<agent-message',
+    '<cross-session-message',
+    'Another Claude session sent a message',
+]
+
+export function isTypedPrompt(text: string): boolean {
+    const trimmed = text.trim()
+    if (trimmed === '') return false
+    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
+}
+
+type Block = { type?: unknown; text?: unknown; id?: unknown; name?: unknown; input?: unknown; tool_use_id?: unknown; is_error?: unknown; content?: unknown }
+
+export type RawEntry = {
+    type?: unknown
+    entrypoint?: unknown
+    uuid?: unknown
+    timestamp?: unknown
+    sessionId?: unknown
+    isMeta?: unknown
+    isSidechain?: unknown
+    isCompactSummary?: unknown
+    /** `peer` on a sub-agent hand-back or another session's message */
+    turnOrigin?: unknown
+    /** queue-operation entries only */
+    operation?: unknown
+    content?: unknown
+    message?: { role?: unknown; content?: unknown }
+    toolUseResult?: unknown
+    /** on a tool_result entry: who allowed the call (`config`, `user_temporary`, …) */
+    permissionDecision?: { source?: unknown; reasonType?: unknown }
+}
+
+const stripReminders = (text: string): string => text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+
+/** the user text of a user entry, reminders stripped, a slash command's typed
+ *  args rescued; null when it carries no text at all (a pure tool_result turn).
+ *  Content is a string for a plain prompt, an array of blocks when the message
+ *  carried pastes or attachments (the text blocks in there are still his). */
+function userText(entry: RawEntry): string | null {
+    const content = entry.message?.content
+    let text: string
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+        const parts = (content as Block[]).filter((b) => b?.type === 'text' && typeof b?.text === 'string').map((b) => b.text as string)
+        if (parts.length === 0) return null
+        text = parts.join('\n')
+    } else return null
+    text = stripReminders(text)
+    // a slash-command entry is a harness WRAPPER around typed text:
+    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
+    // Dropping the whole entry throws away real instructions and repro pastes.
+    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
+    if (args?.[1] != null) {
+        const body = args[1].trim()
+        if (body === '') return ''
+        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
+        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
+    }
+    return text
+}
+
+/** the typed prompt out of a parsed user entry, or null when he did not type
+ *  it. isSidechain = a subagent prompt the AGENT wrote; isMeta and
+ *  isCompactSummary = harness-generated; entrypoint sdk-cli = a script drove it */
+export function typedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'user') return null
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
+    if (entry.entrypoint === 'sdk-cli') return null
+    if (entry.message?.role !== 'user') return null
+    const text = userText(entry)
+    if (text == null || !isTypedPrompt(text)) return null
+    return text
+}
+
+/** A prompt he typed while the agent was still working: the harness parks it as
+ *  `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
+ *  first, it may NEVER become a user message. Skipping these loses exactly the
+ *  mid-flight corrections and standing conventions a retrospective is for */
+export function queuedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
+    if (typeof entry.content !== 'string') return null
+    const text = stripReminders(entry.content)
+    return isTypedPrompt(text) ? text : null
+}
+
+const BASH_EXIT = /^Exit code (\d+)/
+const BLOCKED = [/^PreToolUse:/, /^Permission to use /, /^Permission for this action was denied/, /auto mode classifier/i, /hook error/i]
+
+/** how a tool call ended. The harness marks every failure `is_error`, and the
+ *  text says which kind: a non zero exit, a hook or permission block, the
+ *  human saying no, a timeout (now moved to the background), anything else */
+export function outcomeOf(r: { isError: boolean; text: string; extra: unknown }): { outcome: Outcome; code: number | null } {
+    const extra = r.extra != null && typeof r.extra === 'object' ? (r.extra as Record<string, unknown>) : {}
+    if (typeof extra.timedOutAfterMs === 'number' || /^Command timed out after/.test(r.text)) return { outcome: 'timeout', code: null }
+    if (extra.interrupted === true || r.text.startsWith('[Request interrupted')) return { outcome: 'interrupted', code: null }
+    if (!r.isError) return { outcome: 'ok', code: null }
+    const exit = BASH_EXIT.exec(r.text)
+    if (exit?.[1] != null) return { outcome: 'exit', code: Number(exit[1]) }
+    if (/^The user doesn't want to proceed/.test(r.text) || /^The user (rejected|denied)/.test(r.text)) return { outcome: 'denied', code: null }
+    if (BLOCKED.some((re) => re.test(r.text))) return { outcome: 'blocked', code: null }
+    return { outcome: 'error', code: null }
+}
+
+const DETAIL_MAX = 400
+const clip = (s: string): string => (s.length > DETAIL_MAX ? s.slice(0, DETAIL_MAX) : s)
+
+/** a long command keeps its head and its tail: what runs after a heredoc
+ *  (`cat > x.ts <<EOF … EOF` then `bun x.ts`) is at the end */
+const clipMiddle = (s: string): string => (s.length > 2 * DETAIL_MAX ? `${s.slice(0, DETAIL_MAX)}\n${s.slice(-DETAIL_MAX)}` : s)
+
+/** the one input field that says what a call did: the Bash command, the
+ *  sub-agent type and its description, the skill, the url */
+export function detailOf(name: string, input: unknown): string {
+    const i = input != null && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+    const str = (k: string): string => (typeof i[k] === 'string' ? (i[k] as string) : '')
+    if (name === 'Bash') return clipMiddle(str('command'))
+    if (name === 'Agent' || name === 'Task') return clip(`${str('subagent_type') || 'general-purpose'}: ${str('description')}`)
+    if (name === 'Skill') return clip(str('skill'))
+    if (name === 'WebFetch') return clip(str('url'))
+    if (name === 'Monitor' || name === 'TaskOutput' || name === 'TaskStop') return clip(str('description') || str('task_id'))
+    return ''
+}
+
+const resultText = (content: unknown): string => {
+    if (typeof content === 'string') return content
+    if (Array.isArray(content)) {
+        const first = (content as Block[]).find((b) => b?.type === 'text' && typeof b.text === 'string')
+        return first == null ? '' : (first.text as string)
+    }
+    return ''
+}
+
+// the entry types that carry nothing a reader wants and make most of the
+// bytes (api-request alone is about 80 percent of a long session): a line
+// that starts with one of these is skipped before JSON.parse
+const KEPT_TYPE_PREFIXES = ['{"type":"user"', '{"type":"assistant"', '{"type":"queue-operation"']
+
+/** every event one transcript line holds; [] for anything else, a truncated
+ *  tail line of a live session included */
+export function readTranscriptLine(line: string): TranscriptEvent[] {
+    if (line.startsWith('{"type":"') && !KEPT_TYPE_PREFIXES.some((p) => line.startsWith(p))) return []
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return []
+    }
+    if (parsed == null || typeof parsed !== 'object') return []
+    return eventsOf(parsed as RawEntry)
+}
+
+export function eventsOf(entry: RawEntry): TranscriptEvent[] {
+    const timestamp = typeof entry.timestamp === 'string' ? entry.timestamp : ''
+    const at = Date.parse(timestamp)
+    const uuid = typeof entry.uuid === 'string' ? entry.uuid : null
+    const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null
+    const prompt = (text: string, origin: PromptOrigin): TranscriptEvent => ({ kind: 'prompt', at, timestamp, uuid, sessionId, text, origin })
+
+    if (entry.type === 'queue-operation') {
+        const q = queuedPromptOf(entry)
+        return q == null ? [] : [prompt(q, 'queued')]
+    }
+    if (Number.isNaN(at) && entry.type !== 'user') return []
+    if (entry.type === 'assistant') {
+        const blocks = Array.isArray(entry.message?.content) ? (entry.message.content as Block[]) : []
+        const out: TranscriptEvent[] = []
+        for (const b of blocks) {
+            if (b?.type === 'tool_use' && typeof b.id === 'string' && typeof b.name === 'string') out.push({ kind: 'use', at, id: b.id, name: b.name, detail: detailOf(b.name, b.input) })
+            else if (b?.type === 'text') out.push({ kind: 'reply', at })
+        }
+        return out
+    }
+    if (entry.type !== 'user') return []
+    const out: TranscriptEvent[] = []
+    const content = entry.message?.content
+    if (Array.isArray(content)) {
+        const perm = permOf(entry.permissionDecision)
+        for (const b of content as Block[]) {
+            if (b?.type !== 'tool_result' || typeof b.tool_use_id !== 'string' || Number.isNaN(at)) continue
+            const o = outcomeOf({ isError: b.is_error === true, text: resultText(b.content), extra: entry.toolUseResult })
+            out.push({ kind: 'result', at, id: b.tool_use_id, ...o, perm })
+        }
+    }
+    const typed = typedPromptOf(entry)
+    if (typed != null) out.push(prompt(typed, 'typed'))
+    else if (out.length === 0 && !Number.isNaN(at) && entry.isMeta === true && RELAYED.test(userText(entry) ?? '')) out.push({ kind: 'message', at })
+    // a peer message (a sub-agent hand-back, another session's message) is written isMeta, yet it wakes the agent
+    else if (out.length === 0 && !Number.isNaN(at) && (entry.isMeta !== true || entry.turnOrigin === 'peer') && entry.isCompactSummary !== true) {
+        const text = userText(entry)
+        if (text != null && text !== '') out.push({ kind: 'wake', at })
+    }
+    return out
+}

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