rvlib-shipkit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.6.0 — 2026-07-22
+
+New (wave 3 of the shipkit expansion — media + manual assets):
+
+- `manual()` generator backend — human-provided assets, any media: no
+  Generate button (POST /api/generate 400s; fill/add skip with a visible
+  line; generate-cat excludes them and an all-manual category 400s with an
+  upload pointer — its +N buttons are hidden in the SPA), the studio's
+  upload (button or drag-drop on the roll strip, POST /api/upload multipart,
+  ext-gated per media, seed-style `v<seed>` names — no same-ms overwrite) is
+  the only roll source. Upload itself works on EVERY kind (touched-up
+  images welcome). A manual asset with NO rolls is RED in the sidebar and
+  FAILs `shipkit assets check` with its curation brief; rolls-but-no-pick
+  WARNs. The asset's `prompt` is the brief.
+- `ship.dir` is now honored lib-side: with no via/fn hook, picking copies
+  the roll to `<dir>/<assetId>.<ext>` (zero-config ship); hooks still win
+  and read `dir` as data. Previously `dir` was inert without a repo hook.
+- `media: 'audio'` on kinds — rolls `v<n>.mp3|wav|ogg|m4a`, studio renders
+  players (roll strip, stage, grid card) instead of thumbnails; audio kinds
+  require `manual()` (generation backends are image-only today) and reject
+  geometry panels, both validated loud at defineKit. `isAudioRoll` exported.
+- barrel: `manual`, `mediaOf`, `MEDIA_EXTS`, `isAudioRoll` + types
+  `Media`/`ManualGen` exported.
+
 ## 0.5.0 — 2026-07-22
 
 New (wave 2 of the shipkit expansion — generation UX):

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.5.0",
+    "version": "0.6.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/generate-roll.ts

@@ -24,6 +24,8 @@ export async function generateRoll(
     resolveComfy: ComfyResolver,
 ): Promise<void> {
     const gen = found.kind.generate
+    if (gen.backend === 'manual')
+        throw new Error(`'${found.asset.id}' is a manual asset — upload a file in the studio (button or drag-drop), nothing generates it`)
     if (gen.backend === 'canvas') {
         const { createCanvas } = await import('@napi-rs/canvas')
         const c = createCanvas(CANVAS_SIZE, CANVAS_SIZE)

package/src/assets/kit-config.ts

@@ -19,9 +19,20 @@ export type AssetSpec = {
 
 export type ComfyGen = { backend: 'comfy'; workflow?: string; bg?: string }
 export type CanvasGen = { backend: 'canvas'; draw: (ctx: unknown, asset: AssetSpec) => void | Promise<void> }
-export type GeneratorSpec = ComfyGen | CanvasGen
+/** Human-provided assets (any media): the studio's upload mints rolls, a
+ *  manual asset with no rolls is RED + FAILs `shipkit assets check`. The
+ *  asset's `prompt` is the curation brief. */
+export type ManualGen = { backend: 'manual' }
+export type GeneratorSpec = ComfyGen | CanvasGen | ManualGen
 export const comfy = (p?: { workflow?: string; bg?: string }): ComfyGen => ({ backend: 'comfy', workflow: p?.workflow, bg: p?.bg })
 export const canvas = (draw: CanvasGen['draw']): CanvasGen => ({ backend: 'canvas', draw })
+export const manual = (): ManualGen => ({ backend: 'manual' })
+
+export type Media = 'image' | 'audio'
+export const mediaOf = (kind: Kind): Media => kind.media ?? 'image'
+/** roll/upload extensions per media — ONE source for the workspace regex,
+ *  the upload route, and the SPA's player-vs-img decision */
+export const MEDIA_EXTS: Record<Media, string[]> = { image: ['webp', 'png'], audio: ['mp3', 'wav', 'ogg', 'm4a'] }
 
 export type GeometryPanelSpec = {
     panel: 'geometry'
@@ -81,10 +92,14 @@ export type Kind = {
     category: string
     assets: AssetSpec[]
     generate: GeneratorSpec
+    /** roll media (default 'image') — audio kinds render players, take no geometry */
+    media?: Media
     /** icon kinds get no geometry, thumbnails only */
     mode?: 'sprite' | 'icon'
     /** via = repo hook module path (default .rv-assets/ship.ts) · fn = a
-     *  built-in lib hook (e.g. identityKinds re-rendering the set) — never both */
+     *  built-in lib hook (e.g. identityKinds re-rendering the set) — never
+     *  both. With NO hook, `dir` alone is the zero-config ship: the picked
+     *  roll is copied to <dir>/<assetId>.<ext>; hooks read dir as data. */
     ship?: { dir?: string; via?: string; fn?: ShipFn }
     meta?: KindMeta
 }
@@ -109,6 +124,12 @@ export function validateKit(k: KitConfig): string[] {
         if (kindIds.has(kind.id)) errs.push(`duplicate kind id '${kind.id}'`)
         kindIds.add(kind.id)
         if (kind.generate?.backend === 'comfy' && k.comfy == null) errs.push(`kind '${kind.id}' uses the comfy backend but the kit has no comfy config`)
+        if (kind.media != null && !(kind.media in MEDIA_EXTS))
+            errs.push(`kind '${kind.id}': unknown media '${String(kind.media)}' (${Object.keys(MEDIA_EXTS).join('/')})`)
+        if (kind.media === 'audio' && kind.generate?.backend !== 'manual')
+            errs.push(`kind '${kind.id}': media 'audio' supports only the manual() backend today (generation backends are image-only)`)
+        if (kind.media === 'audio' && (kind.meta?.panels ?? []).some((p) => p.panel === 'geometry'))
+            errs.push(`kind '${kind.id}': audio kinds take no geometry panel`)
         if (kind.ship?.fn != null && kind.ship?.via != null) errs.push(`kind '${kind.id}': ship.fn and ship.via are two hooks for one pick — keep one`)
         if (!Array.isArray(kind.assets) || kind.assets.length === 0) errs.push(`kind '${kind.id}' has no assets — a silent no-op kind is a config mistake`)
         for (const a of kind.assets ?? []) {

package/src/assets/roll-workspace.ts

@@ -15,7 +15,9 @@ export const PICK_INIT: PickState = { pick: null, alts: [], shippedAt: null }
 export type PromptOverlay = { prompt: string | null }
 export const PROMPT_INIT: PromptOverlay = { prompt: null }
 
-export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png)$/.test(f)
+// extension list mirrors kit-config MEDIA_EXTS (audio added 0.6.0)
+export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png|mp3|wav|ogg|m4a)$/.test(f)
+export const isAudioRoll = (f: string): boolean => /\.(mp3|wav|ogg|m4a)$/.test(f)
 
 export const assetDir = (workspace: string, assetId: string): string => join(workspace, 'studio', assetId)
 

package/src/assets/run-assets.ts

@@ -65,9 +65,13 @@ export const runAssetsTopUp = (root: string, io: AssetsIo, o: { mode: 'fill' | '
     guarded(io, async () => {
         const kit = await loadKit(root)
         const resolveComfy = comfyFor(root, kit)
-        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process)
-        const targets = allAssets(kit)
-            .filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
+        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process);
+        // manual kinds have nothing to generate — visible skip, never silence
+        const inScope = allAssets(kit).filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
+        const manualCount = inScope.filter((f) => f.kind.generate.backend === 'manual').length
+        if (manualCount > 0) io.print(`skip: ${manualCount} manual asset(s) — upload in the studio`)
+        const targets = inScope
+            .filter((f) => f.kind.generate.backend !== 'manual')
             .map((f) => ({ f, have: listRolls(assetDir(join(root, kit.workspace), f.asset.id)).length }))
             .map((t) => ({ ...t, want: o.mode === 'add' ? o.n : Math.max(0, o.n - t.have) }))
             .filter((t) => t.want > 0)
@@ -138,5 +142,17 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
             if (outs.length > 0) io.print(`WARN identity outputs missing: ${outs.join(', ')} — run: shipkit assets identity`)
             else io.print('ok: identity outputs present')
         }
+        // manual assets: no rolls = nothing to ship = RED (the missing list
+        // is the shopping list — build/audio doctrine); rolls-but-no-pick = WARN
+        const manuals = allAssets(kit).filter((f) => f.kind.generate.backend === 'manual')
+        let manualBad = 0
+        for (const f of manuals) {
+            const dir = assetDir(join(root, kit.workspace), f.asset.id)
+            const rolls = listRolls(dir)
+            if (rolls.length === 0) { io.print(`FAIL: manual asset '${f.asset.id}' has no file — upload in the studio (brief: ${f.asset.prompt.slice(0, 60)})`); manualBad++ }
+            else if ((await readPick(dir)).pick == null) io.print(`WARN manual asset '${f.asset.id}' has ${rolls.length} file(s), none picked`)
+        }
+        bad += manualBad
+        if (manuals.length > 0 && manualBad === 0) io.print(`ok: ${manuals.length} manual asset(s) provided`)
         return bad > 0 ? 1 : 0
     })

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

@@ -48,6 +48,13 @@ select,input[type=number]{background:var(--bg);color:var(--ink);border:1px solid
 .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}
+.dot.miss{background:#e5484d;border-color:#e5484d}
+.vig.aud{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px;font-size:20px}
+.vig.aud audio{width:100%;height:24px}
+.stageaud{display:flex;flex-direction:column;align-items:center;gap:14px;font-size:48px;padding:40px}
+.stageaud audio{width:min(480px,80%)}
+.card .aud{aspect-ratio:1;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;font-size:28px}
+.card .aud audio{width:92%;height:24px}
 .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)}
@@ -145,6 +152,8 @@ kbd{background:var(--panel2);border:1px solid var(--line);border-radius:4px;padd
    <select id=n><option>1</option><option selected>3</option><option>6</option><option>9</option><option>12</option></select>
    <button id=go disabled>Generate</button>
    <div id=detnote class=detnote style="display:none">deterministic — rolls identical</div>
+   <button id=upload class=ghost style="display:none" title="add files as rolls (or drag-drop onto the strip)">upload</button>
+   <input type=file id=upfile multiple style="display:none">
    <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>
@@ -223,11 +232,11 @@ function renderSide(list){
   const open=openCats.has(c)
   const head='<div class=gname><span><span class=fold onclick="toggleFold(\\''+jsq(c)+'\\')">'+(open?'▾':'▸')+'</span> '+
    '<span class=cn onclick="showCat(\\''+jsq(c)+'\\')" title="grid view">'+esc(c)+'</span>'+
-   '</span><span class=catgen>'+[1,2,3].map(n=>'<button onclick="genCat(\\''+jsq(c)+'\\','+n+')">+'+n+'</button>').join('')+'</span></div>'
+   '</span>'+(list.filter(a=>a.cat===c).every(a=>a.manual)?'':'<span class=catgen>'+[1,2,3].map(n=>'<button onclick="genCat(\\''+jsq(c)+'\\','+n+')">+'+n+'</button>').join('')+'</span>')+'</div>'
   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>'+(pending.includes(a.id)?'<div class=spin></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':(a.manual?'miss':'')))+'"'+(a.manual&&!a.rolls?' title="manual asset — nothing uploaded yet"':'')+'></div>')+'</div>').join('')
  }).join('')
 }
 // ── per-asset info surface (W2-2): backend, workflow provenance, ship target,
@@ -265,18 +274,37 @@ async function selectAsset(id,writeHash=true){
  if(tab.indexOf('c:')===0&&!customs.some(c=>'c:'+c.id===tab))tab='asset' // new asset may not carry the open panel
  renderCustomTabs()
  $('#prompt').value=r.asset?r.asset.prompt:a.prompt
- $('#go').disabled=false;$('#saveprompt').disabled=false;$('#promptmsg').textContent=''
+ $('#saveprompt').disabled=false;$('#promptmsg').textContent=''
+ // manual kinds: nothing generates them — upload is the only roll source
+ const man=!!a.manual
+ $('#go').disabled=man;$('#go').style.display=man?'none':''
+ $('#upload').style.display=''
+ $('#upfile').accept=(a.media==='audio'?'.mp3,.wav,.ogg,.m4a':'.png,.webp')
  // deterministic canvas kinds: a slot machine with one outcome — cap rolls at 1
  const det=!!(r.info&&r.info.deterministic),n=$('#n')
- n.disabled=det;if(det)n.value='1';$('#detnote').style.display=det?'':'none'
+ n.disabled=det||man;if(det)n.value='1';n.style.display=man?'none':''
+ $('#detnote').textContent=man?'manual — upload files (drag-drop works)':'deterministic — rolls identical'
+ $('#detnote').style.display=(det||man)?'':'none'
  renderInfo(r.info)
  await renderRolls(true);loadTab()
 }
+const isAud=n=>['mp3','wav','ogg','m4a'].includes(String(n||'').split('.').pop())
 function setStage(src){
- const st=$('#stage');let img=st.querySelector('img.roll')
+ const st=$('#stage');st.querySelector('.stageaud')?.remove()
+ let img=st.querySelector('img.roll')
  if(!img){st.querySelector('.ph')?.remove();img=document.createElement('img');img.className='roll';st.appendChild(img);img.onload=positionOverlay}
  img.src=src
 }
+function setStageAud(n){
+ const st=$('#stage')
+ const curAud=st.querySelector('.stageaud')
+ if(curAud&&curAud.dataset.n===n)return // keep playback alive across heartbeats
+ st.querySelector('img.roll')?.remove();st.querySelector('.ph')?.remove();curAud?.remove()
+ const d=document.createElement('div');d.className='stageaud';d.dataset.n=n
+ d.innerHTML='🔊<audio controls src="'+imgUrl(cur,n)+'"></audio>'
+ st.appendChild(d);hideOverlay()
+}
+const showRoll=n=>isAud(n)?setStageAud(n):setStage(imgUrl(cur,n))
 async function renderRolls(reset){
  if(!cur)return
  const r=await j('/api/asset?id='+encodeURIComponent(cur))
@@ -286,25 +314,28 @@ async function renderRolls(reset){
  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()
+  const gst=$('#stage');gst.querySelector('img.roll')?.remove();gst.querySelector('.stageaud')?.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(!rolls.length){const a0=assets.find(x=>x.id===cur)
+  strip.innerHTML='<div class=ph>'+(a0&&a0.manual?'no files — upload (or drag-drop here)':'no rolls — hit Generate')+'</div>';hideOverlay()
+  const st=$('#stage');st.querySelector('img.roll')?.remove();st.querySelector('.stageaud')?.remove()
   if(!st.querySelector('.ph')){const ph=document.createElement('div');ph.className='ph';ph.textContent='no rolls yet';st.appendChild(ph)}
   active=null;return}
  if(reset||!rolls.some(x=>x.name===active))active=(rolls.find(x=>x.picked)||rolls[0]).name
- setStage(imgUrl(cur,active))
+ showRoll(active)
  if(hasGeom)await loadRect()
+ const btns='<div class=btns><button class=b-pick>pick</button><button class=b-alt>alt</button><button class=b-del>✕</button></div>'
  strip.innerHTML=rolls.map(x=>
-  '<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('')
+  '<div class="vig'+(isAud(x.name)?' aud':'')+(x.name===active?' active':'')+(x.picked?' picked':'')+(x.alt?' alt':'')+'" data-n="'+x.name+'">'+
+  (isAud(x.name)?'🔊<audio controls src="'+imgUrl(cur,x.name)+'"></audio>':'<img src="'+imgUrl(cur,x.name)+'">')+(x.picked?'<span class=st>★</span>':'')+
+  btns+'</div>').join('')
   +(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))
+  // hover-preview stays image-only — recreating an <audio> mid-playback on hover would cut the sound
+  v.onmouseenter=()=>{if(!isAud(n))setStage(imgUrl(cur,n))}
+  v.onmouseleave=()=>showRoll(active) // setStageAud keepalive avoids audio recreate when unchanged
   v.onclick=()=>{active=n;lastRollSig=null;renderRolls(false);if(tab!=='asset')loadTab()} // meta + custom panels are per-roll
   v.querySelector('.b-pick').onclick=e=>{e.stopPropagation();pickRoll(n)}
   v.querySelector('.b-alt').onclick=e=>{e.stopPropagation();post('/api/alt',{id:cur,name:n}).then(()=>renderRolls(false))}
@@ -321,10 +352,24 @@ async function discard(n){
  if(active===n)active=null
  lastRollSig=null;lastSideSig=null;await renderRolls(true)
 }
-async function genCat(c,n){await post('/api/generate-cat',{cat:c,count:n});heartbeat()}
+async function genCat(c,n){const r=await post('/api/generate-cat',{cat:c,count:n});if(r&&r.error)$('#status').textContent=r.error;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')
+// ── upload: button, file input, drag-drop on the strip (manual kinds' only roll source) ──
+async function uploadFiles(files){
+ if(!cur||!files||!files.length)return
+ for(const f of files){
+  const fd=new FormData();fd.append('id',cur);fd.append('file',f)
+  const r=await fetch(R('/api/upload'),{method:'POST',body:fd}).then(x=>x.json()).catch(e=>({error:String(e)}))
+  if(r.error)$('#status').textContent='upload FAIL: '+r.error
+ }
+ lastRollSig=null;lastSideSig=null;await renderRolls(false)
+}
+$('#upload').onclick=()=>$('#upfile').click()
+$('#upfile').onchange=async e=>{await uploadFiles(e.target.files);e.target.value=''}
+$('#strip').addEventListener('dragover',e=>e.preventDefault())
+$('#strip').addEventListener('drop',e=>{e.preventDefault();uploadFiles(e.dataTransfer.files)})
 $('#saveprompt').onclick=async()=>{
  const r=await post('/api/prompt',{id:cur,prompt:$('#prompt').value})
  $('#promptmsg').textContent=r.error?('FAIL: '+r.error):'saved (overlay)'
@@ -492,9 +537,11 @@ 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+(pending.includes(row.id)?'<div class=spin></div>':'')+'</div>'+
+  return '<div class=card>'+(isAud(row.name)
+   ?'<div class=aud>🔊<audio controls src="'+imgUrl(row.id,row.name)+'"></audio>'+(pending.includes(row.id)?'<div class=spin></div>':'')+'</div>'
+   :'<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)+'"'+
+  ((row.icon||isAud(row.name))?'':('<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>'+
    '<button class=ghost onclick="toggleFlip(\\''+jsq(row.id)+'\\',\\''+jsq(row.name)+'\\')">⇆ flip</button></div>'))+'</div>'
  }).join('')

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

@@ -4,9 +4,9 @@
 //
 // ids/names are validated against the kit + the roll-file regex — no path
 // from the client ever reaches the filesystem unchecked.
-import { existsSync, unlinkSync } from 'fs'
+import { existsSync, mkdirSync, 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 { findAsset, allAssets, mediaOf, missingPanelScripts, MEDIA_EXTS, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit, type ShipFn } from '../kit-config.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'
@@ -28,7 +28,7 @@ export type Studio = { server: ReturnType<typeof Bun.serve>; queue: StudioQueue;
 
 // what the studio detail view shows about an asset's plumbing (W2-2)
 export type AssetInfo = {
-    backend: 'canvas' | 'comfy'
+    backend: 'canvas' | 'comfy' | 'manual'
     /** canvas rolls have no seed input — every roll is identical */
     deterministic: boolean
     /** comfy only: resolved workflow id + its .rv-comfy path (note = why unresolved) */
@@ -161,7 +161,17 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     }
     const ship = async (f: FoundAsset, roll: string): Promise<{ shipped: string | null }> => {
         const fn = await resolveShipFn(f)
-        if (fn == null) return { shipped: null } // no hook: pick.json is the record
+        if (fn == null) {
+            // no hook: ship.dir is the zero-config path — copy the picked
+            // roll as <dir>/<assetId>.<ext>; without dir, pick.json is the record
+            const dir = f.kind.ship?.dir
+            if (dir == null) return { shipped: null }
+            const ext = roll.split('.').at(-1)!
+            const dest = join(root, dir, `${f.asset.id}.${ext}`)
+            mkdirSync(join(root, dir), { recursive: true })
+            await Bun.write(dest, Bun.file(join(dirOf(f.asset.id), roll)))
+            return { shipped: relative(root, dest) }
+        }
         const dir = dirOf(f.asset.id)
         const g = geometryOf(f)
         const dest = await fn({
@@ -196,7 +206,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                 return {
                     id: f.asset.id, cat: f.kind.category, label: f.asset.label ?? f.asset.id,
                     prompt: await promptOf(f), rolls: listRolls(dir).length, picked: pick.pick != null,
-                    icon: f.kind.mode === 'icon',
+                    icon: f.kind.mode === 'icon', media: mediaOf(f.kind), manual: f.kind.generate.backend === 'manual',
                 }
             }))
             return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: queue.errors.slice(-5), assets })
@@ -274,18 +284,44 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         }
 
         if (req.method !== 'POST') return new Response('', { status: 404 })
+
+        if (pathname === '/api/upload') {
+            // multipart (not json) — handled before the json body() parse.
+            // Any kind accepts uploads (touched-up images welcome); manual
+            // kinds have no other roll source. Ext validated per kind media.
+            const fd = await req.formData().catch(() => null)
+            if (fd == null) return bad('multipart form expected (id + file)')
+            const f = findAsset(kit, String(fd.get('id') ?? ''))
+            if (f == null) return bad(`unknown asset '${String(fd.get('id') ?? '')}'`)
+            const file = fd.get('file')
+            if (!(file instanceof File)) return bad('file field missing')
+            const ext = (file.name.split('.').at(-1) ?? '').toLowerCase()
+            const allowed = MEDIA_EXTS[mediaOf(f.kind)]
+            if (!allowed.includes(ext)) return bad(`'${file.name}': .${ext} not allowed for ${mediaOf(f.kind)} (${allowed.join('/')})`)
+            // seed-style name like generated rolls — Date.now() collides for
+            // same-ms multi-uploads and silently overwrites
+            const name = `v${randomSeed()}.${ext}`
+            await Bun.write(join(dirOf(f.asset.id), name), await file.arrayBuffer())
+            return json({ ok: true, name })
+        }
+
         const b = await body()
 
         if (pathname === '/api/generate') {
             const f = findAsset(kit, String(b.id))
             if (f == null) return bad(`unknown asset '${String(b.id)}'`)
+            if (f.kind.generate.backend === 'manual') return bad(`'${f.asset.id}' is a manual asset — upload a file instead`)
             const count = Math.max(1, Math.min(24, Number(b.count) || 1))
             const prompt = typeof b.prompt === 'string' && b.prompt.trim() !== '' ? b.prompt : await promptOf(f)
             queue.enqueue([{ assetId: f.asset.id, prompt, count }])
             return json({ ok: true })
         }
         if (pathname === '/api/generate-cat') {
-            const hit = allAssets(kit).filter((f) => f.kind.category === b.cat)
+            // manual kinds excluded from batch gen — nothing generates them;
+            // an all-manual cat gets a truthful pointer, not "no assets"
+            const inCat = allAssets(kit).filter((f) => f.kind.category === b.cat)
+            const hit = inCat.filter((f) => f.kind.generate.backend !== 'manual')
+            if (hit.length === 0 && inCat.length > 0) return bad(`cat '${String(b.cat)}' has only manual assets — upload in the studio`)
             if (hit.length === 0) return bad(`no assets in cat '${String(b.cat)}'`)
             const count = Math.max(1, Math.min(6, Number(b.count) || 1))
             queue.enqueue(await Promise.all(hit.map(async (f) => ({ assetId: f.asset.id, prompt: await promptOf(f), count }))))
@@ -382,6 +418,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
             const name = safeRoll(b.name)
             const f = findAsset(kit, String(b.id))
             if (name == null || f == null) return bad('bad id/name')
+            if (geometryOf(f) == null) return bad(`kind '${f.kind.id}' has no geometry panel`)
             const current = await sessionRect(f, name)
             const flipped = { ...current, flip: current.flip === true ? undefined : true } as unknown as Record<string, unknown>
             const res = await saveRect(f, name, flipped)

package/src/shipkit.ts

@@ -33,8 +33,8 @@ export type { Ask, CreateOpts } from './asks/asks-queue.ts'
 // assets surface (folded in from the standalone atelier lib; that npm
 // package is frozen). A repo's .rv-assets/kit.ts imports defineKit and
 // declares its kinds; `shipkit assets …` derives the rest.
-export { defineKit, defineKind, comfy, canvas, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
-export type { KitConfig, ResolvedKit, Kind, KindMeta, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'
+export { defineKit, defineKind, comfy, canvas, manual, mediaOf, MEDIA_EXTS, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
+export type { KitConfig, ResolvedKit, Kind, KindMeta, Media, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, ManualGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'
 export { identityKinds, renderIdentity, renderIdentityFromMark, NO_PICK_FIX, FAVICON_SIZE, OG_W, OG_H, LOGO_SIZE } from './assets/kits/identity-kit.ts'
 export type { Brand } from './assets/kits/identity-kit.ts'
 export { serveStudio, studioRoutes } from './assets/server/studio-server.ts'
@@ -50,7 +50,7 @@ export { loadWorkflows, workflowFor } from './assets/gen/workflow-loader.ts'
 export type { Workflow, Sidekick, Binding, Graph } from './assets/gen/workflow-loader.ts'
 export { toPng, alphaHeight } from './assets/image-ops.ts'
 export { updateJson, readJson } from './assets/json-store.ts'
-export { assetDir, listRolls, isRollFile, readPick, updatePick, metaPath, pickPath, readPromptOverlay, updatePromptOverlay, promptPath } from './assets/roll-workspace.ts'
+export { assetDir, listRolls, isRollFile, isAudioRoll, readPick, updatePick, metaPath, pickPath, readPromptOverlay, updatePromptOverlay, promptPath } from './assets/roll-workspace.ts'
 export type { PickState, PromptOverlay } from './assets/roll-workspace.ts'
 export { scanMdGraph } from './wiki/scan-md.ts'
 export { lintMd } from './wiki/lint-md.ts'