rvlib-shipkit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.0 — 2026-07-22
+
+New (wave 2 of the shipkit expansion — generation UX):
+
+- live per-step progress: the comfy engine subscribes ComfyUI's native
+  `/ws?clientId=` (same clientId as the `/prompt` body) and streams
+  `executing {node}` + `progress {value,max}` into the studio; ADDITIVE by
+  contract — a dead socket degrades to no-progress, completion truth stays
+  the `/history` poll. (comfy-code evaluated and rejected: opposite graph
+  model, ~87 dl/mo solo dep; native /ws does the job in-doctrine.)
+- studio spinners: every queued/generating asset shows a spinner placeholder
+  (sidebar row, category-grid card, roll strip) driven by the new
+  `pending: string[]` in `/api/state`; header gains a live progress bar
+  (`step v/max`).
+- cancel: `POST /api/interrupt` (studio "stop current") — comfy `/interrupt`
+  on the box (only when the RUNNING job is a comfy kind — the box is shared)
+  + the current job's remaining rolls dropped (logged `ok: cancelled …`,
+  never an error); queued jobs stay (`clear queue` still drops those). New
+  engine wrapper `interrupt()` exported.
+
 ## 0.4.0 — 2026-07-22
 
 New (wave 1 of the shipkit expansion — uniform repo setup):

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "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",
     "type": "module",

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

@@ -34,16 +34,56 @@ export function applyInputs(graph: Graph, sk: Sidekick, args: { prompt: string;
     }
 }
 
-export async function submit(o: ComfyOpts, graph: Graph): Promise<string> {
+export async function submit(o: ComfyOpts, graph: Graph, clientId?: string): Promise<string> {
     const res = await fetch(`${o.host}/prompt`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ prompt: graph, client_id: crypto.randomUUID() }),
+        body: JSON.stringify({ prompt: graph, client_id: clientId ?? crypto.randomUUID() }),
     })
     if (!res.ok) throw new Error(`POST /prompt → ${res.status}: ${(await res.text()).slice(0, 300)} — bad graph or server mid-boot${healHint(o)}`)
     return ((await res.json()) as { prompt_id: string }).prompt_id
 }
 
+// ── live progress over ComfyUI's native /ws ────────────────────────────────
+// ADDITIVE by contract: a dead socket degrades to no-progress, completion
+// truth stays the /history poll. The clientId MUST match the /prompt body
+// or the server sends nothing.
+export type GenProgress = { value: number; max: number; node: string | null }
+export type OnProgress = (p: GenProgress) => void
+
+const wsWarned = new Set<string>() // one WARN per host per process, not per roll
+export function subscribeProgress(o: ComfyOpts, clientId: string, on: OnProgress): { close: () => void } {
+    const url = `${o.host.replace(/^http/, 'ws')}/ws?clientId=${encodeURIComponent(clientId)}`
+    const warnOnce = (detail: string): void => {
+        if (wsWarned.has(o.host)) return
+        wsWarned.add(o.host)
+        console.log(`WARN comfy /ws unavailable — per-step progress disabled${detail}`)
+    }
+    let node: string | null = null
+    let ws: WebSocket | null = null
+    try {
+        ws = new WebSocket(url)
+        ws.onmessage = (ev) => {
+            if (typeof ev.data !== 'string') return // binary preview frames — not consumed
+            let msg: { type?: string; data?: { value?: number; max?: number; node?: string | null } }
+            try { msg = JSON.parse(ev.data) as typeof msg } catch { return }
+            if (msg.type === 'executing') { node = msg.data?.node ?? null; on({ value: 0, max: 0, node }) }
+            else if (msg.type === 'progress') on({ value: msg.data?.value ?? 0, max: msg.data?.max ?? 0, node })
+        }
+        // progress is a bonus — a refused/dropped ws warns once and stays quiet
+        ws.onerror = () => warnOnce('')
+    } catch (e) {
+        warnOnce(` (${(e as Error).message})`)
+    }
+    return { close: () => { try { ws?.close() } catch {} } }
+}
+
+/** Cancel the RUNNING prompt (queued ones are untouched). */
+export async function interrupt(o: ComfyOpts): Promise<void> {
+    const res = await fetch(`${o.host}/interrupt`, { method: 'POST' })
+    if (!res.ok) throw new Error(`POST /interrupt → ${res.status}${healHint(o)}`)
+}
+
 type HistoryOutputs = Record<string, { images?: { filename: string; subfolder?: string; type?: string }[] }>
 
 export async function waitFor(o: ComfyOpts, promptId: string): Promise<HistoryOutputs> {
@@ -76,11 +116,22 @@ async function fetchImage(o: ComfyOpts, img: { filename: string; subfolder?: str
  * bindings applied, submitted, waited, non-preview outputs saved as
  * <destDir>/<name>.<ext> (ONE clean file per asset — no _00001_ counter noise).
  */
-export async function generate(o: ComfyOpts, wf: Workflow, args: { prompt: string; seed: number; destDir: string; name: string }): Promise<string[]> {
+export async function generate(o: ComfyOpts, wf: Workflow, args: { prompt: string; seed: number; destDir: string; name: string; onProgress?: OnProgress }): Promise<string[]> {
     const graph = structuredClone(wf.graph)
     applyInputs(graph, wf.sidekick, { prompt: args.prompt, seed: args.seed, prefix: args.name })
     mkdirSync(args.destDir, { recursive: true })
-    const outputs = await waitFor(o, await submit(o, graph))
+    let outputs: HistoryOutputs
+    if (args.onProgress != null) {
+        const clientId = crypto.randomUUID()
+        const sub = subscribeProgress(o, clientId, args.onProgress)
+        try {
+            outputs = await waitFor(o, await submit(o, graph, clientId))
+        } finally {
+            sub.close()
+        }
+    } else {
+        outputs = await waitFor(o, await submit(o, graph))
+    }
     const saved: string[] = []
     for (const node of Object.values(outputs)) {
         for (const img of node.images ?? []) {

package/src/assets/gen/generate-roll.ts

@@ -7,7 +7,7 @@
 import { mkdirSync } from 'fs'
 import { join } from 'path'
 import type { FoundAsset } from '../kit-config.ts'
-import { generate } from './comfy-gen.ts'
+import { generate, type OnProgress } from './comfy-gen.ts'
 import { loadWorkflows, workflowFor, type Workflow } from './workflow-loader.ts'
 
 /** roll canvas master size (square) — favicon/logo/sprites derive from it */
@@ -20,7 +20,7 @@ export type ComfyResolver = () => Promise<ComfyRuntime>
  *  v<seed>.<ext> (comfy). `resolveComfy` is only awaited for comfy backends. */
 export async function generateRoll(
     found: FoundAsset,
-    args: { prompt: string; seed: number; destDir: string },
+    args: { prompt: string; seed: number; destDir: string; onProgress?: OnProgress },
     resolveComfy: ComfyResolver,
 ): Promise<void> {
     const gen = found.kind.generate
@@ -34,7 +34,7 @@ export async function generateRoll(
     }
     const rt = await resolveComfy()
     const wf = workflowFor(rt.workflows, { workflow: gen.workflow, assetId: found.asset.id })
-    await generate({ host: rt.host, heal: rt.heal }, wf, { prompt: args.prompt, seed: args.seed, destDir: args.destDir, name: `v${args.seed}` })
+    await generate({ host: rt.host, heal: rt.heal }, wf, { prompt: args.prompt, seed: args.seed, destDir: args.destDir, name: `v${args.seed}`, onProgress: args.onProgress })
 }
 
 /** Memoized lazy comfy runtime for a resolved kit — loads the workflow pairs on

package/src/assets/server/studio-page.ts

@@ -42,6 +42,12 @@ button.ghost{background:var(--panel2);color:var(--ink);border:1px solid var(--li
 button:disabled{opacity:.45;cursor:default}
 select,input[type=number]{background:var(--bg);color:var(--ink);border:1px solid var(--line);border-radius:8px;padding:7px}
 .status{font-size:12px;color:var(--dim);min-height:16px}
+.spin{width:12px;height:12px;border:2px solid var(--line);border-top-color:var(--gold);border-radius:50%;animation:rot 1s linear infinite;flex:none}
+@keyframes rot{to{transform:rotate(360deg)}}
+.progbar{width:120px;height:4px;background:var(--panel2);border-radius:2px;overflow:hidden;display:none}
+.progbar i{display:block;height:100%;width:0;background:var(--gold);transition:width .3s}
+.vig.gen{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;color:var(--dim);font-size:11px}
+.card .th .spin{position:absolute;top:8px;right:8px}
 .detnote{font-size:11px;color:var(--teal);line-height:1.25;max-width:150px}
 /* ── per-asset info surface (W2-2) ── */
 .info{display:none;flex-wrap:wrap;gap:6px;align-items:center;padding:6px 16px;border-bottom:1px solid var(--line);background:var(--panel2)}
@@ -140,13 +146,14 @@ kbd{background:var(--panel2);border:1px solid var(--line);border-radius:4px;padd
    <button id=go disabled>Generate</button>
    <div id=detnote class=detnote style="display:none">deterministic — rolls identical</div>
    <button id=qclear class=ghost title="drop queued jobs">clear queue</button>
+   <button id=qcancel class=ghost style="display:none" title="interrupt the current job (queued jobs stay)">stop current</button>
   </div>
   <div class=promptwrap>
     <textarea id=prompt placeholder="select an asset ←"></textarea>
     <div class=jrow><button id=saveprompt class=ghost disabled>save prompt → overlay</button>
      <button id=copyprompt class=ghost>copy</button><span class=jmsg id=promptmsg></span></div>
   </div>
-  <div class=ctl><div class=status id=status></div></div>
+  <div class=ctl><div class=status id=status></div><div class=progbar id=prog><i></i></div></div>
  </div>
  <div class=info id=info></div>
  <div class=stage id=stage><div class=ph>Pick an asset on the left, then Generate.</div>
@@ -184,7 +191,7 @@ kbd{background:var(--panel2);border:1px solid var(--line);border-radius:4px;padd
 </main>
 <script>
 const $=s=>document.querySelector(s)
-let assets=[],cur=null,rolls=[],active=null,tab='asset',openCats=new Set()
+let assets=[],cur=null,rolls=[],active=null,tab='asset',openCats=new Set(),pending=[]
 let customs=[],panelMod=null,panelKey=null // repo-defined editor panels (custom tabs)
 let lastSideSig=null,lastRollSig=null,catMode=null,lastCatSig=null,catRows=[]
 let rect=null,rectRatio=0.6,hasGeom=false,saveTimer=null
@@ -209,7 +216,7 @@ window.addEventListener('hashchange',restoreFromHash)
 function toggleFold(c){openCats.has(c)?openCats.delete(c):openCats.add(c);lastSideSig=null;renderSide(assets)}
 function renderSide(list){
  assets=list;$('#count').textContent=list.length
- const sig=JSON.stringify(list.map(a=>[a.id,a.rolls,a.picked]))+'|'+cur+'|'+catMode+'|'+[...openCats].join(',')
+ const sig=JSON.stringify(list.map(a=>[a.id,a.rolls,a.picked]))+'|'+cur+'|'+catMode+'|'+[...openCats].join(',')+'|'+pending.join(',')
  if(sig===lastSideSig&&$('#list').innerHTML!=='')return; lastSideSig=sig
  const cats=[...new Set(list.map(a=>a.cat))]
  $('#list').innerHTML=cats.map(c=>{
@@ -220,7 +227,7 @@ function renderSide(list){
   if(!open)return head
   return head+list.filter(a=>a.cat===c).map(a=>
    '<div class="arow'+(a.id===cur?' sel':'')+'" data-id="'+esc(a.id)+'" onclick="selectAsset(\\''+jsq(a.id)+'\\')"><div class=lb><b>'+esc(a.label)+
-   '</b><span>'+a.rolls+' rolls</span></div><div class="dot '+(a.picked?'done':(a.rolls?'some':''))+'"></div></div>').join('')
+   '</b><span>'+a.rolls+' rolls</span></div>'+(pending.includes(a.id)?'<div class=spin></div>':'<div class="dot '+(a.picked?'done':(a.rolls?'some':''))+'"></div>')+'</div>').join('')
  }).join('')
 }
 // ── per-asset info surface (W2-2): backend, workflow provenance, ship target,
@@ -274,9 +281,14 @@ async function renderRolls(reset){
  if(!cur)return
  const r=await j('/api/asset?id='+encodeURIComponent(cur))
  rolls=r.rolls
- const sig=cur+'|'+rolls.map(x=>x.name+(x.picked?'*':'')+(x.alt?'~':'')).join(',')
+ const genHere=pending.includes(cur)
+ const sig=cur+'|'+rolls.map(x=>x.name+(x.picked?'*':'')+(x.alt?'~':'')).join(',')+'|'+genHere
  if(!reset&&sig===lastRollSig)return; lastRollSig=sig
  const strip=$('#strip')
+ if(!rolls.length&&genHere){strip.innerHTML='<div class="vig gen"><div class=spin></div>generating…</div>';hideOverlay()
+  const gst=$('#stage');gst.querySelector('img.roll')?.remove()
+  if(!gst.querySelector('.ph')){const ph=document.createElement('div');ph.className='ph';ph.textContent='generating…';gst.appendChild(ph)}
+  active=null;return}
  if(!rolls.length){strip.innerHTML='<div class=ph>no rolls — hit Generate</div>';hideOverlay()
   const st=$('#stage');st.querySelector('img.roll')?.remove()
   if(!st.querySelector('.ph')){const ph=document.createElement('div');ph.className='ph';ph.textContent='no rolls yet';st.appendChild(ph)}
@@ -288,7 +300,8 @@ async function renderRolls(reset){
   '<div class="vig'+(x.name===active?' active':'')+(x.picked?' picked':'')+(x.alt?' alt':'')+'" data-n="'+x.name+'">'+
   '<img src="'+imgUrl(cur,x.name)+'">'+(x.picked?'<span class=st>★</span>':'')+
   '<div class=btns><button class=b-pick>pick</button><button class=b-alt>alt</button><button class=b-del>✕</button></div></div>').join('')
- strip.querySelectorAll('.vig').forEach(v=>{
+  +(genHere?'<div class="vig gen"><div class=spin></div>generating…</div>':'')
+ strip.querySelectorAll('.vig[data-n]').forEach(v=>{
   const n=v.dataset.n
   v.onmouseenter=()=>setStage(imgUrl(cur,n))
   v.onmouseleave=()=>setStage(imgUrl(cur,active))
@@ -311,6 +324,7 @@ async function discard(n){
 async function genCat(c,n){await post('/api/generate-cat',{cat:c,count:n});heartbeat()}
 $('#go').onclick=async()=>{if(!cur)return;await post('/api/generate',{id:cur,prompt:$('#prompt').value,count:+$('#n').value});heartbeat()}
 $('#qclear').onclick=()=>post('/api/queue/clear')
+$('#qcancel').onclick=()=>post('/api/interrupt')
 $('#saveprompt').onclick=async()=>{
  const r=await post('/api/prompt',{id:cur,prompt:$('#prompt').value})
  $('#promptmsg').textContent=r.error?('FAIL: '+r.error):'saved (overlay)'
@@ -470,7 +484,7 @@ async function fillCat(force){
  const r=await j('/api/catrects?cat='+encodeURIComponent(mode))
  if(catMode!==mode)return // user navigated away mid-fetch
  catRows=r.rows||[]
- const sig=JSON.stringify(catRows)
+ const sig=JSON.stringify(catRows)+'|'+pending.join(',')
  if(!force&&sig===lastCatSig)return; lastCatSig=sig
  const scroll=$('#catgrid').scrollTop
  const pc=v=>(v/(TEX/100))+'%'
@@ -478,7 +492,7 @@ async function fillCat(force){
   const fl=row.rect&&row.rect.flip
   const ovm=row.rect?('<div class=ovmini style="left:'+pc(fl?TEX-row.rect.x-row.rect.w:row.rect.x)+';top:'+pc(row.rect.y)+
    ';width:'+pc(row.rect.w)+';height:'+pc(row.rect.h)+'"></div>'):''
-  return '<div class=card><div class=th><img src="'+thumbUrl(row.id)+'"'+(fl?' style="transform:scaleX(-1)"':'')+'>'+ovm+'</div>'+
+  return '<div class=card><div class=th><img src="'+thumbUrl(row.id)+'"'+(fl?' style="transform:scaleX(-1)"':'')+'>'+ovm+(pending.includes(row.id)?'<div class=spin></div>':'')+'</div>'+
   '<div class=nm onclick="selectAsset(\\''+jsq(row.id)+'\\')">'+esc(row.label)+'</div>'+
   (row.icon?'':('<div class=row><label>size <input type=number step=0.1 min=0.1 value="'+(row.rect?row.rect.size:1)+'"'+
    ' onchange="setSize(\\''+jsq(row.id)+'\\',\\''+jsq(row.name)+'\\',this.value)"></label>'+
@@ -608,8 +622,13 @@ document.addEventListener('keydown',e=>{
 let firstBeat=true
 async function heartbeat(){
  const s=await j('/api/state')
+ pending=s.pending||[]
  renderSide(s.assets)
- $('#status').textContent=s.generating?('generating '+(s.current||'…')+' '+s.done+'/'+s.total+(s.queued?(' · '+s.queued+' queued'):'')):''
+ const p=s.progress
+ $('#status').textContent=s.generating?('generating '+(s.current||'…')+' '+s.done+'/'+s.total+(s.queued?(' · '+s.queued+' queued'):'')+(p&&p.max?(' · step '+p.value+'/'+p.max):'')):''
+ $('#qcancel').style.display=s.generating?'':'none'
+ const pb=$('#prog');pb.style.display=(s.generating&&p&&p.max)?'block':'none'
+ if(p&&p.max)pb.firstElementChild.style.width=Math.round(100*p.value/p.max)+'%'
  const e=$('#errs')
  if(s.errors.length){e.style.display='block';e.textContent=s.errors.join('\\n')}else e.style.display='none'
  if(catMode)await fillCat(false)

package/src/assets/server/studio-queue.ts

@@ -1,16 +1,24 @@
 // Generation queue: single worker, IN-MEMORY (never run the studio with
 // --watch — a restart drops every queued roll; the fill CLI is the recovery
-// path), errors surfaced in a ring buffer, never fatal.
+// path), errors surfaced in a ring buffer, never fatal. Per-step progress
+// (comfy /ws) lives on state; cancel drops the CURRENT job's remaining
+// rolls — queued jobs are `clear()`'s business.
+import type { GenProgress } from '../gen/comfy-gen.ts'
+
 export type Job = { assetId: string; prompt: string; count: number }
-export type QueueState = { generating: boolean; current: string | null; done: number; total: number }
+export type QueueState = { generating: boolean; current: string | null; done: number; total: number; progress: GenProgress | null }
 
 export class StudioQueue {
     private jobs: Job[] = []
-    readonly state: QueueState = { generating: false, current: null, done: 0, total: 0 }
+    private cancelRequested = false
+    readonly state: QueueState = { generating: false, current: null, done: 0, total: 0, progress: null }
     readonly errors: string[] = []
 
     /** generateOne throws on failure — the queue logs and moves on */
-    constructor(private generateOne: (job: Job, seed: number) => Promise<void>, private newSeed: () => number) {}
+    constructor(
+        private generateOne: (job: Job, seed: number, onProgress: (p: GenProgress) => void) => Promise<void>,
+        private newSeed: () => number,
+    ) {}
 
     pushError(msg: string): void {
         this.errors.push(msg)
@@ -20,6 +28,20 @@ export class StudioQueue {
 
     get queuedCount(): number { return this.jobs.length }
 
+    /** asset ids with work still ahead of them (current + queued) — the SPA's spinner set */
+    pendingIds(): string[] {
+        const ids = this.state.generating && this.state.current != null ? [this.state.current] : []
+        for (const j of this.jobs) if (!ids.includes(j.assetId)) ids.push(j.assetId)
+        return ids
+    }
+
+    /** cancel the CURRENT job: the caller interrupts the backend, this drops
+     *  the job's remaining rolls (an interrupted roll's throw is logged as a
+     *  cancel, never an error). No-op when idle. */
+    requestCancel(): void {
+        if (this.state.generating) this.cancelRequested = true
+    }
+
     clear(): void { this.jobs.length = 0 }
 
     enqueue(newJobs: Job[]): void {
@@ -41,18 +63,35 @@ export class StudioQueue {
             if (job == null) {
                 this.state.generating = false
                 this.state.current = null
+                this.state.progress = null
                 return
             }
             this.state.current = job.assetId
+            // each job starts with a clean cancel slate — a cancel raced by a
+            // roll that RESOLVED anyway must never leak onto the next job
+            this.cancelRequested = false
             for (let i = 0; i < job.count; i++) {
+                if (this.consumeCancel(job, i)) break
                 const seed = this.newSeed()
                 try {
-                    await this.generateOne(job, seed)
+                    await this.generateOne(job, seed, (p) => { this.state.progress = p })
                 } catch (e) {
+                    if (this.consumeCancel(job, i)) break
                     this.pushError(`${job.assetId} seed ${seed}: ${(e as Error).message}`)
                 }
+                this.state.progress = null
                 this.state.done++
             }
         }
     }
+
+    /** true = cancel was pending; rolls i..count-1 are counted done + dropped */
+    private consumeCancel(job: Job, i: number): boolean {
+        if (!this.cancelRequested) return false
+        this.cancelRequested = false
+        this.state.done += job.count - i
+        this.state.progress = null
+        console.log(`ok: cancelled ${job.assetId} — ${job.count - i} roll(s) dropped`)
+        return true
+    }
 }

package/src/assets/server/studio-server.ts

@@ -7,7 +7,7 @@
 import { existsSync, unlinkSync } from 'fs'
 import { join, relative } from 'path'
 import { findAsset, allAssets, missingPanelScripts, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit, type ShipFn } from '../kit-config.ts'
-import { randomSeed } from '../gen/comfy-gen.ts'
+import { interrupt, randomSeed, type OnProgress } from '../gen/comfy-gen.ts'
 import { generateRoll, type ComfyRuntime } from '../gen/generate-roll.ts'
 import { loadWorkflows, type Workflow } from '../gen/workflow-loader.ts'
 import { alphaHeight, toPng } from '../image-ops.ts'
@@ -21,7 +21,7 @@ export type StudioDeps = {
     root: string
     page: () => string
     /** test seam — defaults to the comfy engine */
-    generateOne?: (found: FoundAsset, prompt: string, seed: number, destDir: string) => Promise<void>
+    generateOne?: (found: FoundAsset, prompt: string, seed: number, destDir: string, onProgress?: OnProgress) => Promise<void>
 }
 
 export type Studio = { server: ReturnType<typeof Bun.serve>; queue: StudioQueue; stop: () => void }
@@ -100,13 +100,13 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
         return { workflows, host: kit.comfy.host, heal: kit.comfy.heal }
     }
-    const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir) =>
-        generateRoll(found, { prompt, seed, destDir }, resolveComfy))
+    const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir, onProgress) =>
+        generateRoll(found, { prompt, seed, destDir, onProgress }, resolveComfy))
 
-    const queue = new StudioQueue(async (job, seed) => {
+    const queue = new StudioQueue(async (job, seed, onProgress) => {
         const found = findAsset(kit, job.assetId)
         if (found == null) throw new Error(`asset '${job.assetId}' not in the kit — job dropped`)
-        await generateOne(found, job.prompt, seed, dirOf(job.assetId))
+        await generateOne(found, job.prompt, seed, dirOf(job.assetId), onProgress)
     }, randomSeed)
 
     // ── session/live rect plumbing ─────────────────────────────────────────
@@ -199,7 +199,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                     icon: f.kind.mode === 'icon',
                 }
             }))
-            return json({ ...queue.state, queued: queue.queuedCount, errors: queue.errors.slice(-5), assets })
+            return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: queue.errors.slice(-5), assets })
         }
 
         if (pathname === '/api/asset') {
@@ -295,6 +295,19 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
             queue.clear()
             return json({ ok: true })
         }
+        if (pathname === '/api/interrupt') {
+            // cancel the CURRENT job: backend interrupt (comfy kits) + drop
+            // its remaining rolls; queued jobs stay (that's clear's business)
+            if (!queue.state.generating) return bad('nothing generating')
+            queue.requestCancel()
+            // only touch the box when the RUNNING job is a comfy kind — the
+            // box is shared, an unrelated prompt must never be interrupted
+            const running = queue.state.current != null ? findAsset(kit, queue.state.current) : null
+            if (kit.comfy != null && running?.kind.generate.backend === 'comfy')
+                await interrupt({ host: kit.comfy.host, heal: kit.comfy.heal }).catch((e: Error) =>
+                    queue.pushError(`interrupt: ${e.message} — current roll will finish, its job is still dropped`))
+            return json({ ok: true })
+        }
         if (pathname === '/api/pick') {
             const name = safeRoll(b.name)
             const f = findAsset(kit, String(b.id))