rvlib-shipkit 0.11.0 → 0.14.0

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

@@ -0,0 +1,299 @@
+// Media views — topbar, info chips, stage (image/audio + geometry), roll
+// strip, category grid + size-true lineup, drawer (asset json · roll meta ·
+// repo-defined custom panels). Feature parity with the deleted vanilla
+// studio SPA; state lives in MediaSvc (components read and call).
+import { runInAction } from 'mobx'
+import { observer } from 'mobx-react-lite'
+import { useEffect, useRef, useState, type DragEvent, type ReactNode } from 'react'
+import type { HubSt } from './hub-st.ts'
+import { isAud, rollUrl, thumbUrl } from './media-svc.ts'
+import { GeometryLayer, Rectbar, measureBox, type Box } from './geometry-view.tsx'
+import type { CatRow } from './hub-types.ts'
+
+const TEX = 1024
+const MIX_UNIT = 24
+const MIX_GROUND = 44
+
+export const MediaTopbar = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const fileRef = useRef<HTMLInputElement>(null)
+    const taRef = useRef<HTMLTextAreaElement>(null)
+    const manual = m.cur?.manual === true
+    const det = m.deterministic
+    // auto-grow on EVERY prompt change, programmatic (selection) included —
+    // the css max-height caps it, overflow scrolls only past ~14 lines
+    useEffect(() => {
+        const t = taRef.current
+        if (t == null) return
+        t.style.height = 'auto'
+        t.style.height = `${t.scrollHeight + 2}px`
+    }, [m.prompt])
+    return (
+        <div className="bar">
+            {/* the prompt AUTOSAVES (debounced) — no save button, no fear */}
+            <textarea className="prompt" ref={taRef} value={m.prompt} placeholder="select an asset ←"
+                onChange={(e) => m.setPrompt(e.target.value)} />
+            <div className="toolbar">
+                {!manual ? <button disabled={m.curId == null} onClick={() => void m.generate()}>Generate</button> : null}
+                {!manual ? (
+                    <label className="xn" title="rolls per generate">×
+                        <select value={m.n} disabled={det} onChange={(e) => runInAction(() => { m.n = e.target.value })}>
+                            {['1', '3', '6', '9', '12'].map((v) => <option key={v}>{v}</option>)}
+                        </select>
+                    </label>
+                ) : null}
+                <button className="ghost" title="add files as rolls (or drag-drop onto the strip)" onClick={() => fileRef.current?.click()}>upload</button>
+                <input type="file" ref={fileRef} multiple style={{ display: 'none' }}
+                    accept={m.cur?.media === 'audio' ? '.mp3,.wav,.ogg,.m4a' : '.png,.webp'}
+                    onChange={(e) => { if (e.target.files != null) void m.upload(e.target.files); e.target.value = '' }} />
+                <button className="ghost" title="copy the prompt" onClick={() => m.copyPrompt()}>copy</button>
+                {det || manual ? <span className="detnote">{manual ? 'manual — upload files (drag-drop works)' : 'deterministic — rolls identical'}</span> : null}
+                <span className="sp" />
+                {m.generating ? <button className="ghost" title="interrupt the current job (queued jobs stay)" onClick={() => m.stopCurrent()}>stop current</button> : null}
+                {m.queued > 0 ? <button className="ghost" title="drop queued jobs" onClick={() => m.clearQueue()}>clear queue ({m.queued})</button> : null}
+                {m.generating && m.progress?.max ? (
+                    <span className="progbar"><i style={{ width: `${Math.round((100 * m.progress.value) / m.progress.max)}%` }} /></span>
+                ) : null}
+                <span className="status">{m.promptMsg !== '' ? m.promptMsg : m.generating ? m.genLine : m.statusLine}</span>
+            </div>
+        </div>
+    )
+})
+
+export const InfoChips = observer(({ app }: { app: HubSt }) => {
+    const info = app.media.detail?.info
+    if (info == null) return null
+    const chips: { k: string; v: ReactNode; warn?: boolean }[] = [{ k: 'backend', v: info.backend }]
+    if (info.workflow != null) {
+        const w = info.workflow
+        if (w.id != null) chips.push({ k: 'workflow', v: <>{w.id}{w.path != null ? <> <code>{w.path}</code></> : null}</> })
+        else chips.push({ k: 'workflow', v: w.note ?? 'unresolved', warn: true })
+    }
+    const sh = info.ship
+    chips.push({ k: 'ship', v: sh.mode === 'hook' ? <code>{sh.path}</code> : sh.mode === 'built-in' ? `built-in hook — ${sh.note ?? ''}` : sh.note ?? 'pick.json only' })
+    if (info.metaFile != null) chips.push({ k: 'meta', v: <code>{info.metaFile}</code> })
+    chips.push({ k: 'kit', v: <><code>{info.kitSource}</code> · {info.kindId}</> })
+    return (
+        <div className="info" style={{ display: 'flex' }}>
+            {chips.map((c, i) => <span key={i} className={`chip${c.warn === true ? ' warn' : ''}`}><b>{c.k}</b> {c.v}</span>)}
+        </div>
+    )
+})
+
+export const AssetStage = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const stageRef = useRef<HTMLDivElement>(null)
+    const imgRef = useRef<HTMLImageElement>(null)
+    const [box, setBox] = useState<Box | null>(null)
+    const remeasure = (): void => setBox(measureBox(stageRef.current, imgRef.current))
+    useEffect(() => {
+        window.addEventListener('resize', remeasure)
+        return () => window.removeEventListener('resize', remeasure)
+    }, [])
+    const rolls = m.detail?.rolls ?? []
+    const genHere = m.curId != null && m.pending.includes(m.curId)
+    const shown = m.hover ?? m.active
+    let content: ReactNode
+    if (shown == null) content = <div className="ph">{genHere ? 'generating…' : rolls.length === 0 ? 'no rolls yet' : 'Pick an asset on the left, then Generate.'}</div>
+    else if (isAud(shown)) content = (
+        // key = the roll identity: heartbeats re-render but never recreate
+        // the element, so playback survives; the src carries no cache-bust
+        <div className="stageaud" key={`${m.curId}/${shown}`}>🔊<audio controls src={rollUrl(m.curId!, shown)} /></div>
+    )
+    else content = <img className="roll" src={rollUrl(m.curId!, shown)} ref={imgRef} onLoad={remeasure} />
+    return (
+        <div className="stage" ref={stageRef}>
+            {content}
+            {shown != null && !isAud(shown) ? <GeometryLayer app={app} box={box} /> : null}
+            <Rectbar app={app} />
+        </div>
+    )
+})
+
+export const RollStrip = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const rolls = m.detail?.rolls ?? []
+    const genHere = m.curId != null && m.pending.includes(m.curId)
+    const onDrop = (e: DragEvent<HTMLDivElement>): void => { e.preventDefault(); void m.upload(e.dataTransfer.files) }
+    if (rolls.length === 0) return (
+        <div className="strip" onDragOver={(e) => e.preventDefault()} onDrop={onDrop}>
+            {genHere ? <div className="vig gen"><div className="spin" />generating…</div>
+                : <div className="ph">{m.cur?.manual === true ? 'no files — upload (or drag-drop here)' : 'no rolls — hit Generate'}</div>}
+        </div>
+    )
+    return (
+        <div className="strip" onDragOver={(e) => e.preventDefault()} onDrop={onDrop}>
+            {/* rolls are newest-first; generation lands where the eye is */}
+            {genHere ? <div className="vig gen"><div className="spin" />generating…</div> : null}
+            {rolls.map((x) => (
+                <div key={x.name}
+                    className={`vig${isAud(x.name) ? ' aud' : ''}${x.name === m.active ? ' active' : ''}${x.picked ? ' picked' : ''}${x.alt ? ' alt' : ''}`}
+                    // hover-preview stays image-only — swapping an <audio> mid-playback would cut the sound
+                    onMouseEnter={() => { if (!isAud(x.name)) runInAction(() => { m.hover = x.name }) }}
+                    onMouseLeave={() => runInAction(() => { m.hover = null })}
+                    onClick={() => m.setActive(x.name)}>
+                    {isAud(x.name) ? <>🔊<audio controls src={rollUrl(m.curId!, x.name)} /></> : <img src={rollUrl(m.curId!, x.name)} />}
+                    {x.picked ? <span className="st">★</span> : null}
+                    <div className="btns">
+                        <button className="b-pick" onClick={(e) => { e.stopPropagation(); void m.pick(x.name) }}>pick</button>
+                        <button className="b-alt" onClick={(e) => { e.stopPropagation(); void m.alt(x.name) }}>alt</button>
+                        <button className="b-del" onClick={(e) => { e.stopPropagation(); void m.discard(x.name) }}>✕</button>
+                    </div>
+                </div>
+            ))}
+        </div>
+    )
+})
+
+// ── category grid + size-true lineup ─────────────────────────────────────
+const MixLineup = observer(({ rows }: { rows: CatRow[] }) => {
+    const items = rows.filter((r) => !r.icon && r.rect != null).sort((a, b) => a.rect!.size - b.rect!.size || a.label.localeCompare(b.label))
+    const boxH = 420
+    const baseY = boxH - MIX_GROUND
+    let cx = 30
+    const sprites: ReactNode[] = []
+    for (const it of items) {
+        const rect = it.rect!
+        const ts = (rect.size * MIX_UNIT) / rect.w
+        const slot = Math.max(rect.size * MIX_UNIT * 1.35, TEX * ts * 0.62, 40)
+        cx += slot / 2
+        const fx = rect.flip === true ? TEX - rect.x - rect.w : rect.x
+        sprites.push(
+            <img key={it.id} className="mixsprite" src={thumbUrl(it.id)} style={{
+                width: TEX * ts, height: TEX * ts,
+                left: cx - (fx + rect.w / 2) * ts, top: baseY - (rect.y + rect.h / 2) * ts,
+                transform: rect.flip === true ? 'scaleX(-1)' : undefined, zIndex: Math.round(cx),
+            }} />,
+            <div key={`${it.id}-lb`} className="mixlabel" style={{ left: cx, bottom: 14 }}>{it.label} · {+rect.size.toFixed(2)}</div>,
+        )
+        cx += slot / 2 + 10
+    }
+    const rulers: ReactNode[] = []
+    for (let u = 5; u * MIX_UNIT < baseY; u += 5)
+        rulers.push(<div key={u} className={`rlabel${u % 10 === 0 ? ' b' : ''}`} style={{ bottom: MIX_GROUND + u * MIX_UNIT - 5 }}>{u}</div>)
+    return (
+        <div id="mixsec"><div id="mixbox"><div id="mixinner" style={{ width: cx + 30, minWidth: '100%' }}>
+            <div className="ruler" />
+            <div id="mixground" />
+            {sprites}{rulers}
+        </div></div></div>
+    )
+})
+
+export const CatGrid = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const cat = m.catMode
+    if (cat == null) return null
+    const pc = (v: number): string => `${v / (TEX / 100)}%`
+    return (
+        <div id="catgrid" style={{ display: 'block' }}>
+            <div id="allbar">
+                <label>size for ALL {cat} <input type="number" step={0.1} min={0.1} value={m.allSize}
+                    onChange={(e) => runInAction(() => { m.allSize = e.target.value })} /></label>
+                <button className="ghost" onClick={() => void m.applyAllSize()}>apply</button>
+                <span className="jmsg">{m.allMsg}</span>
+            </div>
+            <div className="cards">
+                {m.catRows.map((row) => {
+                    const fl = row.rect?.flip === true
+                    return (
+                        // the WHOLE card jumps into the asset (his order
+                        // 2026-07-23) — inner controls stopPropagation
+                        <div className="card" key={row.id} onClick={() => app.selectAsset(row.id)}>
+                            {isAud(row.name)
+                                ? <div className="aud">🔊<audio controls src={rollUrl(row.id, row.name)} onClick={(e) => e.stopPropagation()} />{m.pending.includes(row.id) ? <div className="spin" /> : null}</div>
+                                : <div className="th">
+                                    <img src={thumbUrl(row.id)} style={fl ? { transform: 'scaleX(-1)' } : undefined} />
+                                    {row.rect != null ? <div className="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),
+                                    }} /> : null}
+                                    {m.pending.includes(row.id) ? <div className="spin" /> : null}
+                                </div>}
+                            <div className="nm">{row.label}</div>
+                            {row.icon || isAud(row.name) ? null : (
+                                <div className="row" onClick={(e) => e.stopPropagation()}>
+                                    {/* commit-on-blur/Enter like the vanilla onchange (one POST,
+                                        not one per keystroke); the size in the key remounts the
+                                        input when apply-all changes it programmatically */}
+                                    <label>size <input key={`${row.id}:${row.rect?.size ?? 1}`} type="number" step={0.1} min={0.1}
+                                        defaultValue={row.rect?.size ?? 1}
+                                        onBlur={(e) => void m.setSize(row.id, row.name, +e.target.value)}
+                                        onKeyDown={(e) => { if (e.key === 'Enter') (e.target as HTMLInputElement).blur() }} /></label>
+                                    <button className="ghost" onClick={() => void m.toggleFlip(row.id, row.name)}>⇆ flip</button>
+                                </div>
+                            )}
+                        </div>
+                    )
+                })}
+            </div>
+            <MixLineup rows={m.catRows} />
+        </div>
+    )
+})
+
+// ── drawer: asset json (read-only) · roll meta · custom panels ───────────
+const PanelHost = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const ref = useRef<HTMLDivElement>(null)
+    const c = m.detail?.asset.custom.find((x) => `c:${x.id}` === m.tab) ?? null
+    const key = `${m.curId}|${m.active}|${c?.id ?? ''}`
+    useEffect(() => {
+        const host = ref.current
+        if (host == null) return
+        if (c == null || m.curId == null || m.active == null) {
+            host.textContent = c == null ? 'panel not on this asset' : 'no roll selected — generate or pick one first'
+            return
+        }
+        let dead = false
+        let mod: Record<string, unknown> | null = null
+        void (async () => {
+            try {
+                // repo-defined editor module, served by the media API
+                mod = (await import(`/media/${c.url}`)) as Record<string, unknown>
+                if (typeof mod.mount !== 'function') throw new Error(`${c.url} must export mount(el, api)`)
+                if (!dead) await (mod.mount as (el: HTMLElement, api: unknown) => unknown)(host, m.panelApi(c))
+            } catch (e) {
+                host.textContent = `panel FAILED: ${(e as Error).message}` // loud in the drawer, never blank
+            }
+        })()
+        return () => {
+            dead = true
+            if (typeof mod?.unmount === 'function') void (mod.unmount as () => unknown)()
+            host.innerHTML = ''
+        }
+    }, [key])
+    return <div ref={ref} />
+})
+
+export const Drawer = observer(({ app }: { app: HubSt }) => {
+    const m = app.media
+    const customs = m.detail?.asset.custom ?? []
+    const isCustom = m.tab.startsWith('c:')
+    return (
+        <div className="drawer">
+            <div className="tabs">
+                {[{ id: 'asset', label: 'asset' }, { id: 'meta', label: 'roll meta' }, ...customs.map((c) => ({ id: `c:${c.id}`, label: c.id }))].map((t) => (
+                    <button key={t.id} className={m.tab === t.id ? 'on' : ''} onClick={() => m.setTab(t.id)}>{t.label}</button>
+                ))}
+                <span className="sp" />
+                <button className="ghost" onClick={() => runInAction(() => { m.drawerOpen = !m.drawerOpen })}>JSON ▾</button>
+            </div>
+            {m.drawerOpen ? (
+                <div id="drawerbody" className="on">
+                    {isCustom ? <PanelHost app={app} /> : (
+                        <div>
+                            <textarea id="jsonta" spellCheck={false} readOnly={m.tab === 'asset'} value={m.jsonText}
+                                onChange={(e) => runInAction(() => { m.jsonText = e.target.value })} />
+                            <div className="jrow">
+                                {/* kind/asset structure is git-reviewed TS — read-only here */}
+                                <button disabled={m.tab === 'asset'} onClick={() => void m.saveMeta()}>save</button>
+                                <span className="jmsg">{m.jsonMsg}</span>
+                            </div>
+                        </div>
+                    )}
+                </div>
+            ) : null}
+        </div>
+    )
+})

package/src/serve/run-serve.ts

@@ -9,9 +9,9 @@ import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
 import { loadKit, type ResolvedKit } from '../assets/kit-config.ts'
-import { page as studioPage } from '../assets/server/studio-page.ts'
 import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
 import { projectNeeds } from '../collections/collection-types.ts'
+import { graphsCollection } from '../collections/graphs.ts'
 import { pingTick } from '../collections/pings.ts'
 import { buildCollections } from '../collections/providers.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
@@ -34,35 +34,47 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     const agentGraph = existsSync(agentRoot)
         ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
         : null
-    let studio: StudioRoutes | null = null
+    // ONE page for every repo (his rule 2026-07-23): the studio ALWAYS
+    // mounts — kit-less repos get an empty media section, never a second
+    // page. A broken kit degrades to the same empty kit, loudly.
     let kit: ResolvedKit | null = null
     if (existsSync(join(root, '.rv-assets/kit.ts'))) {
-        // a broken kit must not take the graphs and status down with it —
-        // WARN + mount everything else
         try {
             kit = await loadKit(root)
-            studio = await studioRoutes({ kit, root, page: studioPage })
         } catch (e) {
-            kit = null
-            io.print(`WARN assets studio not mounted: ${(e as Error).message}`)
+            io.print(`WARN kit not loaded (media section empty): ${(e as Error).message}`)
         }
     }
+    const emptyKit: ResolvedKit = { kinds: [], workspace: '.rv-assets/out' }
+    let studio: StudioRoutes | null = null
+    try {
+        studio = await studioRoutes({ kit: kit ?? emptyKit, root })
+    } catch (e) {
+        io.print(`WARN media API not mounted: ${(e as Error).message}`)
+    }
     const cli = fileURLToPath(new URL('../cli.ts', import.meta.url))
+    const allCollections = () => [
+        ...buildCollections(root, c, kit, { bootVersion: BOOT_VERSION, libVersion }),
+        graphsCollection(root, { customWiki: c.serve?.wikiGraph != null, agentIndex: c.serve?.agentIndex }),
+    ]
+    const port = o?.port ?? c.serve?.port ?? defaultHubPort(c.name)
     return {
         root,
         name: c.name,
-        port: o?.port ?? c.serve?.port ?? defaultHubPort(c.name),
+        port,
         wikiGraph,
         agentGraph,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
-        needs: () => projectNeeds(buildCollections(root, c, kit, { bootVersion: BOOT_VERSION, libVersion })),
+        needs: () => projectNeeds(allCollections()),
+        collections: allCollections,
         asksDir: c.asks?.dir ?? 'asks',
         // RED-only pings while serving; notify command is repo config data.
         // Delivery failure must be LOUD — a silently broken notify path means
         // he assumes no blockers exist
         pingTick: (needs) =>
             pingTick(root, c.asks?.dir ?? 'asks', needs, {
+                link: c.serve?.publicHost != null ? `http://${c.serve.publicHost}:${port}/?f=needs` : undefined,
                 run: (cmd) => {
                     const p = Bun.spawn(cmd, { stdout: 'ignore', stderr: 'pipe' })
                     void p.exited.then(async (code) => {
@@ -95,6 +107,8 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
         const base = `http://localhost:${hub.server.port}`
         io.print(`ok: ${c.name} hub → ${base}`)
         for (const t of hub.tools) io.print(`ok: ${t.label} → ${base}${t.path}`)
+        // the off-machine door (phone, other machines) — publicHost is config
+        if (c.serve?.publicHost != null) io.print(`ok: public → http://${c.serve.publicHost}:${hub.server.port}/`)
         await new Promise(() => {}) // the hub owns the process — never resolve
         return 0
     } catch (e) {

package/src/serve/serve-hub.ts

@@ -1,20 +1,16 @@
-// shipkit serve — ONE hub server per repo, ONE port (his call 2026-07-22:
-// "a single shipkit task in vscode with multiple urls I can click"). The
-// landing page's links are the whole toolbox: /graph/wiki · /graph/agent ·
-// /assets/ (the studio, mounted IN-PROCESS) · /status (STATUS.md + run
-// check). Route logic only — resolving WHAT to mount from repo.config is
-// run-serve.ts's job.
+// shipkit serve — the repo's ONE Bun.serve, serving the ONE page (his
+// rules 2026-07-23: one server per repo, one surface, mobx+react). `/` is
+// the hub app (Bun HTML import — media studio + asks + creds + posts +
+// health + graphs as sections); the studio route table mounts as the media
+// API under /media/*; graph canvases stay as drill-down pages. Route logic
+// only — resolving WHAT to mount from repo.config is run-serve.ts's job.
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
 import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 import type { StudioRoutes } from '../assets/server/studio-server.ts'
-import { appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
-import type { NeedItem } from '../collections/collection-types.ts'
-import { withRail } from './hub-pages.ts'
-// the hub UI is a Bun-native React app (HTML import, no vite, no build) —
-// build/webapp doctrine; legacy pages (graphs, studio SPA) keep the
-// server-injected rail until they migrate
+import { appendAskRemark, appendAssetNote, appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
+import type { Collection, Instance, NeedItem } from '../collections/collection-types.ts'
 import hubIndex from './hub-app/index.html'
 
 export type HubGraph = { title: string; load: () => MdGraph }
@@ -27,13 +23,17 @@ export type HubDeps = {
     wikiGraph: HubGraph
     /** null = no agent/ dir */
     agentGraph: HubGraph | null
-    /** null = no .rv-assets/kit.ts (or it failed to load — caller prints the WARN) */
+    /** the media API (mounted under /media/*); null only if the route
+     *  table failed to build — the page shows the WARN, never a second page */
     studio: StudioRoutes | null
-    /** argv shelling the check run streamed by /status/run (test seam) */
+    /** argv shelling the check run streamed by /api/check/run (test seam) */
     checkCmd: string[]
-    /** the / needs feed — every human-action item, red/yellow, gathered per
-     *  request from the collection providers (run-serve builds it) */
+    /** every human-action item, red/yellow, gathered per request from the
+     *  collection providers (run-serve builds it) */
     needs: () => Promise<NeedItem[]>
+    /** BROWSE-ALL: the collections with every instance incl. healthy —
+     *  the page shows everything that exists (his trust rule) */
+    collections: () => Collection[]
     /** asks dir (repo-root-relative) for the act-in-place ask verbs */
     asksDir: string
     /** RED-only ping tick, called on an interval while serving (null = off) */
@@ -41,28 +41,27 @@ export type HubDeps = {
 }
 export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop: () => void }
 
-// the toolbox as data — the landing page, /hub.json, and the stdout ok:
-// lines all render THIS list, so they can never disagree
-export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph' | 'studio'>): HubTool[] {
-    const tools: HubTool[] = [{ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title }]
+// the toolbox as data — stdout ok: lines and /hub.json render THIS list,
+// so they can never disagree
+export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph'>): HubTool[] {
+    const tools: HubTool[] = [{ path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' }]
+    tools.push({ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title })
     if (d.agentGraph != null) tools.push({ path: '/graph/agent', label: 'agent graph', desc: d.agentGraph.title })
-    if (d.studio != null) tools.push({ path: '/assets/', label: 'assets studio', desc: 'roll, curate, pick, ship' })
-    tools.push({ path: '/status', label: 'status', desc: 'STATUS.md + run check' })
     return tools
 }
 
+// drill-down pages (graph canvases) get one fixed home link back to THE page
+const HOME_LINK = `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
+ background:#17140f;border:1px solid #332b22;border-radius:9px;padding:5px 9px}</style><a class=skhome href="/" title="hub — THE page">⌂</a>`
+const withHome = (html: string): string => html.replace(/<body([^>]*)>/, `<body$1>${HOME_LINK}`)
+
 export function serveHub(d: HubDeps): Hub {
     const tools = hubTools(d)
-    // every HTML page carries the rail — one keystroke between surfaces;
-    // the red dot self-fetches client-side (no collector on passive navs)
-    const shell = (s: string, active: string): Response =>
-        new Response(withRail(s, { tools, active }), { headers: { 'content-type': 'text/html; charset=utf-8' } })
     const server: ReturnType<typeof Bun.serve> = Bun.serve({
         hostname: '127.0.0.1',
         port: d.port,
-        // / (attention dashboard) and /status are the React app — one HTML
-        // bundle, view picked by pathname client-side
-        routes: { '/': hubIndex, '/status': hubIndex },
+        // `/` IS the page — the react app; there is no other surface
+        routes: { '/': hubIndex },
         async fetch(req): Promise<Response> {
             const path = new URL(req.url).pathname
             // identity probe: lets a second launch tell "same repo, another
@@ -72,9 +71,22 @@ export function serveHub(d: HubDeps): Hub {
                 const needs = await d.needs().catch((e: Error) => [{ collection: 'hub', id: 'hub:broken', text: `needs projection broke: ${e.message}`, severity: 'red' as const }])
                 return Response.json({ needs })
             }
+            if (path === '/api/collections.json') {
+                // browse-all: every instance of every collection, healthy
+                // included — failure-isolated per collection
+                const out: { id: string; title: string; media: string; instances: Instance[] }[] = []
+                for (const col of d.collections()) {
+                    try {
+                        out.push({ id: col.id, title: col.title, media: col.media, instances: await col.list() })
+                    } catch (e) {
+                        out.push({ id: col.id, title: col.title, media: col.media, instances: [{ id: `${col.id}:broken`, text: `collector broke: ${(e as Error).message}`, severity: 'red' }] })
+                    }
+                }
+                return Response.json({ collections: out })
+            }
             if (path.startsWith('/api/act/') && req.method === 'POST') {
                 // act-in-place verbs — every mutation hits a git-tracked truth
-                // file; errors surface as 400 text the tile shows verbatim
+                // file; errors surface as 400 text the card shows verbatim
                 try {
                     const b = (await req.json()) as Record<string, string>
                     if (path === '/api/act/ask-done') askDone(d.root, d.asksDir, b.file ?? '')
@@ -86,6 +98,16 @@ export function serveHub(d: HubDeps): Hub {
                         markPosted(d.root, b.channel ?? '', b.file ?? '', b.url ?? '', rating)
                     }
                     else if (path === '/api/act/post-feedback') appendPostFeedback(d.root, b.channel ?? '', b.file ?? '', b.text ?? '')
+                    else if (path === '/api/act/remark') {
+                        // ONE remark verb, routed by collection — his words
+                        // land in the item's own truth file
+                        const text = (b.text ?? '').trim()
+                        if (text === '') return new Response('empty remark', { status: 400 })
+                        if (b.kind === 'ask') appendAskRemark(d.root, d.asksDir, b.file ?? '', text)
+                        else if (b.kind === 'media') appendAssetNote(d.root, b.id ?? '', text)
+                        else if (b.kind === 'post') appendPostFeedback(d.root, b.channel ?? '', b.file ?? '', text)
+                        else return new Response('unknown remark kind', { status: 400 })
+                    }
                     else return new Response('unknown act', { status: 404 })
                     return Response.json({ ok: true })
                 } catch (e) {
@@ -96,28 +118,21 @@ export function serveHub(d: HubDeps): Hub {
                 const p = join(d.root, 'STATUS.md')
                 return Response.json({ statusMd: existsSync(p) ? await Bun.file(p).text() : null })
             }
-            if (path === '/graph/wiki') return shell(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }), path)
-            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
-            if (d.agentGraph != null && path === '/graph/agent') return shell(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }), path)
-            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
-            if (path === '/status/run' && req.method === 'POST') {
+            if (path === '/api/check/run' && req.method === 'POST') {
                 // stream wire lines as the check emits them; sh merges stderr
                 // so FAIL lines reach the page, not just the terminal
                 const proc = Bun.spawn(['sh', '-c', 'exec "$0" "$@" 2>&1', ...d.checkCmd], { cwd: d.root, stdout: 'pipe', stderr: 'ignore' })
                 return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
             }
-            if (d.studio != null) {
-                // the studio page fetches RELATIVE urls — it must live under
-                // the slash-terminated prefix for them to resolve
-                if (path === '/assets') return new Response(null, { status: 307, headers: { location: '/assets/' } })
-                if (path === '/assets/' && req.method === 'GET') {
-                    // the SPA document gets the rail too; API routes untouched
-                    const res = await d.studio.handle(req, '/')
-                    return shell(await res.text(), '/assets/')
-                }
-                if (path.startsWith('/assets/')) return d.studio.handle(req, path.slice('/assets'.length))
-            }
-            return new Response('not found', { status: 404 })
+            const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
+            if (path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
+            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
+            if (d.agentGraph != null && path === '/graph/agent') return page(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
+            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
+            // the media API namespace — the studio route table, ONE prefix strip
+            if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
+            // stale bookmarks (/assets/, /status, …) land here — name the way home
+            return new Response('not found — the hub page is at /', { status: 404 })
         },
     })
     // RED-only pings ride the serving process: one tick now (state file

package/src/shipkit.ts

@@ -1,12 +1,12 @@
 // rvlib-shipkit — barrel. One import per repo: defineRepo in repo.config.ts;
 // everything else is the machinery behind the shipkit CLI.
-export { defineRepo, loadRepoConfig, resolveFloor, allTasks, contractsTask, contractsConfigFrom, activeContracts } from './repo-config.ts'
+export { defineRepo, loadRepoConfig, resolveFloor, allTasks, contractsTask } from './repo-config.ts'
 export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './repo-config.ts'
+export { contractsConfigFrom, activeContracts, applyContractsResult } from './contracts/apply-contracts.ts'
 // the hub (`shipkit serve`): one server, one port, every tool a click away
 export { serveHub, hubTools } from './serve/serve-hub.ts'
 export type { Hub, HubDeps, HubGraph, HubTool } from './serve/serve-hub.ts'
 export { runServe, resolveHubDeps, defaultHubPort } from './serve/run-serve.ts'
-export { withRail } from './serve/hub-pages.ts'
 export { projectNeeds, redCount } from './collections/collection-types.ts'
 export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
 export { buildCollections } from './collections/providers.ts'
@@ -27,6 +27,11 @@ export { writeStatus } from './core/write-status.ts'
 export type { StatusInput, StatusOutcome } from './core/write-status.ts'
 export { formatLine, parseDuration, fmtAge, parseWireOutput } from './core/wire.ts'
 export type { Line } from './core/wire.ts'
+// the SK rule registry — stable-id invariants `shipkit check` enforces;
+// consumers (e.g. a wiki lint verifying mentioned ids exist) read RULES
+export { RULES, ruleById } from './rules/rule-registry.ts'
+export { tagRuleLines } from './rules/rule.ts'
+export type { Rule, RuleEnv, FixResult } from './rules/rule.ts'
 export { evaluateContracts, pngDims } from './contracts/contracts-engine.ts'
 export type { ContractsConfig, ContractsResult, ContractOutcome } from './contracts/contracts-engine.ts'
 export { defineContract, validateManifest, file, png, glob, md, dir, custom, script, fileContains, dirExists } from './contracts/contract-types.ts'
@@ -41,9 +46,8 @@ export { defineKit, defineKind, comfy, canvas, manual, gemini, mediaOf, MEDIA_EX
 export type { KitConfig, ResolvedKit, Kind, KindMeta, Media, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, ManualGen, GeminiGen, 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'
-export type { Studio, StudioDeps, StudioRoutes } from './assets/server/studio-server.ts'
-export { page as studioPage } from './assets/server/studio-page.ts'
+export { studioRoutes } from './assets/server/studio-server.ts'
+export type { StudioDeps, StudioRoutes } from './assets/server/studio-server.ts'
 export { StudioQueue } from './assets/server/studio-queue.ts'
 export type { Job, QueueState } from './assets/server/studio-queue.ts'
 export { cleanRect, liveRect, defaultLegs, migrateCircle } from './assets/panels/geometry-rects.ts'