rvlib-shipkit 0.2.0 → 0.3.0

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

@@ -5,8 +5,8 @@
 // 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 { join } from 'path'
-import { findAsset, allAssets, missingPanelScripts, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit } from '../kit-config.ts'
+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 { generateRoll, type ComfyRuntime } from '../gen/generate-roll.ts'
 import { loadWorkflows, type Workflow } from '../gen/workflow-loader.ts'
@@ -26,19 +26,26 @@ export type StudioDeps = {
 
 export type Studio = { server: ReturnType<typeof Bun.serve>; queue: StudioQueue; stop: () => void }
 
-type ShipCtx = {
-    assetId: string
-    file: string
-    asset: FoundAsset['asset']
-    kind: FoundAsset['kind']
-    meta: unknown
-    rect: GroundRect | null
-    projectRoot: string
-    img: { toPng: typeof toPng; alphaHeight: typeof alphaHeight }
+// what the studio detail view shows about an asset's plumbing (W2-2)
+export type AssetInfo = {
+    backend: 'canvas' | 'comfy'
+    /** canvas rolls have no seed input — every roll is identical */
+    deterministic: boolean
+    /** comfy only: resolved workflow id + its .rv-comfy path (note = why unresolved) */
+    workflow: { id: string | null; path: string | null; note?: string } | null
+    ship: { mode: 'built-in' | 'hook' | 'record'; path?: string; note?: string }
+    /** live write-through target (kind.meta.file), repo-root-relative */
+    metaFile: string | null
+    kindId: string
+    kitSource: string
 }
-type ShipFn = (ctx: ShipCtx) => Promise<string | void>
 
-export async function serveStudio(deps: StudioDeps): Promise<Studio> {
+// the studio's route table without a server: `handle` answers the studio's
+// own path space ('/', '/api/…', '/img', '/panel/…') so serveStudio can own
+// a port AND the shipkit hub can mount the same routes under /assets/.
+export type StudioRoutes = { handle: (req: Request, pathname: string) => Promise<Response>; queue: StudioQueue }
+
+export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     const { kit, root } = deps
     const workspace = join(root, kit.workspace)
     const dirOf = (id: string): string => assetDir(workspace, id)
@@ -54,6 +61,35 @@ export async function serveStudio(deps: StudioDeps): Promise<Studio> {
     const customPanelsOf = (f: FoundAsset): CustomPanelSpec[] =>
         (f.kind.meta?.panels ?? []).filter((p): p is CustomPanelSpec => p.panel === 'custom')
 
+    // ── per-asset provenance for the studio's info surface (W2-2): where every
+    //    roll comes from and where a pick goes. Read-only; never throws (a
+    //    misconfigured comfy kind still shows WHY, it doesn't blank the view).
+    const relOf = (p: string): string => relative(root, p) || p
+    const infoOf = (f: FoundAsset): AssetInfo => {
+        const gen = f.kind.generate
+        const backend = gen.backend
+        let workflow: AssetInfo['workflow'] = null
+        if (gen.backend === 'comfy') {
+            let id = gen.workflow ?? null
+            let note: string | undefined
+            if (id == null) {
+                if (workflows != null && workflows.size === 1) id = [...workflows.keys()][0]!
+                else if (workflows != null) note = `names no workflow; ${workflows.size} loaded — set workflow on the kind`
+            }
+            const wf = id != null && workflows != null ? workflows.get(id) : undefined
+            if (id != null && wf == null && note == null) note = `workflow '${id}' not loaded`
+            const path = wf != null ? relOf(wf.jsonPath) : id != null && kit.comfy != null ? join(kit.comfy.workflows, `${id}.json`) : null
+            workflow = { id, path, note }
+        }
+        let ship: AssetInfo['ship']
+        if (f.kind.ship?.fn != null) ship = { mode: 'built-in', note: 're-renders the set on pick' }
+        else {
+            const via = f.kind.ship?.via ?? '.rv-assets/ship.ts'
+            ship = existsSync(join(root, via)) ? { mode: 'hook', path: via } : { mode: 'record', note: 'pick.json only — no ship hook' }
+        }
+        return { backend, deterministic: backend === 'canvas', workflow, ship, metaFile: f.kind.meta?.file ?? null, kindId: f.kind.id, kitSource: '.rv-assets/kit.ts' }
+    }
+
     // effective prompt: workspace overlay wins over the kit's builder output
     const promptOf = async (f: FoundAsset): Promise<string> =>
         (await readPromptOverlay(dirOf(f.asset.id))).prompt ?? f.asset.prompt
@@ -104,10 +140,13 @@ export async function serveStudio(deps: StudioDeps): Promise<Studio> {
         return errs.length > 0 ? { errors: errs } : { rect }
     }
 
-    // ── ship hooks (probed once PER PATH — kinds may point at different
-    // hooks via ship.via; fixing a hook needs a studio restart) ────────────
+    // ── ship hooks: a kind's BUILT-IN ship.fn (e.g. identityKinds re-rendering
+    // the set from the pick) wins; otherwise the repo module is probed once
+    // PER PATH (ship.via, default .rv-assets/ship.ts; fixing a hook needs a
+    // studio restart) ───────────────────────────────────────────────────────
     const shipFns = new Map<string, ShipFn | null>()
-    const ship = async (f: FoundAsset, roll: string): Promise<{ shipped: string | null }> => {
+    const resolveShipFn = async (f: FoundAsset): Promise<ShipFn | null> => {
+        if (f.kind.ship?.fn != null) return f.kind.ship.fn
         const shipPath = join(root, f.kind.ship?.via ?? '.rv-assets/ship.ts')
         let fn = shipFns.get(shipPath)
         if (fn === undefined) {
@@ -118,6 +157,10 @@ export async function serveStudio(deps: StudioDeps): Promise<Studio> {
             } else fn = null
             shipFns.set(shipPath, fn)
         }
+        return fn ?? null
+    }
+    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
         const dir = dirOf(f.asset.id)
         const g = geometryOf(f)
@@ -139,222 +182,231 @@ export async function serveStudio(deps: StudioDeps): Promise<Studio> {
     const bad = (msg: string): Response => json({ error: msg }, 400)
     const safeRoll = (name: unknown): string | null => (typeof name === 'string' && isRollFile(name) ? name : null)
 
-    const server = Bun.serve({
-        hostname: '127.0.0.1',
-        port: kit.port,
-        async fetch(req) {
-            const url = new URL(req.url)
-            const q = (k: string): string => url.searchParams.get(k) ?? ''
-            const body = async (): Promise<Record<string, unknown>> => (await req.json().catch(() => ({}))) as Record<string, unknown>
-
-            if (url.pathname === '/') return new Response(deps.page(), { headers: { 'Content-Type': 'text/html; charset=utf-8' } })
+    const handle = async (req: Request, pathname: string): Promise<Response> => {
+    const url = new URL(req.url)
+        const q = (k: string): string => url.searchParams.get(k) ?? ''
+        const body = async (): Promise<Record<string, unknown>> => (await req.json().catch(() => ({}))) as Record<string, unknown>
 
-            if (url.pathname === '/api/state') {
-                const assets = await Promise.all(allAssets(kit).map(async (f) => {
-                    const dir = dirOf(f.asset.id)
-                    const pick = await readPick(dir)
-                    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',
-                    }
-                }))
-                return json({ ...queue.state, queued: queue.queuedCount, errors: queue.errors.slice(-5), assets })
-            }
+        if (pathname === '/') return new Response(deps.page(), { headers: { 'Content-Type': 'text/html; charset=utf-8' } })
 
-            if (url.pathname === '/api/asset') {
-                const f = findAsset(kit, q('id'))
-                if (f == null) return bad(`unknown asset '${q('id')}'`)
+        if (pathname === '/api/state') {
+            const assets = await Promise.all(allAssets(kit).map(async (f) => {
                 const dir = dirOf(f.asset.id)
                 const pick = await readPick(dir)
-                const rolls = listRolls(dir).map((name) => ({ name, picked: name === pick.pick, alt: pick.alts.includes(name), hasMeta: existsSync(metaPath(dir, name)) }))
-                const custom = customPanelsOf(f).map((p) => ({ id: p.id, kind: f.kind.id, url: `/panel/${encodeURIComponent(f.kind.id)}/${encodeURIComponent(p.id)}.js` }))
-                return json({ asset: { ...f.asset, prompt: await promptOf(f), cat: f.kind.category, geometry: geometryOf(f) != null, custom }, rolls, pick })
-            }
+                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',
+                }
+            }))
+            return json({ ...queue.state, queued: queue.queuedCount, errors: queue.errors.slice(-5), assets })
+        }
 
-            if (url.pathname.startsWith('/panel/')) {
-                // repo-defined editor module; ids resolved against the kit — the
-                // URL never reaches the filesystem directly
-                const m = url.pathname.match(/^\/panel\/([^/]+)\/([^/]+)\.js$/)
-                const kind = m == null ? null : (kit.kinds.find((k) => k.id === decodeURIComponent(m[1]!)) ?? null)
-                const spec = kind?.meta?.panels?.find((p): p is CustomPanelSpec => p.panel === 'custom' && p.id === decodeURIComponent(m![2]!))
-                if (spec == null) return new Response('', { status: 404 })
-                const file = Bun.file(join(root, spec.script))
-                if (!(await file.exists())) return new Response(`// ${spec.script} vanished after studio boot — restore it`, { status: 404 })
-                return new Response(file, { headers: { 'Content-Type': 'text/javascript; charset=utf-8' } })
-            }
+        if (pathname === '/api/asset') {
+            const f = findAsset(kit, q('id'))
+            if (f == null) return bad(`unknown asset '${q('id')}'`)
+            const dir = dirOf(f.asset.id)
+            const pick = await readPick(dir)
+            const rolls = listRolls(dir).map((name) => ({ name, picked: name === pick.pick, alt: pick.alts.includes(name), hasMeta: existsSync(metaPath(dir, name)) }))
+            const custom = customPanelsOf(f).map((p) => ({ id: p.id, kind: f.kind.id, url: `./panel/${encodeURIComponent(f.kind.id)}/${encodeURIComponent(p.id)}.js` }))
+            return json({ asset: { ...f.asset, prompt: await promptOf(f), cat: f.kind.category, geometry: geometryOf(f) != null, custom }, info: infoOf(f), rolls, pick })
+        }
 
-            if (url.pathname === '/img') {
-                const name = safeRoll(q('name'))
-                const f = findAsset(kit, q('id'))
-                if (f == null || name == null) return new Response('', { status: 404 })
-                const file = Bun.file(join(dirOf(f.asset.id), name))
-                return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
-            }
+        if (pathname.startsWith('/panel/')) {
+            // repo-defined editor module; ids resolved against the kit — the
+            // URL never reaches the filesystem directly
+            const m = pathname.match(/^\/panel\/([^/]+)\/([^/]+)\.js$/)
+            const kind = m == null ? null : (kit.kinds.find((k) => k.id === decodeURIComponent(m[1]!)) ?? null)
+            const spec = kind?.meta?.panels?.find((p): p is CustomPanelSpec => p.panel === 'custom' && p.id === decodeURIComponent(m![2]!))
+            if (spec == null) return new Response('', { status: 404 })
+            const file = Bun.file(join(root, spec.script))
+            if (!(await file.exists())) return new Response(`// ${spec.script} vanished after studio boot — restore it`, { status: 404 })
+            return new Response(file, { headers: { 'Content-Type': 'text/javascript; charset=utf-8' } })
+        }
 
-            if (url.pathname === '/api/thumb') {
-                const f = findAsset(kit, q('id'))
-                if (f == null) return new Response('', { status: 404 })
-                const dir = dirOf(f.asset.id)
-                const pick = await readPick(dir)
-                const name = pick.pick ?? listRolls(dir)[0]
-                if (name == null) return new Response('', { status: 404 })
-                const file = Bun.file(join(dir, name))
-                return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
-            }
+        if (pathname === '/img') {
+            const name = safeRoll(q('name'))
+            const f = findAsset(kit, q('id'))
+            if (f == null || name == null) return new Response('', { status: 404 })
+            const file = Bun.file(join(dirOf(f.asset.id), name))
+            return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
+        }
 
-            if (url.pathname === '/api/rect' && req.method === 'GET') {
-                const f = findAsset(kit, q('id'))
-                const name = safeRoll(q('name'))
-                if (f == null || name == null) return bad('bad id/name')
-                if (geometryOf(f) == null) return bad(`kind '${f.kind.id}' has no geometry panel`)
-                return json({ rect: await sessionRect(f, name) })
-            }
+        if (pathname === '/api/thumb') {
+            const f = findAsset(kit, q('id'))
+            if (f == null) return new Response('', { status: 404 })
+            const dir = dirOf(f.asset.id)
+            const pick = await readPick(dir)
+            const name = pick.pick ?? listRolls(dir)[0]
+            if (name == null) return new Response('', { status: 404 })
+            const file = Bun.file(join(dir, name))
+            return (await file.exists()) ? new Response(file) : new Response('', { status: 404 })
+        }
 
-            if (url.pathname === '/api/catrects') {
-                const rows = []
-                for (const f of allAssets(kit).filter((x) => x.kind.category === q('cat'))) {
-                    const dir = dirOf(f.asset.id)
-                    const rolls = listRolls(dir)
-                    if (rolls.length === 0) continue
-                    const pick = await readPick(dir)
-                    const name = pick.pick ?? rolls[0]!
-                    const icon = f.kind.mode === 'icon'
-                    let rect: GroundRect | null = null
-                    if (!icon && geometryOf(f) != null) {
-                        rect = await sessionRect(f, name)
-                        if (f.kind.meta?.artNormalized === true && rect.art == null) {
-                            const img = join(dir, name)
-                            if (existsSync(img)) rect.art = await alphaHeight(img)
-                        }
+        if (pathname === '/api/rect' && req.method === 'GET') {
+            const f = findAsset(kit, q('id'))
+            const name = safeRoll(q('name'))
+            if (f == null || name == null) return bad('bad id/name')
+            if (geometryOf(f) == null) return bad(`kind '${f.kind.id}' has no geometry panel`)
+            return json({ rect: await sessionRect(f, name) })
+        }
+
+        if (pathname === '/api/catrects') {
+            const rows = []
+            for (const f of allAssets(kit).filter((x) => x.kind.category === q('cat'))) {
+                const dir = dirOf(f.asset.id)
+                const rolls = listRolls(dir)
+                if (rolls.length === 0) continue
+                const pick = await readPick(dir)
+                const name = pick.pick ?? rolls[0]!
+                const icon = f.kind.mode === 'icon'
+                let rect: GroundRect | null = null
+                if (!icon && geometryOf(f) != null) {
+                    rect = await sessionRect(f, name)
+                    if (f.kind.meta?.artNormalized === true && rect.art == null) {
+                        const img = join(dir, name)
+                        if (existsSync(img)) rect.art = await alphaHeight(img)
                     }
-                    rows.push({ id: f.asset.id, label: f.asset.label ?? f.asset.id, name, rect, prop: f.kind.meta?.artNormalized === true, icon })
                 }
-                return json({ rows })
+                rows.push({ id: f.asset.id, label: f.asset.label ?? f.asset.id, name, rect, prop: f.kind.meta?.artNormalized === true, icon })
             }
+            return json({ rows })
+        }
 
-            if (req.method !== 'POST') return new Response('', { status: 404 })
-            const b = await body()
+        if (req.method !== 'POST') return new Response('', { status: 404 })
+        const b = await body()
 
-            if (url.pathname === '/api/generate') {
-                const f = findAsset(kit, String(b.id))
-                if (f == null) return bad(`unknown asset '${String(b.id)}'`)
-                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 (url.pathname === '/api/generate-cat') {
-                const hit = allAssets(kit).filter((f) => f.kind.category === b.cat)
-                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 }))))
-                return json({ ok: true })
-            }
-            if (url.pathname === '/api/queue/clear') {
-                queue.clear()
-                return json({ ok: true })
-            }
-            if (url.pathname === '/api/pick') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                const dir = dirOf(f.asset.id)
-                try {
-                    const res = await ship(f, name)
-                    await updatePick(dir, (s) => {
-                        s.pick = name
-                        s.shippedAt = res.shipped != null ? new Date().toISOString() : s.shippedAt
-                    })
-                    return json(res)
-                } catch (e) {
-                    queue.pushError(`ship ${String(b.id)}: ${(e as Error).message}`)
-                    return json({ error: (e as Error).message }, 500)
-                }
-            }
-            if (url.pathname === '/api/alt') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                await updatePick(dirOf(f.asset.id), (s) => {
-                    s.alts = s.alts.includes(name) ? s.alts.filter((a) => a !== name) : [...s.alts, name]
-                })
-                return json({ ok: true })
-            }
-            if (url.pathname === '/api/discard') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                const dir = dirOf(f.asset.id)
-                for (const path of [join(dir, name), metaPath(dir, name), rectPath(f.asset.id, name)]) if (existsSync(path)) unlinkSync(path)
+        if (pathname === '/api/generate') {
+            const f = findAsset(kit, String(b.id))
+            if (f == null) return bad(`unknown asset '${String(b.id)}'`)
+            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)
+            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 }))))
+            return json({ ok: true })
+        }
+        if (pathname === '/api/queue/clear') {
+            queue.clear()
+            return json({ ok: true })
+        }
+        if (pathname === '/api/pick') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            const dir = dirOf(f.asset.id)
+            try {
+                const res = await ship(f, name)
                 await updatePick(dir, (s) => {
-                    if (s.pick === name) s.pick = null
-                    s.alts = s.alts.filter((a) => a !== name)
+                    s.pick = name
+                    s.shippedAt = res.shipped != null ? new Date().toISOString() : s.shippedAt
                 })
-                return json({ ok: true })
-            }
-            if (url.pathname === '/api/prompt') {
-                if (typeof b.prompt !== 'string') return bad('prompt must be a string')
-                const f = findAsset(kit, String(b.id))
-                if (f == null) return bad(`unknown asset '${String(b.id)}'`)
-                // structure is git-reviewed TS; the studio edits the OVERLAY
-                await updatePromptOverlay(dirOf(f.asset.id), (s) => { s.prompt = (b.prompt as string) === f.asset.prompt ? null : (b.prompt as string) })
-                return json({ ok: true })
-            }
-            if (url.pathname === '/api/rect') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                if (typeof b.rect !== 'object' || b.rect == null) return bad('rect must be an object')
-                const res = await saveRect(f, name, b.rect as Record<string, unknown>)
-                return 'errors' in res ? bad(res.errors.join('; ')) : json({ ok: true, rect: res.rect })
+                return json(res)
+            } catch (e) {
+                queue.pushError(`ship ${String(b.id)}: ${(e as Error).message}`)
+                return json({ error: (e as Error).message }, 500)
             }
-            if (url.pathname === '/api/legs-default') {
-                // legs derived server-side so the SPA never duplicates the constants
-                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)
-                if (current.legs == null) {
-                    current.legs = legDefaults(current)
-                    current.legColor ??= '#c8a070'
-                    const res = await saveRect(f, name, current as unknown as Record<string, unknown>)
-                    if ('errors' in res) return bad(res.errors.join('; '))
-                    return json({ ok: true, rect: res.rect })
-                }
-                return json({ ok: true, rect: current }) // non-destructive: existing legs never replaced
-            }
-            if (url.pathname === '/api/flip') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                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)
+        }
+        if (pathname === '/api/alt') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            await updatePick(dirOf(f.asset.id), (s) => {
+                s.alts = s.alts.includes(name) ? s.alts.filter((a) => a !== name) : [...s.alts, name]
+            })
+            return json({ ok: true })
+        }
+        if (pathname === '/api/discard') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            const dir = dirOf(f.asset.id)
+            for (const path of [join(dir, name), metaPath(dir, name), rectPath(f.asset.id, name)]) if (existsSync(path)) unlinkSync(path)
+            await updatePick(dir, (s) => {
+                if (s.pick === name) s.pick = null
+                s.alts = s.alts.filter((a) => a !== name)
+            })
+            return json({ ok: true })
+        }
+        if (pathname === '/api/prompt') {
+            if (typeof b.prompt !== 'string') return bad('prompt must be a string')
+            const f = findAsset(kit, String(b.id))
+            if (f == null) return bad(`unknown asset '${String(b.id)}'`)
+            // structure is git-reviewed TS; the studio edits the OVERLAY
+            await updatePromptOverlay(dirOf(f.asset.id), (s) => { s.prompt = (b.prompt as string) === f.asset.prompt ? null : (b.prompt as string) })
+            return json({ ok: true })
+        }
+        if (pathname === '/api/rect') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            if (typeof b.rect !== 'object' || b.rect == null) return bad('rect must be an object')
+            const res = await saveRect(f, name, b.rect as Record<string, unknown>)
+            return 'errors' in res ? bad(res.errors.join('; ')) : json({ ok: true, rect: res.rect })
+        }
+        if (pathname === '/api/legs-default') {
+            // legs derived server-side so the SPA never duplicates the constants
+            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)
+            if (current.legs == null) {
+                current.legs = legDefaults(current)
+                current.legColor ??= '#c8a070'
+                const res = await saveRect(f, name, current as unknown as Record<string, unknown>)
                 if ('errors' in res) return bad(res.errors.join('; '))
-                // flipping the CURRENT pick re-ships mirrored pixels
-                const pick = await readPick(dirOf(f.asset.id))
-                if (pick.pick === name) await ship(f, name).catch((e: Error) => queue.pushError(`re-ship ${f.asset.id}: ${e.message}`))
-                return json({ ok: true, flip: res.rect.flip === true })
+                return json({ ok: true, rect: res.rect })
             }
-            if (url.pathname === '/api/meta') {
-                const name = safeRoll(b.name)
-                const f = findAsset(kit, String(b.id))
-                if (name == null || f == null) return bad('bad id/name')
-                const path = metaPath(dirOf(f.asset.id), name)
-                if (b.text === undefined) return json({ text: existsSync(path) ? await Bun.file(path).text() : '' })
-                try {
-                    const parsed: unknown = JSON.parse(String(b.text))
-                    await Bun.write(path, JSON.stringify(parsed, null, 2) + '\n') // meta sidecars have a single writer (this route)
-                    return json({ ok: true })
-                } catch (e) {
-                    return bad(`not valid JSON: ${(e as Error).message}`)
-                }
+            return json({ ok: true, rect: current }) // non-destructive: existing legs never replaced
+        }
+        if (pathname === '/api/flip') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            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)
+            if ('errors' in res) return bad(res.errors.join('; '))
+            // flipping the CURRENT pick re-ships mirrored pixels
+            const pick = await readPick(dirOf(f.asset.id))
+            if (pick.pick === name) await ship(f, name).catch((e: Error) => queue.pushError(`re-ship ${f.asset.id}: ${e.message}`))
+            return json({ ok: true, flip: res.rect.flip === true })
+        }
+        if (pathname === '/api/meta') {
+            const name = safeRoll(b.name)
+            const f = findAsset(kit, String(b.id))
+            if (name == null || f == null) return bad('bad id/name')
+            const path = metaPath(dirOf(f.asset.id), name)
+            if (b.text === undefined) return json({ text: existsSync(path) ? await Bun.file(path).text() : '' })
+            try {
+                const parsed: unknown = JSON.parse(String(b.text))
+                await Bun.write(path, JSON.stringify(parsed, null, 2) + '\n') // meta sidecars have a single writer (this route)
+                return json({ ok: true })
+            } catch (e) {
+                return bad(`not valid JSON: ${(e as Error).message}`)
             }
-            return new Response('', { status: 404 })
-        },
-    })
+        }
+        return new Response('', { status: 404 })
+    }
+
+    return { handle, queue }
+}
 
-    return { server, queue, stop: () => server.stop(true) }
+// standalone studio server (`shipkit assets serve`): the same routes on
+// their own port. The hub (`shipkit serve`) mounts studioRoutes under
+// /assets/ instead — one route table, two front doors.
+export async function serveStudio(deps: StudioDeps): Promise<Studio> {
+    const routes = await studioRoutes(deps)
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: deps.kit.port,
+        fetch: (req) => routes.handle(req, new URL(req.url).pathname),
+    })
+    return { server, queue: routes.queue, stop: () => server.stop(true) }
 }

package/src/cli/cmd_Serve.ts

@@ -0,0 +1,34 @@
+// shipkit serve — the ONE hub server per repo (one vscode folder-open task,
+// clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
+import { Command, Option } from 'clipanion'
+import { runServe } from '../serve/run-serve.ts'
+
+export class ServeCommand extends Command {
+    static override paths = [['serve']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'ONE hub server per repo: landing page linking the wiki/agent graphs, the assets studio, and live status',
+        examples: [
+            ['serve the repo toolbox', 'shipkit serve'],
+            ['pin the port for this launch', 'shipkit serve --port 4804'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'hub port (default: repo.config serve.port, else hashed from the repo name into 4800-4979)' })
+
+    async execute(): Promise<number> {
+        let port: number | undefined
+        if (this.port != null) {
+            port = Number(this.port)
+            if (!Number.isInteger(port) || port <= 0) {
+                this.context.stderr.write(`FAIL --port '${this.port}' is not a port number\n`)
+                return 1
+            }
+        }
+        return runServe(process.cwd(), {
+            print: (l) => this.context.stdout.write(`${l}\n`),
+            printErr: (l) => this.context.stderr.write(`${l}\n`),
+        }, { port })
+    }
+}

package/src/cli.ts

@@ -10,6 +10,7 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
+import { ServeCommand } from './cli/cmd_Serve.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -28,6 +29,7 @@ cli.register(Builtins.VersionCommand)
 cli.register(CiCommand)
 cli.register(CheckCommand)
 cli.register(TuiCommand)
+cli.register(ServeCommand)
 cli.register(ContractsCommand)
 cli.register(AsksCommand)
 cli.register(AsksCheckCommand)