rvlib-shipkit 2.2.0 → 2.4.0

package/src/serve/hub-app/review/review-st.ts

@@ -0,0 +1,902 @@
+// a repo's review page as state (wiki build/shipkit/review.md, The review page): the cards on disk, the open one, the
+// filters, and his draft per card (rectangles, reactions and comments not sent yet), kept in the browser until it is
+// sent. The list is read while the page shows, every 2 s, answered 304 when the store did not move
+import { makeAutoObservable, reaction, runInAction } from 'mobx'
+import {
+    asOptions,
+    isApproved,
+    isChoice,
+    isGallery,
+    isPair,
+    laneOf,
+    moveOf,
+    reworkOf,
+    STARS,
+    STATUS_LABEL,
+    stateOf,
+    unreadBy,
+    verdictOf,
+    type MediaView,
+    type Message,
+    type Move,
+    type Rect,
+    type ReviewItem,
+    type ReviewReaction,
+    type ReviewStatus,
+    type ShownStatus,
+    type Side,
+    type Spec,
+} from '../../../review/model.ts'
+import { answererOf, chainOf, childrenOf, conversationOf, followedIds, isActive, membersOf, orderedThreads, statusOf, threadOfItem, waits, type Thread } from '../../../review/threads.ts'
+import { reach } from '../reach.ts'
+import type { RepoSt } from '../repo-st.ts'
+import type { Role } from '../../../review/role.ts'
+import { ClipSt } from './clip-st.ts'
+
+interface Draft {
+    rects: Rect[]
+    comment: string
+    reactions?: ReviewReaction[]
+    /** the option he picked, on a choice card */
+    pick?: number
+}
+
+/** a live `sk review watch`: its process, the session or lane it keeps, when it started */
+export interface Watcher {
+    pid: number
+    session: string | null
+    lane: string | null
+    started: string
+}
+
+export interface Listing {
+    items: ReviewItem[]
+    broken: { id: string; error: string }[]
+}
+
+/** the zoom of a view: fit the column (and the window's height), or a share of the image's own pixels */
+export const ZOOMS = ['fit', '1', '1.5', '2'] as const
+export type Zoom = (typeof ZOOMS)[number]
+
+/** how a pair of images shows: side by side, the curtain, one over the other, the after alone */
+export type CompareMode = 'side' | 'swipe' | 'onion' | 'mod'
+export const COMPARE_MODES: readonly CompareMode[] = ['side', 'swipe', 'onion', 'mod']
+/** the side a rectangle lands on: the after alone draws on the after */
+export const drawnSide = (mode: CompareMode, drawn: Side): Side => (mode === 'mod' ? 'after' : drawn)
+
+/** below this width the page is the phone's: one column at a time, the verdicts in a bar under the thumb */
+/** a repo's review unit as the page reads it: the words of its kinds and topics, its dispatcher and who holds the role */
+export type RepoSpec = Spec & { role: Role | null; sources: string[]; auto: { id: string; every: string }[] }
+
+export const PHONE_PX = 768
+/** below this width of the review page itself (the project list and the sidebar already took theirs), `auto` stacks
+ *  the card over the answer in one column beside the list */
+export const STACK_PX = 900
+/** where the card sits against its answer: on top of it, left of it, or by the page's width */
+export const CARD_PLACES = ['top', 'left', 'auto'] as const
+export type CardPlace = (typeof CARD_PLACES)[number]
+export type PhonePane = 'list' | 'card' | 'answer'
+export type PairSide = 'before' | 'after' | 'swipe'
+
+const POLL_MS = 2000
+/** a sound's clock steps a tenth of a second */
+const SOUND_FPS = 10
+/** ← → on a sound jump this many seconds */
+const SOUND_JUMP = 2
+
+const sameSpot = (r: ReviewReaction, view: number, tile: number | undefined): boolean => r.view === view && r.tile === tile
+
+/** what a reload must not lose, under keys of this repo: a blocked storage only loses persistence */
+const store = {
+    get(k: string): string | null {
+        try {
+            return localStorage.getItem(k)
+        } catch {
+            return null
+        }
+    },
+    put(k: string, v: string | null): void {
+        try {
+            if (v === null) localStorage.removeItem(k)
+            else localStorage.setItem(k, v)
+        } catch {
+            // as above
+        }
+    },
+}
+
+const draftOf = (s: string | null): Draft | null => {
+    try {
+        const d = s === null ? null : (JSON.parse(s) as Partial<Draft>)
+        if (!d || !Array.isArray(d.rects) || typeof d.comment !== 'string') return null
+        return { rects: d.rects, comment: d.comment, ...(Array.isArray(d.reactions) ? { reactions: d.reactions } : {}), ...(typeof d.pick === 'number' ? { pick: d.pick } : {}) }
+    } catch {
+        return null
+    }
+}
+
+/** a loader for a polled list: it sends the tag of its last answer, and on « not modified » gives that answer again */
+function unchangedAware<T>(url: () => string): () => Promise<T> {
+    let last: { tag: string; value: T } | null = null
+    return async () => {
+        const res = await reach(url(), { cache: 'no-store', headers: last ? { 'If-None-Match': last.tag } : {} })
+        if (res.status === 304 && last) return last.value
+        if (!res.ok) throw new Error(`${url()}: HTTP ${res.status} ${await res.text().catch(() => '')}`.trim())
+        const value = (await res.json()) as T
+        const tag = res.headers.get('ETag')
+        last = tag ? { tag, value } : null
+        return value
+    }
+}
+
+async function postJson<T>(url: string, body: unknown): Promise<T> {
+    const res = await reach(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+    const text = await res.text()
+    if (!res.ok) {
+        let msg = text
+        try {
+            msg = (JSON.parse(text) as { error?: string }).error ?? text
+        } catch {
+            // a plain text answer says it already
+        }
+        throw new Error(msg || `HTTP ${res.status}`)
+    }
+    return JSON.parse(text) as T
+}
+
+/** the pair's compare mode, the curtain's line and the onion's opacity, shared by every pair of the page */
+export class CompareSt {
+    mode: CompareMode = 'side'
+    split = 0.5
+    opacity = 0.5
+    constructor(private readonly key: string) {
+        const m = store.get(key)
+        if (m && (COMPARE_MODES as readonly string[]).includes(m)) this.mode = m as CompareMode
+        makeAutoObservable<this, 'key'>(this, { key: false })
+    }
+    setMode(m: CompareMode): void {
+        this.mode = m
+        store.put(this.key, m)
+    }
+    setSplit(v: number): void {
+        this.split = Math.max(0, Math.min(1, v))
+    }
+    setOpacity(v: number): void {
+        this.opacity = Math.max(0, Math.min(1, v))
+    }
+}
+
+/** the phone's state: which pane shows, « circle » drawing on, the side of a pair */
+export class PhoneSt {
+    on = false
+    pane: PhonePane = 'list'
+    draw = false
+    pair: PairSide = 'after'
+    constructor() {
+        makeAutoObservable(this)
+        if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+            const mq = window.matchMedia(`(max-width: ${PHONE_PX - 1}px)`)
+            this.on = mq.matches
+            mq.addEventListener('change', (e) => runInAction(() => (this.on = e.matches)))
+        }
+    }
+    show(p: PhonePane): void {
+        this.pane = p
+    }
+    toggleDraw(): void {
+        this.draw = !this.draw
+    }
+    setPair(s: PairSide): void {
+        this.pair = s
+    }
+}
+
+const isShownStatus = (s: string): s is ShownStatus => Object.hasOwn(STATUS_LABEL, s)
+
+export class ReviewSt {
+    list: Listing | null = null
+    listError: string | null = null
+    /** the repo's review unit in words (its kinds, topics, dispatcher and its holder), read when the page starts */
+    spec: RepoSpec | null = null
+    /** the dispatcher's board in place of the cards */
+    board = false
+    watchers: Watcher[] = []
+    /** each clip view's own clock on the open card, by view index, made on first use */
+    private readonly clips = new Map<number, ClipSt>()
+    private clipsCard = ''
+    selectedId: string | null = null
+    query = ''
+    subject: string | null = null
+    whose: Move | null = null
+    status: ShownStatus | null = null
+    drafts: Record<string, Draft> = {}
+    /** the rectangle of the open card picked on the image, its index */
+    rect: number | null = null
+    /** the subject rings over the image (M) */
+    marksOn = true
+    /** the open card's active view, its index: the one last drawn on or picked, whose clip the keys drive */
+    view = 0
+    zoom: Zoom = 'fit'
+    viewZoom: Record<number, Zoom> = {}
+    /** the gallery tile shown large across the column, `<view>/<tile>` */
+    bigTile: string | null = null
+    /** a card of options shown full, every view stacked, by id: his switch, this visit */
+    full: Record<string, boolean> = {}
+    /** the option rows unfolded to their full view, by view index */
+    openRows: Record<number, boolean> = {}
+    replies: Record<string, string> = {}
+    private reading = new Set<string>()
+    /** « hide handled »: only the active threads in the list */
+    hideHandled = true
+    /** « by lane »: the list grouped under one header per lane */
+    byLane = false
+    /** the threads whose older versions are unfolded, by head id */
+    unfolded: Record<string, boolean> = {}
+    busy = false
+    error: string | null = null
+    /** the card against its answer, his pick, kept with the prefs */
+    place: CardPlace = 'auto'
+    /** the page is narrower than STACK_PX */
+    narrow = false
+    readonly compare: CompareSt
+    readonly phone = new PhoneSt()
+    private timer: ReturnType<typeof setInterval> | null = null
+    private readonly loadList: () => Promise<Listing>
+    private readonly loadWatchers: () => Promise<Watcher[]>
+    private readonly prefix: string
+
+    /** the page measured its width */
+    fit(px: number): void {
+        const on = px > 0 && px < STACK_PX
+        if (this.narrow !== on) this.narrow = on
+    }
+    /** the card over its answer in one column: picked, or `auto` on a narrow page */
+    get stacked(): boolean {
+        return this.place === 'top' || (this.place === 'auto' && this.narrow)
+    }
+    setPlace(p: CardPlace): void {
+        this.place = p
+    }
+    /** the open card as thin option rows: a choice, or views that each play alone, unless he asked them full */
+    get rows(): boolean {
+        const x = this.open
+        return x !== null && asOptions(x.item) && this.full[x.item.id] !== true
+    }
+    setFull(on: boolean): void {
+        const id = this.open?.item.id
+        if (id) this.full = { ...this.full, [id]: on }
+    }
+    get choice(): boolean {
+        const x = this.open
+        return x !== null && isChoice(x.item)
+    }
+    /** the card's header (title, state, what, and in one column the verdicts) sits over its views: one column, the
+     *  phone's card pane, a choice's options */
+    get headInViews(): boolean {
+        return this.stacked || this.phone.on || this.choice
+    }
+    toggleRow(i: number): void {
+        this.openRows = { ...this.openRows, [i]: !this.openRows[i] }
+    }
+
+    constructor(private readonly st: RepoSt) {
+        this.prefix = `shipkit.review.${st.key}.`
+        this.loadList = unchangedAware(() => st.url('/api/review'))
+        this.loadWatchers = unchangedAware(() => st.url('/api/review/watchers'))
+        this.compare = new CompareSt(`${this.prefix}compare`)
+        try {
+            const p = JSON.parse(store.get(`${this.prefix}prefs`) ?? '{}') as { hideHandled?: boolean; byLane?: boolean; zoom?: string; marks?: boolean; place?: string }
+            if (p.hideHandled === false) this.hideHandled = false
+            if (p.byLane === true) this.byLane = true
+            if (p.marks === false) this.marksOn = false
+            if ((ZOOMS as readonly string[]).includes(p.zoom ?? '')) this.zoom = p.zoom as Zoom
+            if ((CARD_PLACES as readonly string[]).includes(p.place ?? '')) this.place = p.place as CardPlace
+        } catch {
+            // a broken pref is the default
+        }
+        makeAutoObservable<this, 'st' | 'clips' | 'clipsCard' | 'reading' | 'timer' | 'loadList' | 'loadWatchers' | 'prefix'>(this, {
+            st: false,
+            clips: false,
+            clipsCard: false,
+            reading: false,
+            timer: false,
+            loadList: false,
+            loadWatchers: false,
+            prefix: false,
+            compare: false,
+            phone: false,
+        })
+        // opening a card reads the agent's messages on its whole thread
+        reaction(
+            () => (this.openThread ? membersOf(this.openThread) : []).filter((x) => unreadBy(x, 'owner').length > 0).map((x) => x.item.id),
+            (ids) => {
+                for (const id of ids) void this.markRead(id)
+            },
+        )
+        reaction(
+            () => JSON.stringify({ hideHandled: this.hideHandled, byLane: this.byLane, zoom: this.zoom, marks: this.marksOn, place: this.place }),
+            (s) => store.put(`${this.prefix}prefs`, s),
+        )
+    }
+
+    /** the list and the watchers, read now and every 2 s while the page shows; the unit's words once a start */
+    start(): void {
+        void this.refresh()
+        void fetch(this.st.url('/api/review/spec'))
+            .then((r) => (r.ok ? (r.json() as Promise<RepoSpec>) : null))
+            .catch(() => null)
+            .then((spec) => runInAction(() => (this.spec = spec)))
+        if (this.timer === null) this.timer = setInterval(() => void this.refresh(), POLL_MS)
+    }
+
+    stop(): void {
+        if (this.timer !== null) clearInterval(this.timer)
+        this.timer = null
+    }
+
+    async refresh(): Promise<void> {
+        try {
+            const [list, watchers] = await Promise.all([this.loadList(), this.loadWatchers().catch(() => this.watchers)])
+            runInAction(() => {
+                if (list !== this.list) this.list = list
+                if (watchers !== this.watchers) this.watchers = watchers
+                this.listError = null
+            })
+        } catch (e) {
+            runInAction(() => (this.listError = (e as Error).message))
+        }
+    }
+
+    /** the card's folder, or one of its files, shown in the Finder of the machine the hub runs on */
+    async reveal(id: string, file?: string): Promise<void> {
+        try {
+            await postJson(this.st.url(`/api/review/${id}/reveal`), file ? { file } : {})
+        } catch (e) {
+            runInAction(() => (this.error = (e as Error).message))
+        }
+    }
+
+    setBoard(on: boolean): void {
+        this.board = on
+    }
+
+    fileUrl(id: string, name: string): string {
+        return this.st.url(`/api/review/${id}/${name}`)
+    }
+
+    thumbUrl(x: ReviewItem, name: string): string {
+        return /\.(png|jpe?g|webp)$/.test(name) ? this.st.url(`/api/review/${x.item.id}/thumb/${name}`) : this.fileUrl(x.item.id, name)
+    }
+
+    threadImageUrl(id: string, name: string): string {
+        return this.st.url(`/api/review/${id}/thread/${name}`)
+    }
+
+    get items(): ReviewItem[] {
+        return this.list?.items ?? []
+    }
+
+    get broken(): Listing['broken'] {
+        return this.list?.broken ?? []
+    }
+
+    statusOf(x: ReviewItem): ShownStatus {
+        return statusOf(x, this.items)
+    }
+
+    get followed(): Set<string> {
+        return followedIds(this.items)
+    }
+
+    reworkOf(x: ReviewItem): ReturnType<typeof reworkOf> {
+        return reworkOf(x, this.followed.has(x.item.id), new Date())
+    }
+
+    /** the live watches that read his answer on any of these cards */
+    listenersOf(cards: readonly ReviewItem[]): Watcher[] {
+        return this.watchers.filter((w) =>
+            cards.some((x) => (w.session === null || (x.item.origin.by === 'agent' && x.item.origin.session === w.session)) && (w.lane === null || laneOf(x) === w.lane)),
+        )
+    }
+
+    get threads(): Thread[] {
+        return orderedThreads(this.items)
+    }
+
+    /** what waits on him: the cards waiting for the owner's verdict, and what he raised that asks him */
+    get pendingCount(): number {
+        return this.threads.filter((t) => waits(t.head) || (t.head.item.origin.by !== 'agent' && this.moveOf(t.head) === 'owner')).length
+    }
+
+    get activeCount(): number {
+        return this.threads.filter((t) => isActive(t)).length
+    }
+
+    /** the subject kinds this store holds, for the filter */
+    get subjects(): string[] {
+        return [...new Set(this.items.map((x) => x.item.subject.kind))].sort()
+    }
+
+    /** the list as the switch, the filters and the search show it: one thread per head */
+    get visible(): Thread[] {
+        const q = this.query.trim().toLowerCase()
+        return this.threads.filter(
+            (t) =>
+                (!this.hideHandled || isActive(t)) &&
+                (this.subject === null || t.head.item.subject.kind === this.subject) &&
+                (this.whose === null || this.moveOf(t.head) === this.whose) &&
+                (this.status === null || this.statusOf(t.head) === this.status) &&
+                (q === '' || membersOf(t).some((x) => `${x.item.title} ${x.item.what ?? ''} ${x.item.id}`.toLowerCase().includes(q))),
+        )
+    }
+
+    /** the visible threads under one header per lane; null: the cards with no lane */
+    get laneGroups(): { lane: string | null; threads: Thread[] }[] {
+        const groups = new Map<string | null, Thread[]>()
+        for (const t of this.visible) {
+            const lane = laneOf(t.head) ?? null
+            groups.set(lane, [...(groups.get(lane) ?? []), t])
+        }
+        const all = [...groups].map(([lane, threads]) => ({ lane, threads }))
+        return [...all.filter((g) => g.lane !== null), ...all.filter((g) => g.lane === null)]
+    }
+
+    get open(): ReviewItem | null {
+        return this.items.find((x) => x.item.id === this.selectedId) ?? this.visible[0]?.head ?? this.threads[0]?.head ?? null
+    }
+
+    get openThread(): Thread | null {
+        const id = this.open?.item.id
+        return id === undefined ? null : threadOfItem(id, this.threads)
+    }
+
+    /** the reports and notes nested in the open card */
+    get answered(): ReviewItem[] {
+        const t = this.openThread
+        const id = this.open?.item.id
+        return t && t.versions.some((x) => x.item.id === id) ? t.answers : []
+    }
+
+    get answeredBy(): ReviewItem | null {
+        const x = this.open
+        return x && x.item.origin.by !== 'agent' ? answererOf(x.item.id, this.items) : null
+    }
+
+    /** the older versions of the open card, the newest of them first */
+    get history(): ReviewItem[] {
+        const x = this.open
+        return x ? chainOf(x, this.items).slice(1) : []
+    }
+
+    get newer(): ReviewItem[] {
+        const x = this.open
+        return x ? childrenOf(x.item.id, this.items) : []
+    }
+
+    showsVersions(t: Thread): boolean {
+        return this.unfolded[t.head.item.id] === true || t.versions.slice(1).some((x) => x.item.id === this.selectedId)
+    }
+
+    fold(headId: string): void {
+        this.unfolded = { ...this.unfolded, [headId]: !this.unfolded[headId] }
+    }
+
+    setHideHandled(on: boolean): void {
+        this.hideHandled = on
+    }
+
+    setByLane(on: boolean): void {
+        this.byLane = on
+    }
+
+    setQuery(q: string): void {
+        this.query = q
+    }
+
+    setFilter(f: { subject?: string | null; whose?: Move | null; status?: ShownStatus | null }): void {
+        if (f.subject !== undefined) this.subject = f.subject
+        if (f.whose !== undefined) this.whose = f.whose
+        if (f.status !== undefined) this.status = f.status
+    }
+
+    moveOf(x: ReviewItem): Move {
+        return moveOf(stateOf(x, this.followed.has(x.item.id)).state)
+    }
+
+    /** what the form edits: the draft, else the sent feedback, else nothing yet */
+    get draft(): Draft {
+        const x = this.open
+        if (!x) return { rects: [], comment: '' }
+        const v = verdictOf(x)
+        const sent = v?.reactions
+        return (
+            this.drafts[x.item.id] ?? {
+                rects: v?.rects ?? [],
+                comment: v?.comment ?? '',
+                ...(sent && sent.length > 0 ? { reactions: sent } : {}),
+                ...(v?.pick !== undefined ? { pick: v.pick } : {}),
+            }
+        )
+    }
+
+    get dirty(): boolean {
+        const x = this.open
+        return x !== null && this.drafts[x.item.id] !== undefined
+    }
+
+    private edit(f: (d: Draft) => Draft): void {
+        const x = this.open
+        if (!x) return
+        const d = this.draft
+        const { reactions, ...rest } = f({ ...d, rects: [...d.rects], reactions: [...(d.reactions ?? [])] })
+        const next: Draft = reactions && reactions.length > 0 ? { ...rest, reactions } : rest
+        this.drafts = { ...this.drafts, [x.item.id]: next }
+        store.put(`${this.prefix}draft.${x.item.id}`, JSON.stringify(next))
+    }
+
+    /** opens a card from the page: its address follows */
+    pick(id: string): void {
+        this.st.showReview(id)
+        if (this.phone.on) this.phone.show('card')
+    }
+
+    /** what the address carries beside the card: its view and the list's filters, `view=1&subject=place`, each only
+     *  off its default (`handled=1` shows the handled threads, `lanes=1` groups by lane) */
+    get address(): string {
+        const q = new URLSearchParams()
+        if (this.view > 0) q.set('view', String(this.view))
+        if (this.subject !== null) q.set('subject', this.subject)
+        if (this.whose !== null) q.set('whose', this.whose)
+        if (this.status !== null) q.set('status', this.status)
+        if (!this.hideHandled) q.set('handled', '1')
+        if (this.byLane) q.set('lanes', '1')
+        return q.toString()
+    }
+
+    /** an address's view and filters read back: a key it leaves out keeps what the page has; an unknown value is dropped */
+    applyAddress(raw: string): void {
+        const q = new URLSearchParams(raw)
+        const view = Number(q.get('view'))
+        if (Number.isInteger(view) && view > 0) this.view = view
+        const subject = q.get('subject')
+        if (subject) this.subject = subject
+        const whose = q.get('whose')
+        if (whose === 'owner' || whose === 'agents' || whose === 'none') this.whose = whose
+        const status = q.get('status')
+        if (status !== null && isShownStatus(status)) this.status = status
+        if (q.get('handled') === '1') this.hideHandled = false
+        if (q.get('lanes') === '1') this.byLane = true
+    }
+
+    /** the card the address names; its draft is read again from storage, the truth over every window */
+    select(id: string | null): void {
+        if (id !== this.selectedId) {
+            this.view = 0
+            this.viewZoom = {}
+            this.bigTile = null
+            this.openRows = {}
+            // a link to a card on the phone opens the card, never the list
+            if (id !== null && this.phone.on) this.phone.show('card')
+        }
+        this.selectedId = id
+        if (id !== null) {
+            const stored = draftOf(store.get(`${this.prefix}draft.${id}`))
+            if (stored) this.drafts = { ...this.drafts, [id]: stored }
+            else if (this.drafts[id]) {
+                const { [id]: _, ...rest } = this.drafts
+                this.drafts = rest
+            }
+        }
+        this.rect = null
+        this.error = null
+    }
+
+    /** ↑↓ on the page: the next thread head the list shows */
+    move(delta: 1 | -1): void {
+        const list = this.visible
+        const at = list.findIndex((t) => t.head.item.id === this.openThread?.head.item.id)
+        const next = list[Math.max(0, Math.min(list.length - 1, at + delta))]
+        if (next) this.pick(next.head.item.id)
+    }
+
+    /** N: the next pending thread head after the open one, wrapping */
+    nextPending(): void {
+        const pend = this.threads.filter((t) => waits(t.head))
+        if (pend.length === 0) return
+        const at = pend.findIndex((t) => t.head.item.id === this.open?.item.id)
+        const next = pend[(at + 1) % pend.length]
+        if (next) this.pick(next.head.item.id)
+    }
+
+    /** a rectangle on a view, which becomes the active one; on a clip it keeps the time of the frame shown */
+    addRect(r: { x: number; y: number; w: number; h: number }, side: Side | undefined, on: number = this.view): void {
+        if (on !== this.view) this.setView(on)
+        const view = this.view > 0 ? { view: this.view } : {}
+        const t = this.clipKey ? { t: Math.round(this.clip.time * 1000) / 1000 } : {}
+        this.edit((d) => ({ ...d, rects: [...d.rects, { ...r, comment: '', ...view, ...(side ? { side } : {}), ...t }] }))
+        this.rect = this.draft.rects.length - 1
+    }
+
+    setView(i: number): void {
+        this.view = i
+        this.rect = null
+    }
+
+    /** the playable view an option row or a clip shows: a clip, or a sound shown as a row */
+    private playableAt(i: number): MediaView | null {
+        const v = this.open?.item.views[i]
+        if (!v || isGallery(v)) return null
+        return v.clip || (v.audio && this.rows && !isPair(v.files)) ? v : null
+    }
+
+    get openView(): MediaView | null {
+        const v = this.open?.item.views[this.view]
+        return v && !isGallery(v) ? v : null
+    }
+
+    zoomOf(i: number): Zoom {
+        return this.viewZoom[i] ?? this.zoom
+    }
+
+    setZoom(z: Zoom): void {
+        this.zoom = z
+        this.viewZoom = {}
+    }
+
+    setViewZoom(i: number, z: Zoom): void {
+        this.viewZoom = { ...this.viewZoom, [i]: z }
+    }
+
+    toggleTile(view: number, tile: number): void {
+        const k = `${view}/${tile}`
+        this.bigTile = this.bigTile === k ? null : k
+    }
+
+    reactionOf(view: number, tile?: number): ReviewReaction | null {
+        return (this.draft.reactions ?? []).find((r) => sameSpot(r, view, tile)) ?? null
+    }
+
+    /** a reaction's toggle: sets that status, or clears it when it is already the one */
+    react(view: number, tile: number | undefined, status: ReviewStatus): void {
+        const cur = this.reactionOf(view, tile)
+        this.putReaction(view, tile, { ...cur, status: cur?.status === status ? undefined : status, comment: cur?.comment ?? '' })
+    }
+
+    setReactionComment(view: number, tile: number | undefined, comment: string): void {
+        this.putReaction(view, tile, { ...this.reactionOf(view, tile), comment })
+    }
+
+    /** an option's stars; the same number again clears them */
+    setStars(view: number, n: number): void {
+        const cur = this.reactionOf(view)
+        this.putReaction(view, undefined, { ...cur, comment: cur?.comment ?? '', stars: cur?.stars === n ? undefined : n })
+    }
+
+    removeReaction(view: number, tile: number | undefined): void {
+        this.putReaction(view, tile, { comment: '' })
+    }
+
+    /** « pick »: that option is his answer, sent at once as an approval; his stars and words go with it */
+    async choose(view: number): Promise<void> {
+        if (!this.choice) return
+        this.edit((d) => ({ ...d, pick: view }))
+        await this.submit('approved')
+    }
+
+    /** the reactions that go to the agent with the verdict, in the card's order */
+    get outgoingReactions(): ReviewReaction[] {
+        return [...(this.draft.reactions ?? [])].sort((a, b) => a.view - b.view || (a.tile ?? -1) - (b.tile ?? -1))
+    }
+
+    private putReaction(view: number, tile: number | undefined, r: { status?: ReviewStatus | undefined; comment: string; stars?: number | undefined }): void {
+        const next: ReviewReaction = { view, ...(tile !== undefined ? { tile } : {}), ...(r.status ? { status: r.status } : {}), comment: r.comment, ...(r.stars ? { stars: r.stars } : {}) }
+        const empty = !r.status && r.comment === '' && !r.stars
+        this.edit((d) => {
+            const rest = (d.reactions ?? []).filter((q) => !sameSpot(q, view, tile))
+            return { ...d, reactions: empty ? rest : [...rest, next] }
+        })
+    }
+
+    /** the open view's clip identity (a clip, or a sound on a row), empty when it shows images */
+    get clipKey(): string {
+        const x = this.open
+        return x && this.playableAt(this.view) ? `${x.item.id}#${this.view}` : ''
+    }
+
+    /** a row's ▶: that option plays with its sound, the one playing before it stops; again, it pauses */
+    listen(i: number): void {
+        this.setView(i)
+        const c = this.clipOf(i)
+        if (c.paused) c.listen()
+        else c.pause()
+    }
+
+    /** the clock of a clip view of the open card: every clip view plays and steps on its own */
+    clipOf(view: number): ClipSt {
+        const id = this.open?.item.id ?? ''
+        if (id !== this.clipsCard) {
+            this.clips.clear()
+            this.clipsCard = id
+        }
+        let c = this.clips.get(view)
+        if (!c) {
+            c = new ClipSt()
+            const views = this.open?.item.views ?? []
+            const v = views[view]
+            const media = v && !isGallery(v) ? v : undefined
+            // one thing plays at a time: the first clip of a card loops on its own, the others and every option wait
+            const first = views.findIndex((w) => !isGallery(w) && w.clip !== undefined)
+            const still = this.rows || view !== first
+            if (media?.audio) c.load(`${id}#${view}`, media.audio.duration, SOUND_FPS, true)
+            else c.load(`${id}#${view}`, media?.clip?.duration ?? 0, media?.clip?.fps ?? 20, still)
+            this.clips.set(view, c)
+        }
+        return c
+    }
+
+    get clip(): ClipSt {
+        return this.clipOf(this.view)
+    }
+
+    get conversation(): ReturnType<typeof conversationOf> {
+        const t = this.openThread
+        return t ? conversationOf(t) : []
+    }
+
+    /** a thread holds an agent message he has not read: its card shows a dot */
+    unread(t: Thread): boolean {
+        return membersOf(t).some((x) => unreadBy(x, 'owner').length > 0)
+    }
+
+    get reply(): string {
+        const id = this.open?.item.id
+        return id ? (this.replies[id] ?? store.get(`${this.prefix}reply.${id}`) ?? '') : ''
+    }
+
+    setReply(text: string): void {
+        const id = this.open?.item.id
+        if (!id) return
+        this.replies = { ...this.replies, [id]: text }
+        store.put(`${this.prefix}reply.${id}`, text || null)
+    }
+
+    /** ⌘Enter or « reply »: his message goes to the open card */
+    async sendReply(): Promise<void> {
+        const x = this.open
+        const text = this.reply.trim()
+        if (!x || !text || this.busy) return
+        const id = x.item.id
+        this.busy = true
+        this.error = null
+        try {
+            await postJson(this.st.url(`/api/review/${id}/reply`), { text })
+            runInAction(() => {
+                const { [id]: _, ...rest } = this.replies
+                this.replies = rest
+                store.put(`${this.prefix}reply.${id}`, null)
+            })
+            void this.refresh()
+        } catch (e) {
+            runInAction(() => (this.error = (e as Error).message))
+        } finally {
+            runInAction(() => (this.busy = false))
+        }
+    }
+
+    private async markRead(id: string): Promise<void> {
+        if (this.reading.has(id)) return
+        this.reading.add(id)
+        try {
+            await postJson(this.st.url(`/api/review/${id}/read`), {})
+            void this.refresh()
+        } catch (e) {
+            runInAction(() => (this.error = (e as Error).message))
+        } finally {
+            this.reading.delete(id)
+        }
+    }
+
+    toggleMarks(): void {
+        this.marksOn = !this.marksOn
+    }
+
+    /** a rectangle picked: its view comes on screen, and on a clip its frame, paused */
+    pickRect(i: number | null): void {
+        this.rect = i
+        if (i === null) return
+        const r = this.draft.rects[i]
+        this.view = r?.view ?? 0
+        if (r?.t === undefined || !this.clipKey) return
+        this.clip.seek(r.t)
+    }
+
+    setRectComment(i: number, comment: string): void {
+        this.edit((d) => ({ ...d, rects: d.rects.map((r, j) => (j === i ? { ...r, comment } : r)) }))
+    }
+
+    removeRect(i: number): void {
+        this.edit((d) => ({ ...d, rects: d.rects.filter((_, j) => j !== i) }))
+        this.rect = null
+    }
+
+    setComment(comment: string): void {
+        this.edit((d) => ({ ...d, comment }))
+    }
+
+    /** back to what was sent */
+    dropDraft(): void {
+        const x = this.open
+        if (!x) return
+        const { [x.item.id]: _, ...rest } = this.drafts
+        this.drafts = rest
+        store.put(`${this.prefix}draft.${x.item.id}`, null)
+        this.rect = null
+    }
+
+    /** V, F, R, A: the draft goes to the card's thread as the owner's verdict, through the server */
+    async submit(status: ReviewStatus): Promise<void> {
+        const x = this.open
+        if (!x || this.busy) return
+        if (x.item.origin.by !== 'agent') {
+            this.error = 'this item was raised, not shown by an agent: a word on it goes in a reply'
+            return
+        }
+        if (x.item.wip) {
+            this.error = 'a draft card: the verdict comes once its agent makes it ready; a word goes in a reply'
+            return
+        }
+        const id = x.item.id
+        const d = this.draft
+        this.busy = true
+        this.error = null
+        try {
+            const pick = isChoice(x.item) && isApproved(status) && d.pick !== undefined ? { pick: d.pick } : {}
+            const m = await postJson<Message>(this.st.url(`/api/review/${id}/feedback`), { status, comment: d.comment, rects: d.rects, reactions: d.reactions ?? [], ...pick })
+            runInAction(() => {
+                // the verdict shows at once: the list of every card comes back after it
+                const r = this.list
+                if (r) this.list = { ...r, items: r.items.map((y) => (y.item.id === id ? { ...y, thread: [...y.thread, m] } : y)) }
+                const { [id]: _, ...rest } = this.drafts
+                this.drafts = rest
+                store.put(`${this.prefix}draft.${id}`, null)
+            })
+            void this.refresh()
+            // the tree's count of what waits on him moves at once
+            void this.st.cols.poll(true)
+        } catch (e) {
+            runInAction(() => (this.error = (e as Error).message))
+        } finally {
+            runInAction(() => (this.busy = false))
+        }
+    }
+
+    /** the page's keys, as the atelier takes its own: true when it used the key. V approves, F ok with a fix, R rejects,
+     *  A archives, N the next waiting card, M the rings, Delete the picked rectangle; on a clip Space plays, ← → a frame
+     *  (a sound: two seconds); on option rows 1 to 9 play that row, ⇧1 to ⇧5 score the row playing, P picks it. A digit is
+     *  read from its physical key (`code`), so ⇧ and an AZERTY keyboard read the same */
+    key(e: Pick<KeyboardEvent, 'key' | 'shiftKey'> & { code?: string }): boolean {
+        const k = e.key.toLowerCase()
+        const digit = Number(/^Digit([1-9])$/.exec(e.code ?? '')?.[1] ?? (/^[1-9]$/.test(e.key) ? e.key : 0))
+        const sound = this.openView?.audio !== undefined
+        if (this.rows && digit > 0 && !e.shiftKey) {
+            if (digit <= (this.open?.item.views.length ?? 0)) this.listen(digit - 1)
+        } else if (this.choice && this.rows && digit > 0 && e.shiftKey) {
+            if (digit <= STARS) this.setStars(this.view, digit)
+        } else if (this.choice && k === 'p') void this.choose(this.view)
+        else if (this.clipKey && e.key === ' ') {
+            if (this.clip.paused && this.rows) this.clip.listen()
+            else this.clip.toggle()
+        } else if (this.clipKey && sound && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) this.clip.jump(this.clip.time + (e.key === 'ArrowRight' ? SOUND_JUMP : -SOUND_JUMP))
+        else if (this.clipKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) this.clip.step(e.key === 'ArrowRight' ? 1 : -1)
+        else if (e.key === 'ArrowUp' || e.key === 'ArrowDown') this.move(e.key === 'ArrowDown' ? 1 : -1)
+        else if (k === 'v') void this.submit('approved')
+        else if (k === 'f') void this.submit('approved-with-fix')
+        else if (k === 'r') void this.submit('rejected')
+        else if (k === 'a') void this.submit('archived')
+        else if (k === 'n') this.nextPending()
+        else if (k === 'm') this.toggleMarks()
+        else if ((e.key === 'Delete' || e.key === 'Backspace') && this.rect !== null) this.removeRect(this.rect)
+        else return false
+        return true
+    }
+}