rvlib-shipkit 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.8.0
+
+- **A brand's `icon` draws the favicon family at each size.** `icon: canvas(draw)` in `.shipkit/identity/brand.ts` draws `favicon.png` (512), `favicon-32.png`, `favicon-16.png` and `apple-touch-icon.png` (180, flattened on `palette.bg`), each at its own size, `asset.id` naming the file, so a 16 px tab reads a shape made for it, never a shrunk logo. Without one the favicon is the logo master resized, as before.
+- **comfy-ts is an optional peer, no longer a dependency.** A repo that never declares comfy no longer installs it (npm and bun both skip an optional peer). The toolkit names comfy-ts in no import, a type import included, so importing it, `sk ci`, `sk serve`, the hub and `sk assets identity` never load it. It is loaded at the first workflow load, from the repo's copy. A repo with comfy kinds or `.cflow.ts` modules installs it itself: `bun add -d comfy-ts`. Without it, a workflow load fails loud with that line, and `sk sound` fails loud when no `comfy-ts` is on PATH. `LoadedWorkflow.wf` is typed by the toolkit's own `CflowWorkflow`, the slice of comfy-ts it drives, held to comfy-ts's types by a test.
+- **`og.png` is written small.** The identity writer encodes the og card as a 256 colour palette png at maximum compression: invisible at preview size, and a photo card drops about 3x (pkm-multi's banner card: 970 KB → 280 KB), under the size where some chat apps stop showing a preview. The file name and format stay `og.png`.
+
+## 2.7.0
+
+- **What waits on the owner is a pill on every repo's row of the project list.** Beside the open asks badge, a pill in the review hue counts the cards that wait on the owner's verdict or answer; zero draws none, and folded it rides the icon's top left corner. A click opens that repo's review page on its first waiting card, the list on the owner's move. One count, `waitingCards` (`collections/review.ts`), read by the tree's review row, `sk needs`, the review page and the list; `/api/projects.json` reads it on every request, so a new card shows within one poll and a verdict at once. Below 768 px the list is always the rail, so the pills show on a phone.
+- **A trailer's score is the game's waveform, not only its level.** A note starts on its time's nearest sample frame, as the game's synth now rounds it (a time a hair past a frame, 14.450000000000001, no longer starts a frame late); a noise note's playback rate is held per 128 frame block, the browser's k-rate, its sweep starting at the next block (risers and whooshes were another noise). pkm-multi's main4: 38 of 38 sections within 0.1 dB and every one the same waveform, the difference at least 40 dB under it (four were about 10 dB). Every score renders again once.
+- **`sk fleet` skips a linked worktree.** A dir whose `.git` is a file is its main checkout again, as the home already reads it: `--update` no longer dirties a checkout that only follows main (a `-live` one) and blocks its own updater.
+- **A « fix » or a « no » the agent read is still owed.** It stays `claimed` and active (« hide handled » no longer hides it) until `sk review done`, `wontfix` or a new version; `sk review inbox` lists it under `owed`.
+
 ## 2.6.0
 
 - **A trailer's score sounds as the game's browser synth, section for section.** A note that starts inside a 128 frame block takes the phase the browser gives it (it runs at the default 440 Hz until its own frame of that block), so overlapping notes of one pitch, a timpani roll, add or cancel as in the browser; `osc: 'square'` is the browser's own square wave, no longer a sine; the master's compressor and limiter are the browser's kernel (32 frame divisions, adaptive release, the sine warp on the gain). pkm-multi's main4 score: 38 of 38 sections within 0.1 dB of the game's render (were 18), each octave band within 0.15 dB. Every score renders again once.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.6.0",
+    "version": "2.8.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
@@ -25,7 +25,8 @@
         "@types/bun": "^1.3.14",
         "@types/react": "^19.2.17",
         "@types/react-dom": "^19.2.3",
-        "@types/sanitize-html": "^2.16.1"
+        "@types/sanitize-html": "^2.16.1",
+        "comfy-ts": "^2.9.0"
     },
     "overrides": {
         "mobx": "^7.0.0",
@@ -38,7 +39,6 @@
         "@floating-ui/react": "^0.27.20",
         "@napi-rs/canvas": "^1.1.0",
         "clipanion": "^4.0.0-rc.4",
-        "comfy-ts": "^2.9.0",
         "ink": "^7.1.1",
         "marked": "^18.0.7",
         "mobx": "^7.0.0",
@@ -48,5 +48,13 @@
         "react-resizable-panels": "^4.13.3",
         "sanitize-html": "^2.17.6",
         "sharp": "^0.35.3"
+    },
+    "peerDependencies": {
+        "comfy-ts": "^2.9.0"
+    },
+    "peerDependenciesMeta": {
+        "comfy-ts": {
+            "optional": true
+        }
     }
 }

package/src/assets/gen/comfyts-gen.ts

@@ -4,16 +4,40 @@
 // must disconnectAll() in a finally, or the host websocket keeps bun alive.
 // Workflows are discriminated by duck-typing, never instanceof: a consumer's
 // .cflow.ts may hold a second copy of comfy-ts in its module graph.
+// comfy-ts is an optional peer: this file is the one place that loads it, at
+// the first workflow load, and never names it in an import, so a repo without
+// it imports and typechecks the toolkit (tests/comfy-optional.test.ts).
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { basename, join } from 'path'
 import { pathToFileURL } from 'url'
-import { ComfyTS, type AnyVar, type ComfyExecution, type DefinedWorkflow, type MediaImage } from 'comfy-ts'
+
+// the slice of comfy-ts the toolkit drives, held to comfy-ts's own types by
+// tests/comfy-optional.test.ts
+export type CflowVar = { readonly kind: string; parse(raw: string): boolean; loadJSON(value: unknown): unknown; reset(): unknown }
+export type CflowImage = { readonly ComfyNode: { class_type?: string } | null | undefined; readonly metadata: { type?: string }; readonly buffer: Uint8Array }
+export type CflowExecution = { readonly status: string | null | undefined; data: { error?: unknown }; images: CflowImage[]; imageErrors: unknown[] }
+export type CflowHost = {
+    data: { id: string }
+    schema: { readonly size: number }
+    getServerHostHTTP(): string
+    disconnect(): void
+    interrupt(): Promise<void>
+}
+export type CflowWorkflow = {
+    spec: { id?: string }
+    readonly vars: { [key: string]: CflowVar }
+    host: CflowHost
+    entries(): [string, CflowVar][]
+    build(): Promise<{ problems: { title: string }[]; readonly size: number }>
+    run(settings?: { onProgress?: (p: { percent: number; nodeName: string | null }) => void }): Promise<CflowExecution>
+}
+type ComfyTsModule = { ComfyTS?: { create(o: { rootPath: string }): unknown } }
 
 export type GenProgress = { value: number; max: number; node: string | null }
 export type OnProgress = (p: GenProgress) => void
 
 /** root: the repo the workflow belongs to, which holds its drafts */
-export type LoadedWorkflow = { id: string; root: string; file: string; wf: DefinedWorkflow }
+export type LoadedWorkflow = { id: string; root: string; file: string; wf: CflowWorkflow }
 export type ComfyTsRuntime = { workflows: Map<string, LoadedWorkflow>; heal?: string }
 
 // function declaration, not const — TS only narrows on never-calls to
@@ -22,35 +46,39 @@ function fail(msg: string): never { throw new Error(msg) }
 
 // same duck predicate the comfy-ts TUI and serve bind to: a module valid
 // for shipkit is valid for `bunx comfy-ts tui` and vice versa
-function findDefinedWorkflow(mod: Record<string, unknown>): DefinedWorkflow | null {
-    const isDefined = (x: unknown): x is DefinedWorkflow =>
+function findDefinedWorkflow(mod: Record<string, unknown>): CflowWorkflow | null {
+    const isDefined = (x: unknown): x is CflowWorkflow =>
         typeof x === 'object' && x != null && 'spec' in x &&
-        typeof (x as DefinedWorkflow).run === 'function' &&
-        typeof (x as DefinedWorkflow).entries === 'function'
+        typeof (x as CflowWorkflow).run === 'function' &&
+        typeof (x as CflowWorkflow).entries === 'function'
     return [mod.default, ...Object.values(mod)].find(isDefined) ?? null
 }
 
-const varsOf = (wf: DefinedWorkflow): Record<string, AnyVar> => wf.vars as Record<string, AnyVar>
-
 /** true when the image belongs in a roll. Preview-family nodes (PreviewImage,
  *  PreviewBridge, …) emit raw temp images that comfy-ts downloads like any
  *  output, in completion order, and MediaImage drops the server-side
  *  'temp' marker, so the producing node's class_type is the only signal left.
  *  no node json (SaveImageWebsocket frames) = deliberate output, kept. */
-export const isRollImage = (img: Pick<MediaImage, 'ComfyNode'>): boolean =>
+export const isRollImage = (img: Pick<CflowImage, 'ComfyNode'>): boolean =>
     !/preview/i.test(img.ComfyNode?.class_type ?? '')
 
-/** the ComfyTS class of the comfy-ts a bare import from `dir` reaches,
- *  shipkit's own when the repo carries none */
-async function comfyTsOf(dir: string): Promise<typeof ComfyTS> {
-    let path: string
-    try {
-        path = Bun.resolveSync('comfy-ts', dir)
-    } catch {
-        return ComfyTS
+const COMFY_TS = 'comfy-ts'
+const INSTALL_COMFY_TS = 'Install it in this repo: bun add -d comfy-ts'
+
+/** the ComfyTS class of the comfy-ts a bare import from `dir` reaches, else
+ *  the toolkit's own; loud when neither is installed */
+async function comfyTsOf(dir: string): Promise<NonNullable<ComfyTsModule['ComfyTS']>> {
+    for (const from of [dir, import.meta.dir]) {
+        let path: string
+        try {
+            path = Bun.resolveSync(COMFY_TS, from)
+        } catch {
+            continue
+        }
+        const mod = (await import(path)) as ComfyTsModule
+        if (typeof mod.ComfyTS?.create === 'function') return mod.ComfyTS
     }
-    const mod = (await import(path)) as { ComfyTS?: typeof ComfyTS }
-    return typeof mod.ComfyTS?.create === 'function' ? mod.ComfyTS : ComfyTS
+    fail(`comfy-ts is not installed, and ${dir}/ holds comfy-ts workflow modules. ${INSTALL_COMFY_TS}`)
 }
 
 /** dir = the flat folder holding the <id>.cflow.ts workflow modules.
@@ -74,7 +102,10 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
     for (const f of readdirSync(dir).filter((x) => x.endsWith('.cflow.ts')).sort()) {
         const file = join(dir, f)
         const id = basename(f, '.cflow.ts')
-        const mod = (await import(pathToFileURL(file).href)) as Record<string, unknown>
+        const mod = (await import(pathToFileURL(file).href).catch((e: Error) => {
+            if (/Cannot find (package|module) 'comfy-ts'/.test(e.message)) fail(`${file} imports comfy-ts, which this repo does not install. ${INSTALL_COMFY_TS}`)
+            throw e
+        })) as Record<string, unknown>
         const wf = findDefinedWorkflow(mod)
         if (wf == null) fail(`${file}: exports no DefinedWorkflow — export default host.defineWorkflow({...})`)
         // the file name IS the id: it is also the comfy-ts draft folder key,
@@ -96,7 +127,7 @@ export function workflowFor(workflows: Map<string, LoadedWorkflow>, ref: { workf
         : workflows.size === 1
           ? [...workflows.values()][0]!
           : fail(`asset '${ref.assetId ?? '?'}' names no workflow and ${workflows.size} are loaded (${[...workflows.keys()].join(', ')}) — set workflow on the kind`)
-    const vars = varsOf(lw.wf)
+    const vars = lw.wf.vars
     if (vars.prompt?.kind !== 'prompt' || vars.seed?.kind !== 'seed')
         fail(`kind '${ref.kind ?? '?'}' drives workflow '${lw.id}', which must declare vars.prompt (v.prompt) and vars.seed (v.seed) — the atelier writes both`)
     return lw
@@ -105,8 +136,8 @@ export function workflowFor(workflows: Map<string, LoadedWorkflow>, ref: { workf
 /** Apply a name→value record onto a workflow's vars: strings go through
  *  parse (validated), everything else through loadJSON (the drafts setter).
  *  Unknown names throw listing what the workflow has. */
-export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown>, source: string): void {
-    const defs = varsOf(wf)
+export function applyVarValues(wf: CflowWorkflow, vars: Record<string, unknown>, source: string): void {
+    const defs = wf.vars
     for (const [name, value] of Object.entries(vars)) {
         const varDef = defs[name]
         if (varDef == null) fail(`${source}: unknown var '${name}' on workflow '${wf.spec.id ?? '?'}' (has: ${wf.entries().map(([n, d]) => `${n}:${d.kind}`).join(', ')})`)
@@ -167,7 +198,7 @@ export async function generateComfyTs(
     // names no kind. It is what the tune button edits
     const draftId = args.draftId ?? args.assetId
     ensureAssetDraft(lw, draftId, args.prompt)
-    const defs = varsOf(lw.wf)
+    const defs = lw.wf.vars
     // modules are import-cached: a previous asset's values must not leak
     for (const [, varDef] of lw.wf.entries()) varDef.reset()
     if (args.vars != null) applyVarValues(lw.wf, args.vars, `asset '${args.assetId}' kit vars`)
@@ -192,7 +223,7 @@ export async function generateComfyTs(
     defs.seed!.parse(`= ${args.seed}`)
     mkdirSync(args.destDir, { recursive: true })
     const healHint = rt.heal != null ? ` — is the backend up? (${rt.heal})` : ''
-    let execution: ComfyExecution
+    let execution: CflowExecution
     try {
         execution = await lw.wf.run({
             onProgress: args.onProgress == null ? undefined : (p) => args.onProgress!({ value: Math.round(p.percent), max: 100, node: p.nodeName }),

package/src/assets/kits/identity-kit.ts

@@ -1,6 +1,7 @@
 // kits/identity — favicon / logo / OG as asset kinds. One render path
 // (renderIdentityFromMark: mark png → logo master 1024², favicon 512², og
-// card), two ways to get the mark:
+// card; a brand's `icon` draws the favicon family at each size instead), two
+// ways to get the mark:
 // - canvas mark: deterministic, instant — `shipkit assets identity` draws it
 //   headlessly and renders the set.
 // - comfy mark: roll-and-pick in the studio; the kind carries a BUILT-IN ship
@@ -28,6 +29,12 @@ export type Brand = {
     /** comfy marks: the FULL generation prompt for identity-logo rolls
      *  (style included — the studio shows/edits exactly this) */
     markPrompt?: string
+    /** the small mark, when the logo does not read at 16 px: favicon.png,
+     *  favicon-32.png, favicon-16.png and apple-touch-icon.png (180², flattened
+     *  on palette.bg) are each drawn at their own size; `asset.id` names the
+     *  file (apple-touch-icon fills its square: iOS rounds it). Absent, the
+     *  favicon is the logo master resized */
+    icon?: CanvasGen
     /** og layout hook — replaces the WHOLE default card (bg + mark left +
      *  name/tagline right); the hook owns compositing the mark if it wants one */
     drawOg?: (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }) => void
@@ -42,6 +49,8 @@ export const FAVICON_SIZE = 512
 export const OG_W = 1200
 export const OG_H = 630
 export const LOGO_SIZE = 1024
+/** what a brand's `icon` draws, each at its own size */
+export const ICON_FILES = [['favicon', FAVICON_SIZE], ['favicon-32', 32], ['favicon-16', 16], ['apple-touch-icon', 180]] as const
 
 /** the one next step when a comfy mark has no picked roll yet */
 export const NO_PICK_FIX = 'roll + pick in the studio: bun run hub → /assets/#identity-logo'
@@ -110,13 +119,23 @@ export async function renderIdentityFromMark(brand: Brand, root: string, markPng
         .resize(LOGO_SIZE, LOGO_SIZE, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
         .png().toBuffer()
     await write('logo.png', logoPng)
-    // favicon = logo master resized to 512² (browsers derive the rest)
-    await write('favicon.png', await sharp(logoPng).resize(FAVICON_SIZE, FAVICON_SIZE).png().toBuffer())
+    if (brand.icon != null) {
+        for (const [id, px] of ICON_FILES) {
+            const c = createCanvas(px, px)
+            await brand.icon.draw(c.getContext('2d'), { id, prompt: '' })
+            const png = sharp(c.toBuffer('image/png'))
+            await write(`${id}.png`, await (id === 'apple-touch-icon' ? png.flatten({ background: brand.palette.bg }) : png).png().toBuffer())
+        }
+    } else {
+        // favicon = logo master resized to 512² (browsers derive the rest)
+        await write('favicon.png', await sharp(logoPng).resize(FAVICON_SIZE, FAVICON_SIZE).png().toBuffer())
+    }
     const og = createCanvas(OG_W, OG_H)
     const ctx = og.getContext('2d')
     if (brand.drawOg != null) brand.drawOg(ctx, brand, { w: OG_W, h: OG_H })
     else defaultOg(ctx, brand, { w: OG_W, h: OG_H }, await loadImage(logoPng))
-    await write('og.png', og.toBuffer('image/png'))
+    // a link preview is small: a 256 colour palette is invisible there and cuts a photo card about 3x (some chat apps drop a preview past ~300 KB)
+    await write('og.png', await sharp(og.toBuffer('image/png')).png({ palette: true, quality: 90, effort: 10, compressionLevel: 9 }).toBuffer())
     return out
 }
 

package/src/cli/cmd_Review.ts

@@ -436,6 +436,14 @@ export class ReviewInboxCommand extends Command {
                 if (t) printed.add(t.head.item.id)
                 h.out(`${t ? threadDetail(t, h.dir, false, h.say) : detail(x, h.dir, false, false, h.say)}\n`)
             }
+            // a « fix » or a « no » an agent read and has not done: owed, never an unseen answer again
+            const owed = threads.filter((t) => of(t.head) && !printed.has(t.head.item.id) && t.head.item.origin.by === 'agent' && verdictOf(t.head)?.seen === true && stateOf(t.head, false).state === 'claimed')
+            const owedLine = (x: (typeof all.items)[number]): string => {
+                const fix = verdictOf(x)?.status === 'approved-with-fix'
+                const close = fix ? `sk review done ${x.item.id} "<what changed>"` : `--supersedes ${x.item.id} on its new version`
+                return `  ${x.item.id} ${fix ? 'ok with a fix' : 'rejected'} "${x.item.title}": ${close}, or sk review wontfix ${x.item.id} --note "<why>"`
+            }
+            if (owed.length > 0) h.out(`owed, read and not done:\n${owed.map((t) => owedLine(t.head)).join('\n')}\n`)
             const watchers = liveWatchers(h.dir)
             const untaken = all.items.flatMap((x) => {
                 const why = untakenOf(x, followed.has(x.item.id), watchers, new Date(), h.say.spec.dispatcher)

package/src/collections/review.ts

@@ -4,12 +4,27 @@
 // Each collection exists only where the repo has its folder, so a repo with none draws the section greyed
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { STATUS_LABEL, isFrame, stateOf } from '../review/model.ts'
-import { readAllCached, storeDir } from '../review/store.ts'
-import { statusOf, waitingOnOwner } from '../review/threads.ts'
+import { STATUS_LABEL, isFrame, stateOf, type ReviewItem } from '../review/model.ts'
+import { readAllCached, storeDir, storeStamp } from '../review/store.ts'
+import { statusOf, waitingOnOwner, type Thread } from '../review/threads.ts'
 import { cutsOf, trailerIds } from '../review/trailer-desk.ts'
 import { REVIEW_COL, TRAILER_COL, type Collection, type Instance } from './collection-types.ts'
 
+const waiting = new Map<string, { stamp: string; threads: Thread[]; items: ReviewItem[] }>()
+
+/** what waits on the owner in a repo, the ONE count every surface shows (the tree's review row, the project list's pill,
+ *  `sk needs`): read again only when the store's stamp moved */
+export function waitingCards(root: string): { threads: Thread[]; items: ReviewItem[] } {
+    const dir = storeDir(root)
+    const stamp = storeStamp(dir)
+    const kept = waiting.get(dir)
+    if (kept?.stamp === stamp) return kept
+    const items = stamp === 'none' ? [] : readAllCached(dir).items
+    const fresh = { stamp, threads: waitingOnOwner(items), items }
+    waiting.set(dir, fresh)
+    return fresh
+}
+
 export function reviewCollection(root: string): Collection | null {
     const dir = storeDir(root)
     if (!existsSync(dir)) return null
@@ -19,8 +34,8 @@ export function reviewCollection(root: string): Collection | null {
         kind: 'card',
         media: 'image',
         list: async () => {
-            const { items } = readAllCached(dir)
-            return waitingOnOwner(items).map(({ head: x }): Instance => ({
+            const { threads, items } = waitingCards(root)
+            return threads.map(({ head: x }): Instance => ({
                 id: `card:${x.item.id}`,
                 text: `${x.item.title} (${STATUS_LABEL[statusOf(x, items)]})`,
                 label: x.item.title,

package/src/fleet/scan-fleet.ts

@@ -13,6 +13,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { isArchived } from '../core/archived.ts'
+import { isLinkedWorktree } from '../core/git-root.ts'
 import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
 import { isBreaking, isLinkedInstall, pinFloor } from '../core/update-policy.ts'
 
@@ -97,7 +98,9 @@ export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[
             continue
         }
         const pkg = readPkg(dir)
-        if (pkg == null || isArchived(dir)) continue
+        // a linked worktree is its main checkout again: an update dirties a
+        // tree that only follows main and blocks that tree's own updater
+        if (pkg == null || isArchived(dir) || isLinkedWorktree(dir)) continue
         const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
         const names = Object.keys(all).filter((n) => n.startsWith(prefix))
         if (names.length === 0) continue

package/src/review/model.ts

@@ -444,12 +444,12 @@ export function stateOf(x: ReviewItem, superseded: boolean): ItemState {
     let s: ItemState = startOf(i)
     // what his latest verdict left: a released or superseded rework of an agent's card goes back to it
     let given: ItemState = s
-    const read = readBy(x, 'agent')
     for (const m of x.thread) {
         const keep = s.topic ? { topic: s.topic } : {}
         if (m.verdict !== undefined) {
             const v = m.verdict
-            if (v === 'approved' || v === 'archived' || read.has(m.id)) s = { ...keep, state: 'closed', why: v }
+            // « fix » and « no » owe the lane work: reading the verdict is never doing it (done, wontfix or a new version closes it)
+            if (v === 'approved' || v === 'archived') s = { ...keep, state: 'closed', why: v }
             else s = { ...keep, state: 'claimed', ...(lane ? { worker: lane } : {}) }
             given = s
             continue
@@ -502,8 +502,9 @@ export function stateOf(x: ReviewItem, superseded: boolean): ItemState {
                 break
         }
     }
-    // the card that redoes it landed: the rework is over
-    if (superseded && i.origin.by === 'agent' && s.since !== undefined) return given
+    // the card that redoes it landed: the work its verdict owed is over
+    const owed = verdictOf(x)?.status
+    if (superseded && i.origin.by === 'agent' && s.state === 'claimed' && owed !== undefined) return { ...(s.topic ? { topic: s.topic } : {}), state: 'closed', why: owed }
     if (verdictOf(x) === null) {
         if (withdrawnOf(x) !== undefined) return { state: 'closed', why: 'withdrawn' }
         if (superseded && s.state !== 'closed') return { ...(s.topic ? { topic: s.topic } : {}), state: 'closed', why: 'superseded' }
@@ -612,6 +613,8 @@ export function untakenOf(x: ReviewItem, superseded: boolean, watchers: readonly
     if (s.state === 'open') return `raised${s.topic ? ` on ${s.topic}` : ''}, nobody claimed it`
     if (s.state !== 'claimed') return null
     if (s.since !== undefined) return quiet > STALE_CLAIM_MS ? `${s.worker ?? 'its'} claim went stale` : null
+    // an agent read the verdict: the work it owes is taken, only not done yet
+    if (verdictOf(x)?.seen) return null
     return listenersOf([x], watchers).length === 0 ? `the owner's verdict went back to ${s.worker ?? 'its author'}, and no watch reads it` : null
 }
 

package/src/review/threads.ts

@@ -124,8 +124,9 @@ export const isFollowed = (id: string, items: readonly ReviewItem[]): boolean =>
 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 */
+/** a thread still needs someone: its head pending, or answered with work owed (« fix » until `done` or a new version,
+ *  « no » until a new version or `wontfix`; reading the verdict is never doing it; 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
@@ -133,7 +134,7 @@ export function isActive(t: Thread, now = new Date()): boolean {
     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
+    return stateOf(t.head, false).state !== 'closed'
 }
 
 /** the thread's conversation: every version's and every answered item's replies, oldest first, each with the item it

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

@@ -36,6 +36,9 @@ export const PLACE_PATH = { overview: '/', planned: '/planned', activity: '/acti
 /** where a repo's hub answers on the home */
 export const repoBase = (name: string): string => `/r/${encodeURIComponent(name)}`
 /** the page of a repo on the home */
+/** the review list's address on the cards whose move is the owner's */
+const WAITING = 'whose=owner'
+
 export const repoPage = (name: string): string => `${repoBase(name)}/`
 
 /** where a check's own page answers on the home */
@@ -112,6 +115,7 @@ export class HomeSt {
         const m = this.machine
         if (m != null) {
             this.projects.onSelect = (name) => this.select(name)
+            this.projects.onReview = (name, card) => this.openReview(name, card)
             this.projects.onPlace = (p) => this.navigate(PLACE_PATH[p])
             this.projects.onPicker = () => this.palette.toggle()
             this.projects.pickerOpen = () => this.palette.open
@@ -121,6 +125,10 @@ export class HomeSt {
         } else {
             this.projects.onSelect = (name) => void this.openInHome(name)
             const own = this.repo('')
+            this.projects.onReview = (name, card) => {
+                if (this.projects.list.some((p) => p.name === name && p.current)) own.showReview(card, WAITING)
+                else void this.openInHome(name, `#${hashFor({ t: 'review', id: card, q: WAITING })}`)
+            }
             own.markSeen()
             this.selected = own.key
         }
@@ -212,6 +220,13 @@ export class HomeSt {
         this.show('repo', repo, 'push')
     }
 
+    /** the cards that wait on the owner in a repo: its review page in place, on the
+     *  first one, the list on the owner's move */
+    openReview(repo: string, card: string | null): void {
+        this.repo(repo).showReview(card, WAITING)
+        this.show('repo', repo, 'push')
+    }
+
     /** a link to a page of the home: the same page, in place */
     navigate(path: string): void {
         const u = new URL(path, 'http://home.invalid')
@@ -303,9 +318,9 @@ export class HomeSt {
 
     /** a list click on a hub serving on its own: that repo's page on the
      *  home when one serves, else the folder in VS Code */
-    async openInHome(name: string): Promise<void> {
+    async openInHome(name: string, hash = ''): Promise<void> {
         const home = await fetch('/api/home-url').then((r) => r.json() as Promise<{ port: number; up: boolean }>).catch(() => null)
         if (home?.up !== true) return this.projects.open(name)
-        window.location.href = `${window.location.protocol}//${window.location.hostname}:${home.port}${repoPage(name)}`
+        window.location.href = `${window.location.protocol}//${window.location.hostname}:${home.port}${repoPage(name)}${hash}`
     }
 }

package/src/serve/hub-app/hub-app.tsx

@@ -304,7 +304,7 @@ const App = observer(() => {
     const dockRef = usePanelRef()
     const listRef = usePanelRef()
     // ⌘B folds the list to its rail and back; a drag that already did it finds it there
-    const rail = l.listRail
+    const rail = l.folded
     const railW = l.railPx
     useLayoutEffect(() => {
         const p = listRef.current

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

@@ -6,7 +6,7 @@
 // value can hand the page a list wider than LIST.max. The list also folds to
 // its icon rail: a drag below its min or ⌘B, kept per browser too, its icons
 // small, medium or large (RAIL_ICONS), the rail as wide as they need.
-import { makeAutoObservable } from 'mobx'
+import { makeAutoObservable, runInAction } from 'mobx'
 
 export type Bounds = { key: string; min: number; max: number; def: number }
 
@@ -62,16 +62,31 @@ function loadRail(): boolean {
     }
 }
 
+/** a page narrower than this draws the list as its rail, whatever the pick: a list squeezed under its min hides its pills */
+export const NARROW_PX = 768
+
 export class LayoutSt {
     listWidth = loadWidth(LIST)
-    /** the list shows its icons only */
+    /** the owner's pick: the list shows its icons only */
     listRail = loadRail()
+    /** the page is narrower than NARROW_PX, read live */
+    narrow = false
     /** the rail's icon size */
     railIcon: RailIcon = loadRailIcon()
     sidebarWidth = loadWidth(SIDEBAR)
 
     constructor() {
         makeAutoObservable(this)
+        if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+            const mq = window.matchMedia(`(max-width: ${NARROW_PX - 1}px)`)
+            this.narrow = mq.matches
+            mq.addEventListener('change', (e) => runInAction(() => (this.narrow = e.matches)))
+        }
+    }
+
+    /** the list as drawn: the rail when he picked it or the page is narrow */
+    get folded(): boolean {
+        return this.listRail || this.narrow
     }
 
     /** a drag of the list's separator ended at this width */

package/src/serve/hub-app/project-list.css

@@ -74,9 +74,11 @@
 /* ⌘1 to ⌘9 select the first nine rows (keys.ts): the hint sits at the row's end */
 .pjkey{flex:none;font:10px/1 ui-monospace,Menlo,monospace;color:var(--dim);opacity:.6;background:none;border:0;padding:0}
 .pjrow:hover .pjkey,.pjrow.cur .pjkey,.pjpl:hover .pjkey,.pjpl.cur .pjkey{opacity:1}
-/* the one badge: open asks, at the end of the row */
-.pga{flex:none;min-width:16px;height:16px;padding:0 var(--s1);border-radius:8px;
+/* what waits on the owner, at the end of the row: the review cards (a click opens them), then the open asks */
+.pga,.pgr{flex:none;min-width:16px;height:16px;padding:0 var(--s1);border-radius:8px;
  font-size:10px;font-weight:700;line-height:16px;text-align:center;color:var(--bg);background:var(--warn)}
+.pgr{background:var(--review);cursor:pointer}
+.pgr:hover{box-shadow:0 0 0 2px var(--review)}
 /* Claude sessions running: a thin edge on the left that breathes */
 .pgs{position:absolute;left:0;top:5px;bottom:5px;width:2px;border-radius:1px;background:var(--accent);pointer-events:none;animation:pgpulse 2.4s ease-in-out infinite}
 /* the home only: the repo's hub state (starting, crashed) */
@@ -102,6 +104,7 @@
 /* NEEDS YOU: a warn toned bullet, set apart from the facts */
 .pgcneeds{margin-top:var(--s2);padding:var(--s1) var(--s2);border-left:2px solid var(--warn);background:var(--panel2);border-radius:0 3px 3px 0}
 .pgcneed{display:flex;gap:var(--s1);min-width:0;color:var(--warn)}
+.pgcneed.rev{color:var(--review)}
 .pgcneed.red{color:var(--red);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .pgcask{flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .pgcmore{flex:none}
@@ -134,7 +137,9 @@
 /* the app icon is a rounded plate already (core/app-icon.ts) */
 .pjlist.rail .pjrow img.pjapp{border-radius:0}
 .pjsize{font:600 10px/1 ui-monospace,Menlo,monospace}
-.pjlist.rail .pga{position:absolute;top:0;right:calc(50% - var(--ri,24px) / 2 - 4px);min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
+.pjlist.rail .pga,.pjlist.rail .pgr{position:absolute;top:0;min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
+.pjlist.rail .pga{right:calc(50% - var(--ri,24px) / 2 - 4px)}
+.pjlist.rail .pgr{left:calc(50% - var(--ri,24px) / 2 - 4px)}
 .pjlist.rail .pgd,.pjlist.rail .pgw{position:absolute;bottom:var(--s0);right:calc(50% - var(--ri,24px) / 2 - 2px)}
 .pjlist.rail .pjfoot{flex-direction:column;height:auto;padding:var(--s1) 0}
 .pjlist.rail .pjfoot button{justify-content:center;width:28px;padding:0}

package/src/serve/hub-app/project-list.tsx

@@ -2,7 +2,8 @@
 // down the left of the page, a small icon and the repo's name on one line,
 // the shown repo's row marked in its identity colour. Its width is the
 // panel the page gives it (hub-app.tsx, react-resizable-panels). A row says
-// three things and no more (faceOf): the open asks as its one badge, a dim
+// three things and no more (faceOf): what waits on the owner as pills (the review
+// cards, a click away from them, then the open asks), a dim
 // name (never the icon) while VS Code does not have the folder open, a thin edge breathing
 // while Claude sessions run in it; on the home, a dot while its hub starts
 // or crashed and a mark while a global process it uses is off. Everything
@@ -15,8 +16,8 @@
 // (names only, no ⌘ number, a row opens the archived page, nothing loads),
 // the foot never moving. ⌘B (or the foot's fold button, or a drag of the
 // separator below the list's min) folds the list to its icon rail: the
-// names, the ⌘ hints and the step hint hide, the badge rides the icon's
-// corner, the hover card still names the row. On the home a section of four lines on top, in the
+// names, the ⌘ hints and the step hint hide, the pills ride the icon's
+// corners, the hover card still names the row; a phone width is always the rail. On the home a section of four lines on top, in the
 // repo rows' style, opens the picker, the overview, the activity and the
 // plan, each with its shortcut at the line's end, the page shown lit. It
 // renders from the first paint with the list this browser kept, so a load
@@ -34,7 +35,7 @@ import { RAIL_ICONS, type RailIcon } from './layout-st.ts'
 
 /** what the list needs of its page: the hub and the home both carry one;
  *  the layout, when the page can fold the list to its rail */
-export type ListHost = { projects: ProjectsSvc; layout?: { listRail: boolean; toggleRail(): void; railIcon: RailIcon; cycleRailIcon(): void }; theme?: { pick: ThemePick; cycle(): void } }
+export type ListHost = { projects: ProjectsSvc; layout?: { folded: boolean; toggleRail(): void; railIcon: RailIcon; cycleRailIcon(): void }; theme?: { pick: ThemePick; cycle(): void } }
 
 /** the lines on top of the list, in their order: the picker, the overview,
  *  then the places, each with its shortcut (keys.ts) */
@@ -96,10 +97,14 @@ export const Row = observer(({ app, p, i }: { app: ListHost; p: Project; i: numb
                     },
                     onDragEnd: () => s.dragEnd(),
                 })}>
-                {app.layout?.listRail === true && p.appIcon != null
+                {app.layout?.folded === true && p.appIcon != null
                     ? <img className="pjapp" src={p.appIcon} alt="" width={ROW_ICON} height={ROW_ICON} draggable={false} />
                     : <Face p={p} px={ROW_ICON} />}
                 <span className="pjname">{p.name}</span>
+                {face.cards != null ? (
+                    <b className="pgr" aria-label={`${face.cards} review card${face.cards === 1 ? '' : 's'} wait on you: open them`}
+                        onClick={(e) => { e.stopPropagation(); s.review(p.name) }} onDoubleClick={(e) => e.stopPropagation()}>{face.cards}</b>
+                ) : null}
                 {face.badge != null ? <b className="pga">{face.badge}</b> : null}
                 {face.busy ? <i className="pgs" /> : null}
                 {dot != null ? <i className={`pgd ${dot}`} /> : null}
@@ -138,6 +143,12 @@ export const Card = ({ p, now }: { p: Project; now: number }) => {
             {m.head.description == null ? null : <div className="pgcdesc">{m.head.description}</div>}
             {m.needs == null ? null : (
                 <div className="pgcneeds">
+                    {m.needs.cards == null ? null : (
+                        <div className="pgcneed rev">
+                            <span className="pgcask">{m.needs.cards.count} card{m.needs.cards.count === 1 ? '' : 's'} to review: {m.needs.cards.titles.join(' · ')}</span>
+                            {m.needs.cards.more > 0 ? <span className="pgcmore">+{m.needs.cards.more}</span> : null}
+                        </div>
+                    )}
                     {m.needs.asks == null ? null : (
                         <div className="pgcneed">
                             <span className="pgcask">{m.needs.asks.count} ask{m.needs.asks.count === 1 ? '' : 's'}: {m.needs.asks.titles.join(' · ')}</span>
@@ -165,7 +176,7 @@ export const ProjectList = observer(({ app }: { app: ListHost }) => {
     useEffect(() => app.projects.start(), [app])
     const s = app.projects
     const lay = app.layout
-    const rail = lay?.listRail === true
+    const rail = lay?.folded === true
     return (
         <nav className={`pjlist${rail ? ' rail' : ''}`} aria-label="projects" style={rail ? ({ '--ri': `${RAIL_ICONS[lay!.railIcon]}px` } as CSSProperties) : undefined}>
             {s.onPlace == null && s.onPicker == null && s.error === '' ? null : (

package/src/serve/hub-app/projects-svc.ts

@@ -62,7 +62,8 @@ const keptSort = (): SortMode | null => {
 export function loadList(): Project[] {
     try {
         const v = JSON.parse(globalThis.localStorage?.getItem(LIST_KEY) ?? '[]') as unknown
-        return Array.isArray(v) && v.every((p) => typeof (p as Project)?.name === 'string') ? (v as Project[]) : []
+        // a list kept before a row carried its cards reads as none waiting until the first poll
+        return Array.isArray(v) && v.every((p) => typeof (p as Project)?.name === 'string') ? (v as Project[]).map((p) => ({ ...p, cards: p.cards ?? [] })) : []
     } catch {
         return []
     }
@@ -133,12 +134,13 @@ export function sortNames(list: Project[], mode: SortMode): string[] {
  *  its hub starts or crashed. A hub that is up is the normal case and draws none */
 export type HubDot = 'starting' | 'crashed' | null
 
-/** what the icon face shows, and nothing more: at most ONE badge (the open
- *  asks, the only fact that needs a human's hands), a dim name while VS Code
- *  does not have the folder open (the icon stays whole), and a pulsing edge
- *  while Claude sessions run */
-export type Face = { badge: number | null; dim: boolean; busy: boolean }
+/** what the icon face shows, and nothing more: what waits on the owner as
+ *  two pills (the review cards waiting on a verdict, the open asks waiting
+ *  on hands), a dim name while VS Code does not have the folder open (the
+ *  icon stays whole), and a pulsing edge while Claude sessions run */
+export type Face = { cards: number | null; badge: number | null; dim: boolean; busy: boolean }
 export const faceOf = (p: Project): Face => ({
+    cards: p.cards.length > 0 ? p.cards.length : null,
     badge: p.asks > 0 ? p.asks : null,
     dim: p.vscode === false,
     busy: p.sessions != null && p.sessions > 0,
@@ -149,7 +151,7 @@ export const faceOf = (p: Project): Face => ({
  *  human, and label and value rows. Each part leaves out an unknown fact */
 export type CardModel = {
     head: { name: string; current: boolean; icon: string | null; version: string | null; branch: string | null; description: string | null }
-    needs: { asks: { count: number; titles: string[]; more: number } | null; gate: string | null } | null
+    needs: { cards: { count: number; titles: string[]; more: number } | null; asks: { count: number; titles: string[]; more: number } | null; gate: string | null } | null
     facts: { k: 'release' | 'live' | 'activity'; v: string; tone?: 'warn' }[]
 }
 
@@ -159,6 +161,8 @@ export const CARD_NAMES = 3
 export function cardModel(p: Project, now: number): CardModel {
     const branch = p.branch == null ? null : p.dirty != null && p.dirty > 0 ? `${p.branch} · ${p.dirty} uncommitted` : p.branch
     const asks = p.asks > 0 ? { count: p.asks, titles: p.askTitles.slice(0, CARD_NAMES), more: Math.max(0, p.asks - CARD_NAMES) } : null
+    const n = p.cards.length
+    const cards = n > 0 ? { count: n, titles: p.cards.slice(0, CARD_NAMES).map((c) => c.title), more: Math.max(0, n - CARD_NAMES) } : null
     const reds = p.gate != null && p.gate !== 'green' ? p.gate.reds : []
     const gate = reds.length === 0 ? null : `gate red: ${reds.slice(0, CARD_NAMES).join(', ')}${reds.length > CARD_NAMES ? ` +${reds.length - CARD_NAMES}` : ''}`
     const facts: CardModel['facts'] = []
@@ -177,7 +181,7 @@ export function cardModel(p: Project, now: number): CardModel {
     if (act.length > 0) facts.push({ k: 'activity', v: act.join(' · ') })
     return {
         head: { name: p.name, current: p.current, icon: p.icon, version: p.version, branch, description: p.description },
-        needs: asks == null && gate == null ? null : { asks, gate },
+        needs: cards == null && asks == null && gate == null ? null : { cards, asks, gate },
         facts,
     }
 }
@@ -216,6 +220,9 @@ export class ProjectsSvc {
     /** what a single click does: the home shows that repo in place, a hub
      *  of its own opens the home on it. Default: the folder in VS Code */
     onSelect: (name: string) => void = (name) => void this.open(name)
+    /** a click on a row's review pill: that repo's review page on its first
+     *  waiting card. The home and a hub of its own each set it */
+    onReview: (name: string, card: string | null) => void = (name) => this.select(name)
     /** the two places at the top of the list, the overview and the plan:
      *  the home sets it, a hub of its own has none */
     onPlace: ((p: Place) => void) | null = null
@@ -281,6 +288,12 @@ export class ProjectsSvc {
         this.onSelect(name)
     }
 
+    /** the review pill: the cards that wait on the owner in that repo */
+    review(name: string): void {
+        this.selected = name
+        this.onReview(name, this.list.find((p) => p.name === name)?.cards[0]?.id ?? null)
+    }
+
 
     /** the repo above (-1) or below (+1) the selected one, round the ends;
      *  with none selected, down starts at the top and up at the bottom */

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

@@ -28,7 +28,7 @@ import {
     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 { answererOf, chainOf, childrenOf, conversationOf, followedIds, isActive, membersOf, orderedThreads, statusOf, threadOfItem, waitingOnOwner, 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'
@@ -450,9 +450,9 @@ export class ReviewSt {
         return orderedThreads(this.items)
     }
 
-    /** what waits on him: the cards waiting for the owner's verdict, and what he raised that asks him */
+    /** what waits on the owner, the one count of every surface (collections/review.ts waitingCards) */
     get pendingCount(): number {
-        return this.threads.filter((t) => waits(t.head) || (t.head.item.origin.by !== 'agent' && this.moveOf(t.head) === 'owner')).length
+        return waitingOnOwner(this.items).length
     }
 
     get activeCount(): number {
@@ -908,8 +908,9 @@ export class ReviewSt {
                 store.put(`${this.prefix}draft.${id}`, null)
             })
             void this.refresh()
-            // the tree's count of what waits on him moves at once
+            // the tree's count of what waits on the owner moves at once, and so does the project list's pill
             void this.st.cols.poll(true)
+            void this.st.home.projects.load()
         } catch (e) {
             runInAction(() => (this.error = (e as Error).message))
         } finally {

package/src/serve/project-gutter-route.ts

@@ -23,11 +23,21 @@ import { readLastStatusReadonly } from '../ledger/run-log.ts'
 import { identityOfText, identityProblem, type Identity } from '../core/identity-color.ts'
 import { writeIdentity } from '../core/identity.ts'
 import { appIconOf, appIconPngs, identityOfRoot } from '../core/app-icon.ts'
+import { waitingCards } from '../collections/review.ts'
 import { writeArchived } from '../core/archived.ts'
 
 export type { Gate }
 
 export const POLL_MS = 5_000
+
+/** a repo's waiting cards as its row carries them; a store that cannot be read waits on nobody, and its hub says why */
+function cardsOf(path: string): ProjectRow['cards'] {
+    try {
+        return waitingCards(path).threads.map((t) => ({ id: t.head.item.id, title: t.head.item.title }))
+    } catch {
+        return []
+    }
+}
 /** the app icon preview: sharp on a 2x screen at the admin page's 128px */
 const PREVIEW_PX = 256
 /** the rail's app icon, cropped to the plate: 40px at 2x, the largest rail size */
@@ -59,6 +69,8 @@ export type ProjectRow = {
     asks: number
     /** their titles, in file order */
     askTitles: string[]
+    /** the review cards that wait on the owner (collections/review.ts waitingCards), oldest first: read on every request */
+    cards: { id: string; title: string }[]
     /** package.json `description`, else the README's first line of prose */
     description: string | null
     /** package.json `version` */
@@ -338,6 +350,7 @@ export function projectGutter(d: GutterDeps) {
                 sessions: counts?.get(r.path) ?? null,
                 asks: asks.length,
                 askTitles: asks,
+                cards: cardsOf(r.path),
                 description,
                 version: versionOf(pkg),
                 branch: branchOf(readText(join(r.path, '.git', 'HEAD'))),
@@ -386,7 +399,11 @@ export function projectGutter(d: GutterDeps) {
 
     /** null when the path is not this route's */
     async function handle(req: Request, path: string): Promise<Response | null> {
-        if (path === '/api/projects.json') return Response.json(await answer())
+        if (path === '/api/projects.json') {
+            // the measure holds 5 s, the cards never: a verdict he just gave shows on the next ask
+            const a = await answer()
+            return Response.json({ ...a, projects: a.projects.map((p) => ({ ...p, cards: cardsOf(p.path) })) })
+        }
         if (path.startsWith('/api/projects/icon/')) {
             if (repos.length === 0) await answer()
             const r = findAny(decodeURIComponent(path.slice('/api/projects/icon/'.length)))

package/src/shot/clip-encoder.ts

@@ -8,7 +8,8 @@
 // `CLIP_INIT` run IN the page, so they import nothing and read only their
 // argument and the document. A WebGL canvas keeps no drawing buffer after it
 // presents, so the clip's page is opened with CLIP_INIT, which asks every
-// WebGL context for `preserveDrawingBuffer`.
+// WebGL context for `preserveDrawingBuffer`; a WebGPU canvas read on a frame
+// it did not draw gives an older drawing, so it is read only after a draw.
 
 /** what the page films: seconds of its largest canvas at fps, H.264 at a fixed quantizer */
 export type PageClipAsk = { seconds: number; fps: number; quantizer: number; keyEvery: number }
@@ -16,13 +17,22 @@ export type PageClipAsk = { seconds: number; fps: number; quantizer: number; key
 /** what the page says once the film ran */
 export type PageClipDone = { frames: number; repeated: number; width: number; height: number; canvasOfViewport: string }
 
-/** IN THE PAGE, as an init script: every WebGL context keeps its drawing buffer, so a frame reads back after it presents */
+/** IN THE PAGE, as an init script: every WebGL context keeps its drawing buffer, so a frame reads back after it presents;
+ *  a WebGPU canvas counts its drawings (window.__skDraws): read on a frame it did not draw, it gives an older drawing */
 export const CLIP_INIT = `(() => {
     const get = HTMLCanvasElement.prototype.getContext
     HTMLCanvasElement.prototype.getContext = function (type, attrs) {
         if (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl') attrs = Object.assign({}, attrs, { preserveDrawingBuffer: true })
+        if (type === 'webgpu') window.__skDraws ??= 0
         return get.call(this, type, attrs)
     }
+    if (typeof GPUCanvasContext !== 'undefined') {
+        const current = GPUCanvasContext.prototype.getCurrentTexture
+        GPUCanvasContext.prototype.getCurrentTexture = function () {
+            window.__skDraws = (window.__skDraws ?? 0) + 1
+            return current.call(this)
+        }
+    }
 })()`
 
 type ClipState = {
@@ -70,25 +80,37 @@ export async function installClip(a: PageClipAsk): Promise<string | null> {
     const total = Math.round(a.seconds * a.fps)
     const step = 1000 / a.fps
     const rect = { x: 0, y: 0, width, height }
+    // a WebGPU canvas is read only on a frame it drew (CLIP_INIT counts them), else its last drawing is filmed again
+    const gpu = w as unknown as { __skDraws?: number }
     st.done = new Promise<PageClipDone>((ok, fail) => {
         let n = 0
         let repeated = 0
         let t0 = -1
+        let last: VideoFrame | null = null
+        let seen = -1
         const tick = (t: number): void => {
             try {
                 if (st.failed) throw new Error(st.failed)
                 if (t0 < 0) t0 = t
+                const draws = gpu.__skDraws
+                const fresh = last == null || draws === undefined || draws !== seen
+                if (fresh) {
+                    last?.close()
+                    last = new VideoFrame(canvas, { timestamp: 0, visibleRect: rect })
+                    seen = draws ?? -1
+                }
                 // a frame for every step of real time passed: a slow page repeats its last drawing, so the clip keeps its length
                 let made = 0
                 while (n < total && n * step <= t - t0) {
-                    const frame = new VideoFrame(canvas, { timestamp: Math.round(n * step * 1000), duration: Math.round(step * 1000), visibleRect: rect })
+                    const frame = new VideoFrame(last!, { timestamp: Math.round(n * step * 1000), duration: Math.round(step * 1000) })
                     enc.encode(frame, { keyFrame: n % a.keyEvery === 0, avc: { quantizer: a.quantizer } } as VideoEncoderEncodeOptions)
                     frame.close()
-                    if (made++ > 0) repeated++
+                    if (made++ > 0 || !fresh) repeated++
                     n++
                 }
                 if (n < total) requestAnimationFrame(tick)
-                else
+                else {
+                    last?.close()
                     void enc
                         .flush()
                         .then(() => {
@@ -97,7 +119,9 @@ export async function installClip(a: PageClipAsk): Promise<string | null> {
                             ok({ frames: n, repeated, width, height, canvasOfViewport })
                         })
                         .catch(fail)
+                }
             } catch (e) {
+                last?.close()
                 if (enc.state !== 'closed') enc.close()
                 fail(e)
             }

package/src/trailer/score/synth.ts

@@ -253,15 +253,21 @@ function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, t
     }
 }
 
-/** a noise buffer looped at a moving playback rate, added into `buf` */
-function noiseRun(buf: Float32Array, n: number, t0: number, rate: number, src: Float32Array, p: Pitch): void {
+/** a noise buffer looped at a moving playback rate, added into `buf`. A browser buffer source's playbackRate is k-rate:
+ *  held for each 128 frame block at the block's start. In the block the note starts inside (`lead` frames in) it is the
+ *  default 1; the note's events take hold at the next block, so its sweep starts there and still ends at its own time */
+function noiseRun(buf: Float32Array, n: number, t0: number, rate: number, src: Float32Array, p: Pitch, lead: number): void {
+    const first = (QUANTUM - lead) % QUANTUM
+    const sweep: Pitch = { from: p.from, to: p.to, over: p.over - first / rate }
     let pos = 0
+    let inc = 1
     const len = src.length
     for (let i = 0; i < n; i++) {
+        if (i >= first && (i - first) % QUANTUM === 0) inc = pitchAt(sweep, t0 + (i - first) / rate)
         const j = pos | 0
         const v = src[j % len]!
         buf[i] = buf[i]! + v + (src[(j + 1) % len]! - v) * (pos - j)
-        pos += pitchAt(p, t0 + i / rate)
+        pos += inc
         if (pos >= len) pos -= len
     }
 }
@@ -285,18 +291,20 @@ function playNote(bus: Bus, waves: Waves, inst: InstrumentDef, note: ScheduledNo
     if (peak <= 0) return
     const pts = envPoints(inst.env, note.dur, peak)
     const length = (pts[pts.length - 1]?.[0] ?? note.dur) + 0.02
-    const i0 = Math.max(0, Math.ceil(note.time * rate))
-    const i1 = Math.min(bus.l.length, Math.ceil((note.time + length) * rate))
+    // on its sample frame, as the game rounds a note's time: a hair past one (a sum's float noise) is that frame
+    const start = Math.round(note.time * rate)
+    const i0 = Math.max(0, start)
+    const i1 = Math.min(bus.l.length, Math.ceil((start / rate + length) * rate))
     const n = i1 - i0
     if (n <= 0) return
     if (scratch.buf.length < n) scratch.buf = new Float32Array(n)
     const buf = scratch.buf
     buf.fill(0, 0, n)
-    const t0 = i0 / rate - note.time
+    const t0 = (i0 - start) / rate
     if (inst.osc === 'noise') {
         const r0 = Math.max(0.05, Math.min(8, hz / NOISE_REF_HZ))
         const pitch: Pitch = inst.sweep ? { from: r0, to: Math.max(0.02, r0 * 2 ** (inst.sweep.semis / 12)), over: Math.max(1e-4, inst.sweep.time) } : { from: r0, to: r0, over: 0 }
-        noiseRun(buf, n, t0, rate, inst.noise === 'metal' ? waves.metal : waves.white, pitch)
+        noiseRun(buf, n, t0, rate, inst.noise === 'metal' ? waves.metal : waves.white, pitch, i0 % QUANTUM)
     } else {
         const voices = Math.max(1, Math.min(4, inst.unison ?? (inst.detune ? 2 : 1)))
         const spread = inst.detune ?? 0

package/src/trailer/sound/comfy.ts

@@ -12,6 +12,7 @@ export function comfyModule(comfy: string | undefined, name: string): string {
 const COMFY_TIMEOUT_S = 15 * 60
 
 export async function comfyRun(module: string, vars: Record<string, string | number | boolean | undefined>, out: string): Promise<void> {
+    if (Bun.which('comfy-ts') == null) throw new Error(`comfy-ts is not on PATH, and ${module} is a comfy-ts module. Install it: bun add -g comfy-ts`)
     const args = ['comfy-ts', 'run', module]
     for (const [k, v] of Object.entries(vars)) if (v !== undefined) args.push(`--${k}`, String(v))
     args.push('--out', out, '--json')