rvlib-shipkit 2.1.1 → 2.3.0

package/src/review/threads.ts

@@ -0,0 +1,237 @@
+// the threads of the store (wiki build/shipkit/review.md): a card's versions, each superseding the last, and the raised
+// items (a report, his note) the card answers, read as one thread per bug; their status, conversation and order, and
+// the active thread a new card already covers. Pure, over the items of review/model.ts
+import {
+    isReply,
+    partyOf,
+    reworkOf,
+    stateOf,
+    subjectKey,
+    unreadBy,
+    verdictOf,
+    withdrawnOf,
+    wordsOf,
+    type Message,
+    type ReviewItem,
+    type ShownStatus,
+    type Spec,
+    type Subject,
+    NO_SPEC,
+} from './model.ts'
+
+/** one thread of versions: a head no later card supersedes, then the chain it supersedes back to the first, and the
+ *  raised items any of them answers */
+export interface Thread {
+    head: ReviewItem
+    /** the head first, then each older version; v1 is the last */
+    versions: ReviewItem[]
+    /** the reports and notes the versions answer, oldest first */
+    answers: ReviewItem[]
+}
+
+/** every item of a thread: its versions, then the raised items they answer */
+export const membersOf = (t: Thread): ReviewItem[] => [...t.versions, ...t.answers]
+
+const answersOf = (x: ReviewItem): readonly string[] => (x.item.origin.by === 'agent' ? (x.item.answers ?? []) : [])
+
+const newest = (a: ReviewItem, b: ReviewItem): number => b.item.created.localeCompare(a.item.created) || b.item.id.localeCompare(a.item.id)
+const oldest = (a: ReviewItem, b: ReviewItem): number => a.item.created.localeCompare(b.item.created) || a.item.id.localeCompare(b.item.id)
+
+function answeredBy(versions: readonly ReviewItem[], byId: ReadonlyMap<string, ReviewItem>): ReviewItem[] {
+    return [...new Set(versions.flatMap(answersOf))]
+        .flatMap((id) => {
+            const y = byId.get(id)
+            return y && y.item.origin.by !== 'agent' ? [y] : []
+        })
+        .sort(oldest)
+}
+
+/** the raised item's opening: his or the player's words and rectangles that raised it, none on an agent card */
+export const openingOf = (x: ReviewItem): Message | undefined =>
+    x.item.origin.by === 'agent' ? undefined : x.thread.find((m) => m.op === undefined && partyOf(m.who) === 'owner' && (m.text !== undefined || m.rects !== undefined))
+
+/** the links of one list of items, built once per list: every reader of a 3000 item store walks them per item */
+interface Links {
+    byId: Map<string, ReviewItem>
+    /** by id, the cards superseding it, newest first */
+    superseders: Map<string, ReviewItem[]>
+    /** by id, the cards answering it, newest first */
+    answerers: Map<string, ReviewItem[]>
+}
+const links = new WeakMap<readonly ReviewItem[], Links>()
+
+function linksOf(items: readonly ReviewItem[]): Links {
+    const held = links.get(items)
+    if (held) return held
+    const l: Links = { byId: new Map(), superseders: new Map(), answerers: new Map() }
+    const push = (m: Map<string, ReviewItem[]>, id: string, x: ReviewItem): void => void (m.get(id) ?? m.set(id, []).get(id))?.push(x)
+    for (const x of items) {
+        l.byId.set(x.item.id, x)
+        if (x.item.supersedes) push(l.superseders, x.item.supersedes, x)
+        for (const a of answersOf(x)) push(l.answerers, a, x)
+    }
+    for (const m of [l.superseders, l.answerers]) for (const xs of m.values()) xs.sort(newest)
+    links.set(items, l)
+    return l
+}
+
+/** the item, the one it supersedes, that one's, back to the first; a missing link or a cycle ends the walk */
+export function chainOf(x: ReviewItem, items: readonly ReviewItem[]): ReviewItem[] {
+    const byId = linksOf(items).byId
+    const out = [x]
+    const seen = new Set([x.item.id])
+    for (let cur = x; cur.item.supersedes !== undefined; ) {
+        const next = byId.get(cur.item.supersedes)
+        if (!next || seen.has(next.item.id)) break
+        out.push(next)
+        seen.add(next.item.id)
+        cur = next
+    }
+    return out
+}
+
+/** every card superseding this one, the newest first */
+export const childrenOf = (id: string, items: readonly ReviewItem[]): ReviewItem[] => [...(linksOf(items).superseders.get(id) ?? [])]
+
+/** every item a later card follows: a version it supersedes, a raised item it answers */
+export const followedIds = (items: readonly ReviewItem[]): Set<string> => {
+    const l = linksOf(items)
+    return new Set([...l.superseders.keys(), ...l.answerers.keys()])
+}
+
+/** one thread per head: two cards superseding the same one are two threads sharing their history; a raised item a
+ *  card answers is in that card's thread, never a head */
+export function threadsOf(items: readonly ReviewItem[]): Thread[] {
+    const byId = linksOf(items).byId
+    const followed = followedIds(items)
+    return items
+        .filter((x) => !followed.has(x.item.id))
+        .map((head) => {
+            const versions = chainOf(head, items)
+            return { head, versions, answers: answeredBy(versions, byId) }
+        })
+}
+
+/** the newest card answering this raised item, null when none does */
+export const answererOf = (id: string, items: readonly ReviewItem[]): ReviewItem | null => linksOf(items).answerers.get(id)?.[0] ?? null
+
+const supersederOf = (id: string, items: readonly ReviewItem[]): ReviewItem | null => linksOf(items).superseders.get(id)?.[0] ?? null
+
+/** a later card follows the item: a new version of it, or a card answering it (stateOf's `superseded`) */
+export const isFollowed = (id: string, items: readonly ReviewItem[]): boolean => supersederOf(id, items) !== null || answererOf(id, items) !== null
+
+/** the thread an item reads in: its own, the one whose history holds it, or the card's that answers it */
+export const threadOfItem = (id: string, threads: readonly Thread[]): Thread | null =>
+    threads.find((t) => t.head.item.id === id) ?? threads.find((t) => membersOf(t).some((x) => x.item.id === id)) ?? null
+
+/** a thread still needs someone: its head pending, or answered and not yet acted on by the agent (an approval needs
+ *  nothing), or a lane reworking it; what he or a player raised, until it is closed */
+export function isActive(t: Thread, now = new Date()): boolean {
+    if (t.versions.some((x) => unreadBy(x, 'agent').some((m) => m !== openingOf(x)))) return true
+    if (t.answers.some((x) => unreadBy(x, 'agent').some((m) => m !== openingOf(x)))) return true
+    if (t.head.item.origin.by !== 'agent') return stateOf(t.head, false).state !== 'closed'
+    if (reworkOf(t.head, false, now)) return true
+    const f = verdictOf(t.head)
+    if (!f) return withdrawnOf(t.head) === undefined
+    return f.status !== 'approved' && f.status !== 'archived' && !f.seen
+}
+
+/** the thread's conversation: every version's and every answered item's replies, oldest first, each with the item it
+ *  sits on; an answered item's opening words show with the item, not here */
+export function conversationOf(t: Thread): (Message & { on: string })[] {
+    const openings = new Set(t.answers.map(openingOf))
+    return membersOf(t)
+        .flatMap((x) => x.thread.filter((m) => isReply(m) && !openings.has(m)).map((m) => ({ ...m, on: x.item.id })))
+        .sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id))
+}
+
+/** a head waits for the owner's verdict: an agent's card, none yet, not withdrawn, not a draft */
+export const waits = (x: ReviewItem): boolean => x.item.origin.by === 'agent' && !x.item.wip && verdictOf(x) === null && withdrawnOf(x) === undefined
+
+/** the active pending heads first in the order they were sent, then every other thread, newest first */
+export function orderedThreads(items: readonly ReviewItem[]): Thread[] {
+    const all = threadsOf(items)
+    const first = (x: ReviewItem): boolean => waits(x) || (x.item.wip !== undefined && verdictOf(x) === null && withdrawnOf(x) === undefined)
+    const pending = all.filter((t) => first(t.head)).sort((a, b) => oldest(a.head, b.head))
+    const rest = all.filter((t) => !first(t.head)).sort((a, b) => newest(a.head, b.head))
+    return [...pending, ...rest]
+}
+
+const STOP = new Set(['a', 'an', 'the', 'of', 'on', 'in', 'at', 'to', 'and', 'with', 'by', 'de', 'la', 'le', 'les', 'du', 'des', 'au', 'aux', 'l', 'd', 'et', 'en'])
+
+/** two titles share most of their words (Dice over the words, stop words aside): a new version sent without --supersedes */
+export function closeTitles(a: string, b: string): boolean {
+    const wa = new Set(wordsOf(a).filter((w) => !STOP.has(w)))
+    const wb = new Set(wordsOf(b).filter((w) => !STOP.has(w)))
+    if (wa.size === 0 || wb.size === 0) return false
+    const common = [...wa].filter((w) => wb.has(w)).length
+    return (2 * common) / (wa.size + wb.size) >= 0.6
+}
+
+/** the head of an active thread that already covers this subject, null when none. Subjects first: two that each name
+ *  one thing are one subject exactly when they name the same; else the same topic and a subject its kind calls near;
+ *  else a close title */
+export function coveringHead(card: { title: string; topic?: string; subject: Subject }, items: readonly ReviewItem[], spec: Spec = NO_SPEC): { head: ReviewItem; by: 'subject' | 'near' | 'title' } | null {
+    const key = subjectKey(card.subject, spec)
+    const comparable = threadsOf(items)
+        .filter((t) => isActive(t))
+        .filter((t) => {
+            const k = subjectKey(t.head.item.subject, spec)
+            return key === null || k === null || k === key
+        })
+    const same = key === null ? undefined : comparable.find((t) => subjectKey(t.head.item.subject, spec) === key)
+    if (same) return { head: same.head, by: 'subject' }
+    const near = spec.kinds[card.subject.kind]?.near
+    const close = near
+        ? comparable.find((t) => t.head.item.topic === card.topic && t.head.item.subject.kind === card.subject.kind && near(card.subject, t.head.item.subject))
+        : undefined
+    if (close) return { head: close.head, by: 'near' }
+    const title = comparable.find((t) => closeTitles(card.title, t.head.item.title))
+    return title ? { head: title.head, by: 'title' } : null
+}
+
+/** what the list says of a card: the owner's verdict, else withdrawn, a draft, replaced, or waiting for him */
+export function statusOf(x: ReviewItem, items: readonly ReviewItem[]): ShownStatus {
+    if (x.item.origin.by !== 'agent') {
+        // a report a card answers shows the bug's status: its card's, at the newest version
+        let card = answererOf(x.item.id, items)
+        const seen = new Set<string>()
+        for (let next = card; next && !seen.has(next.item.id); next = supersederOf(next.item.id, items)) {
+            seen.add(next.item.id)
+            card = next
+        }
+        if (card) return statusOf(card, items)
+        const st = stateOf(x, false)
+        if (st.state !== 'closed') return 'raised'
+        return st.why === 'wontfix' || st.why === 'dropped' ? 'wontfix' : st.why === 'rated' ? 'rated' : 'fixed'
+    }
+    const v = verdictOf(x)
+    if (v) return v.status
+    if (withdrawnOf(x) !== undefined) return 'withdrawn'
+    if (x.item.wip) return 'wip'
+    return supersederOf(x.item.id, items) ? 'superseded' : 'pending'
+}
+
+/** the latest thing on `x` the agent has not seen: its verdict or a reply of the owner */
+const lastUnseen = (x: ReviewItem, answered: boolean): string => {
+    const v = verdictOf(x)
+    const opening = answered || stateOf(x, false).state === 'closed' ? openingOf(x) : undefined
+    const replies = unreadBy(x, 'agent').filter((m) => m !== opening)
+    return [...(v && !v.seen ? [v.at] : []), ...replies.map((m) => m.at)].sort().at(-1) ?? ''
+}
+
+/** the items with a verdict or an owner reply the agent has not marked seen yet, oldest first */
+export function unseen(items: readonly ReviewItem[]): ReviewItem[] {
+    const answered = new Set(items.flatMap(answersOf))
+    return items
+        .map((x) => ({ x, at: lastUnseen(x, answered.has(x.item.id)) }))
+        .filter((u) => u.at !== '')
+        .sort((a, b) => a.at.localeCompare(b.at))
+        .map((u) => u.x)
+}
+
+/** what waits on him: the cards waiting for the owner's verdict, and what he raised that asks him a question or is blocked on him */
+export function waitingOnOwner(items: readonly ReviewItem[]): Thread[] {
+    const followed = followedIds(items)
+    return orderedThreads(items).filter((t) => waits(t.head) || (t.head.item.origin.by !== 'agent' && ['question', 'blocked'].includes(stateOf(t.head, followed.has(t.head.item.id)).state)))
+}

package/src/review/trailer-desk.ts

@@ -0,0 +1,385 @@
+// the trailer view's cuts, renders and timelines (wiki build/trailer.md, Frame notes), and the still a note on a frame
+// is raised with: the note itself is an item of the one store, its subject the frame, anchored on its shot's name, so it
+// survives a new render of the cut. A cut is a `trailer/<id>/<cut>.trailer` and its render `out/<name>.mp4` (`<name>`
+// its `trailer` line), or a render with no file beside it. The trailer core (src/trailer/) is read, never changed
+import { constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { LAYOUT } from '../core/layout.ts'
+import { parseTrailer, starts, total, type Trailer } from '../trailer/grammar.ts'
+import { THUMB_W } from '../trailer/graph.ts'
+import { probe, stillAt } from './media.ts'
+import type { FrameSubject } from './model.ts'
+import { readAllCached, storeDir } from './store.ts'
+import { CUT_RE, notesOf, shotAt, TRAILER_ID_RE, type CutInfo, type SectionSpan, type ShotSpan, type Timeline, type TrailerInfo } from './trailer-model.ts'
+
+const round = (v: number, d = 4): number => Number(v.toFixed(d))
+
+/** the cut's montage on its clock: each shot from its start to the next one's, the sections, the captions */
+export function timelineOf(t: Pick<Trailer, 'shots' | 'fps' | 'size'>): Timeline {
+    const st = starts(t)
+    const end = total(t)
+    let section: string | null = null
+    const shots: ShotSpan[] = t.shots.map((s, i) => {
+        if (s.section) section = s.section.name
+        const start = st[i] ?? 0
+        return {
+            name: s.name,
+            line: s.line,
+            start: round(start),
+            end: round(st[i + 1] ?? end),
+            length: s.length,
+            section,
+            captions: s.titles.map((ti) => ({ text: ti.text, style: ti.style, start: round(start + ti.at), end: round(start + (ti.for === null ? s.length : ti.at + ti.for)) })),
+        }
+    })
+    const sections: SectionSpan[] = []
+    for (const s of shots) {
+        if (s.section === null) continue
+        const last = sections.at(-1)
+        if (last?.name === s.section) last.end = s.end
+        else sections.push({ name: s.section, start: s.start, end: s.end })
+    }
+    return { total: round(end), fps: t.fps, size: t.size, shots, sections }
+}
+
+/** a render with no .trailer beside it: one shot spanning the whole video, so the player and the notes still work */
+const wholeTimeline = (duration: number, fps: number, size: [number, number]): Timeline => ({
+    total: round(duration),
+    fps,
+    size,
+    shots: [{ name: 'cut', line: 0, start: 0, end: round(duration), length: round(duration), section: null, captions: [] }],
+    sections: [],
+})
+
+const trailersDir = (root: string): string => join(root, 'trailer')
+
+/** a trailer folder by its name, or null when the name is not one */
+export function trailerDir(root: string, id: string): string | null {
+    if (!TRAILER_ID_RE.test(id)) return null
+    const dir = join(trailersDir(root), id)
+    return existsSync(dir) && statSync(dir).isDirectory() ? dir : null
+}
+
+/** one cut of a folder, as found on disk */
+interface CutFiles {
+    cut: string
+    /** the render's stem */
+    name: string
+    trailer: string | null
+    /** a kept version: its text in versions/, its render and strip in versions/<v>/ */
+    version?: true
+}
+
+/** the `trailer <name>` line of a file, read without a parse; its stem when it has none */
+const nameOf = (file: string, stem: string): string => /^\s*trailer\s+([a-z0-9][a-z0-9-]*)\s*(#.*)?$/m.exec(readFileSync(file, 'utf8'))?.[1] ?? stem
+
+/** the one file of a version's folder ending so, null when it has none */
+const versionFile = (dir: string, v: string, end: string): string | null => {
+    const d = join(dir, 'versions', v)
+    const f = existsSync(d) ? readdirSync(d).find((x) => x.endsWith(end) && (end !== '.mp4' || !x.endsWith('.part.mp4'))) : undefined
+    return f ? join(d, f) : null
+}
+
+/** a trailer's kept versions (wiki build/trailer.md, Versions): each `versions/<v>.trailer`, its render in its folder
+ *  when the machine still holds it */
+function versionsOf(dir: string): CutFiles[] {
+    const vd = join(dir, 'versions')
+    if (!existsSync(vd)) return []
+    return readdirSync(vd)
+        .filter((f) => f.endsWith('.trailer') && CUT_RE.test(f.slice(0, -'.trailer'.length)))
+        .map((f) => f.slice(0, -'.trailer'.length))
+        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+        .map((v) => ({ cut: v, name: v, trailer: join(vd, `${v}.trailer`), version: true as const }))
+}
+
+/** a trailer's cuts: each .trailer file, then each render no file names (a shot's preview `shot-*`, a passage `clip-*`
+ *  and a section's preview `<cut>-<section>` are never a cut), then each kept version a cut of that name does not shadow */
+export function cutsOf(dir: string): CutFiles[] {
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith('.trailer') && CUT_RE.test(f.slice(0, -'.trailer'.length)))
+        .sort()
+    const out: CutFiles[] = files.map((f) => {
+        const cut = f.slice(0, -'.trailer'.length)
+        return { cut, name: nameOf(join(dir, f), cut), trailer: join(dir, f) }
+    })
+    const named = new Set(out.map((c) => c.name))
+    const outDir = join(dir, 'out')
+    if (existsSync(outDir))
+        for (const f of readdirSync(outDir).sort()) {
+            const stem = f.slice(0, -'.mp4'.length)
+            if (!f.endsWith('.mp4') || /^(shot|clip)-/.test(f) || named.has(stem) || [...named].some((n) => stem.startsWith(`${n}-`)) || !CUT_RE.test(stem) || out.some((c) => c.cut === stem)) continue
+            out.push({ cut: stem, name: stem, trailer: null })
+        }
+    out.sort((a, b) => (a.cut === 'main' ? -1 : b.cut === 'main' ? 1 : a.cut.localeCompare(b.cut)))
+    return [...out, ...versionsOf(dir).filter((v) => !out.some((c) => c.cut === v.cut))]
+}
+
+/** every trailer folder: a folder of trailer/ that holds a cut */
+export function trailerIds(root: string): string[] {
+    const d = trailersDir(root)
+    if (!existsSync(d)) return []
+    return readdirSync(d)
+        .filter((id) => TRAILER_ID_RE.test(id) && statSync(join(d, id)).isDirectory() && cutsOf(join(d, id)).length > 0)
+        .sort()
+}
+
+export const cutOf = (dir: string, cut: string): CutFiles | null => (CUT_RE.test(cut) ? (cutsOf(dir).find((c) => c.cut === cut) ?? null) : null)
+/** a cut's render: out/<name>.mp4, or a version's own */
+export const videoOf = (dir: string, c: CutFiles): string => (c.version ? (versionFile(dir, c.cut, '.mp4') ?? join(dir, 'versions', c.cut, `${c.cut}.mp4`)) : join(dir, 'out', `${c.name}.mp4`))
+const stripOf = (dir: string, c: CutFiles): string => (c.version ? (versionFile(dir, c.cut, '.strip.png') ?? join(dir, 'versions', c.cut, `${c.cut}.strip.png`)) : join(dir, 'out', `${c.name}.strip.png`))
+export const montageOf = (dir: string, c: CutFiles): string => join(dir, 'out', `${c.name}.montage.md`)
+
+/** a cut's .trailer parsed: the film lines need the project CLI's words, which a timeline never does, so their errors
+ *  are left out */
+function parseCut(file: string): { trailer: Trailer; errors: string[] } {
+    const text = readFileSync(file, 'utf8')
+    const lines = text.split('\n')
+    const { trailer, errors } = parseTrailer(text, { verbs: null })
+    const own = errors.filter((e) => !/^\s*film\s/.test(lines[e.line - 1] ?? ''))
+    return { trailer, errors: own.map((e) => `${file.split('/').pop()}:${e.line}: ${e.message}`) }
+}
+
+/** a render younger than this may still be written: ffmpeg writes in place */
+const SETTLE_MS = 2500
+const settled = (mtime: number, now: number): boolean => now - mtime > SETTLE_MS
+
+/** where each finished render is kept as the page plays it: an APFS clone, free, untouched by the next render */
+export const viewDir = (root: string): string => join(root, LAYOUT.cache, 'trailer-view')
+/** the versions kept per cut: the one on screen may be the one before the newest */
+const VIEWS_KEPT = 3
+
+/** a finished render of a cut: its clone, its length and rate, its size, the timeline it was rendered from (null: unknown) */
+export interface View {
+    mtime: number
+    duration: number
+    fps: number
+    size: [number, number]
+    timeline: Timeline | null
+}
+
+const viewBase = (root: string, id: string, cut: string, mtime: number): string => join(viewDir(root), `${id}--${cut}--${Math.round(mtime)}`)
+export const viewVideo = (root: string, id: string, cut: string, mtime: number): string => `${viewBase(root, id, cut, mtime)}.mp4`
+export const viewStrip = (root: string, id: string, cut: string, mtime: number): string => `${viewBase(root, id, cut, mtime)}.strip.png`
+
+/** the render's contact strip kept beside it, once the build has written it (just after the mp4) */
+function keepStrip(root: string, dir: string, id: string, c: CutFiles, mtime: number): void {
+    const kept = viewStrip(root, id, c.cut, mtime)
+    const sf = stripOf(dir, c)
+    if (existsSync(kept) || !existsSync(sf) || statSync(sf).mtimeMs < mtime || !settled(statSync(sf).mtimeMs, Date.now())) return
+    copyFileSync(sf, kept, constants.COPYFILE_FICLONE)
+}
+
+/** a kept version by its mtime, null when it was pruned */
+export function readView(root: string, id: string, cut: string, mtime: number): View | null {
+    const f = `${viewBase(root, id, cut, mtime)}.json`
+    return existsSync(f) && existsSync(viewVideo(root, id, cut, mtime)) ? (JSON.parse(readFileSync(f, 'utf8')) as View) : null
+}
+
+function newestView(root: string, id: string, cut: string): View | null {
+    if (!existsSync(viewDir(root))) return null
+    const prefix = `${id}--${cut}--`
+    const ms = readdirSync(viewDir(root))
+        .filter((f) => f.startsWith(prefix) && f.endsWith('.json'))
+        .map((f) => Number(f.slice(prefix.length, -5)))
+        .filter((m) => Number.isFinite(m))
+        .sort((x, y) => y - x)
+    for (const m of ms) {
+        const v = readView(root, id, cut, m)
+        if (v) return v
+    }
+    return null
+}
+
+/** the render's length, rate and size; null while ffprobe cannot read it (a render still written) */
+function probeVideo(video: string): { duration: number; fps: number; size: [number, number] } | null {
+    try {
+        const p = probe(video)
+        return { duration: p.duration, fps: p.video?.fps || 30, size: [p.video?.width ?? 1920, p.video?.height ?? 1080] }
+    } catch {
+        return null
+    }
+}
+
+/** every repo the hub serves keeps its own: the key carries the root */
+const views = new Map<string, View>()
+
+/** the cut's render as the page plays it: the newest finished version, kept; while a new one is written, the last one */
+export function viewOf(root: string, dir: string, id: string, c: CutFiles, now = Date.now()): { view: View | null; rendering: boolean } {
+    const key = `${root}\0${id}/${c.cut}`
+    const kept = views.get(key) ?? newestView(root, id, c.cut)
+    const video = videoOf(dir, c)
+    if (!existsSync(video)) return { view: kept, rendering: false }
+    const mtime = Math.round(statSync(video).mtimeMs)
+    if (kept?.mtime === mtime) {
+        views.set(key, kept)
+        keepStrip(root, dir, id, c, mtime)
+        return { view: kept, rendering: false }
+    }
+    if (!settled(mtime, now)) return { view: kept, rendering: true }
+    const p = probeVideo(video)
+    if (!p) return { view: kept, rendering: true }
+    mkdirSync(viewDir(root), { recursive: true })
+    copyFileSync(video, viewVideo(root, id, c.cut, mtime), constants.COPYFILE_FICLONE)
+    // the .trailer saved before the render is the one it was rendered from; one saved after may differ
+    let timeline: Timeline | null = null
+    if (c.trailer === null) timeline = wholeTimeline(p.duration, p.fps, p.size)
+    else if (statSync(c.trailer).mtimeMs <= mtime)
+        try {
+            timeline = timelineOf(parseCut(c.trailer).trailer)
+        } catch {
+            timeline = null
+        }
+    const view: View = { mtime, ...p, timeline }
+    writeFileSync(`${viewBase(root, id, c.cut, mtime)}.json`, JSON.stringify(view))
+    keepStrip(root, dir, id, c, mtime)
+    views.set(key, view)
+    pruneViews(root, id, c.cut)
+    return { view, rendering: false }
+}
+
+function pruneViews(root: string, id: string, cut: string): void {
+    const prefix = `${id}--${cut}--`
+    for (const f of viewsToDrop(root)) if (f.slice(viewDir(root).length + 1).startsWith(prefix)) rmSync(f, { force: true })
+}
+
+/** the kept renders that go: every one past the newest VIEWS_KEPT of a cut, and every one of a cut its folder no longer
+ *  has (a note keeps its own still) */
+export function viewsToDrop(root: string): string[] {
+    const vd = viewDir(root)
+    if (!existsSync(vd)) return []
+    const live = new Set(trailerIds(root).flatMap((id) => cutsOf(join(trailersDir(root), id)).map((c) => `${id}--${c.cut}`)))
+    const byCut = new Map<string, Set<number>>()
+    const files = readdirSync(vd)
+    for (const f of files) {
+        const m = /^(.+)--(\d+)\./.exec(f)
+        if (!m) continue
+        const ms = byCut.get(m[1]!) ?? new Set<number>()
+        byCut.set(m[1]!, ms.add(Number(m[2])))
+    }
+    const kept = new Set(
+        [...byCut].flatMap(([cut, ms]) =>
+            live.has(cut)
+                ? [...ms]
+                      .sort((x, y) => y - x)
+                      .slice(0, VIEWS_KEPT)
+                      .map((m) => `${cut}--${m}`)
+                : [],
+        ),
+    )
+    return files.filter((f) => !kept.has(/^(.+--\d+)\./.exec(f)?.[1] ?? '')).map((f) => join(vd, f))
+}
+
+/** the contact strip's grid as src/trailer/stitch.ts lays it: rows of six tiles THUMB_W wide, 6 px apart */
+const STRIP_COLS = 6
+const STRIP_PAD = 6
+
+/** the strip's grid, when the file's size fits this timeline's shots */
+function stripInfo(file: string, tl: Timeline): CutInfo['strip'] {
+    if (!existsSync(file) || tl.shots.length === 0) return null
+    const head = readFileSync(file).subarray(0, 24)
+    const w = head.readUInt32BE(16)
+    const h = head.readUInt32BE(20)
+    const cols = Math.min(STRIP_COLS, tl.shots.length)
+    const rows = Math.ceil(tl.shots.length / cols)
+    const tileH = Math.round((THUMB_W * tl.size[1]) / tl.size[0] / 2) * 2
+    const fits = w === cols * THUMB_W + (cols - 1) * STRIP_PAD && h === rows * tileH + (rows - 1) * STRIP_PAD
+    return fits ? { cols, tileW: THUMB_W, tileH, pad: STRIP_PAD } : null
+}
+
+export function cutInfo(root: string, dir: string, id: string, c: CutFiles): CutInfo {
+    const video = videoOf(dir, c)
+    const fileMtime = c.trailer ? statSync(c.trailer).mtimeMs : existsSync(video) ? statSync(video).mtimeMs : 0
+    let parsed: Timeline | null = null
+    let errors: string[] = []
+    if (c.trailer)
+        try {
+            const p = parseCut(c.trailer)
+            parsed = timelineOf(p.trailer)
+            errors = p.errors
+        } catch (e) {
+            errors = [`${c.cut}.trailer: ${(e as Error).message}`]
+        }
+    const { view, rendering } = viewOf(root, dir, id, c)
+    const timeline = view?.timeline ?? parsed
+    const rel = (p: string): string => relative(root, p)
+    const montage = montageOf(dir, c)
+    return {
+        cut: c.cut,
+        name: c.name,
+        files: { trailer: c.trailer ? rel(c.trailer) : null, video: rel(video), strip: rel(stripOf(dir, c)), montage: existsSync(montage) ? rel(montage) : null },
+        timeline,
+        timelineFromRender: view?.timeline != null,
+        errors,
+        video: view ? { mtime: view.mtime, duration: view.duration, fps: view.fps } : null,
+        rendering: !c.version && rendering,
+        edited: !c.version && c.trailer !== null && view !== null && fileMtime > view.mtime,
+        strip: timeline && view ? stripInfo(viewStrip(root, id, c.cut, view.mtime), timeline) : null,
+        fileMtime,
+        version: c.version === true,
+    }
+}
+
+export function trailerInfo(root: string, id: string): TrailerInfo | null {
+    const dir = trailerDir(root, id)
+    if (!dir) return null
+    return { id, cuts: cutsOf(dir).map((c) => cutInfo(root, dir, id, c)), notes: notesOf(readAllCached(storeDir(root)).items, id) }
+}
+
+/** the montage page of a cut, null when its build wrote none */
+export function montagePage(root: string, id: string, cut: string): string | null {
+    const dir = trailerDir(root, id)
+    const c = dir ? cutOf(dir, cut) : null
+    if (!dir || !c) return null
+    const f = montageOf(dir, c)
+    return existsSync(f) ? readFileSync(f, 'utf8') : null
+}
+
+// ── a note's frame ──
+
+/** a note's frame on a cut: its index and the frame's middle, where the player and ffmpeg both show it */
+export function frameAt(time: number, fps: number, duration: number): { frame: number; time: number } {
+    const last = Math.max(0, Math.round(duration * fps) - 1)
+    const frame = Math.max(0, Math.min(last, Math.floor(time * fps + 1e-6)))
+    return { frame, time: (frame + 0.5) / fps }
+}
+
+export interface NewNote {
+    cut: string
+    /** the render on screen, by its mtime: the still is cut from that version, whatever came after */
+    version: number
+    time: number
+}
+
+/** the frame at `time` of the render on screen as a note's subject, and its still cut into `still`: the shot read from
+ *  that render's timeline */
+export async function frameNote(root: string, trailer: string, input: NewNote, still: string): Promise<FrameSubject> {
+    const dir = trailerDir(root, trailer)
+    const c = dir ? cutOf(dir, input.cut) : null
+    if (!dir || !c) throw new Error(`no cut ${trailer}/${input.cut}`)
+    const v = readView(root, trailer, input.cut, input.version)
+    if (!v) throw new Error(`the render of ${input.cut} on screen is gone: load the new one`)
+    const tl = v.timeline ?? (c.trailer ? timelineOf(parseCut(c.trailer).trailer) : wholeTimeline(v.duration, v.fps, v.size))
+    const f = frameAt(input.time, v.fps, v.duration)
+    const shot = shotAt(tl, f.time)
+    if (!shot) throw new Error(`${input.cut} has no shot`)
+    await stillAt(viewVideo(root, trailer, input.cut, v.mtime), (f.frame - 0.5) / v.fps, still)
+    return { kind: 'frame', trailer, cut: input.cut, version: String(v.mtime), time: round(f.time), frame: f.frame, shot: shot.name, shotTime: round(f.time - shot.start), section: shot.section }
+}
+
+/** what a live poll compares: every .trailer file and render of every trailer, by name and mtime, and whether each
+ *  render has settled */
+export function trailerStamp(root: string, now = Date.now()): string {
+    const parts: string[] = []
+    for (const id of trailerIds(root)) {
+        const dir = join(trailersDir(root), id)
+        for (const d of [dir, join(dir, 'out'), join(dir, 'versions')]) {
+            if (!existsSync(d)) continue
+            for (const f of readdirSync(d)) {
+                if (!/\.(trailer|mp4)$/.test(f) || f.startsWith('shot-')) continue
+                const m = statSync(join(d, f)).mtimeMs
+                parts.push(`${id}/${f}:${m}${f.endsWith('.mp4') && !settled(m, now) ? ':writing' : ''}`)
+            }
+        }
+    }
+    return parts.join('|')
+}