rvlib-shipkit 0.10.0 → 0.13.0

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

@@ -1,153 +1,266 @@
-// The hub's React app (Bun.serve HTML import — no vite, no build step).
-// Two views routed by pathname: / = attention dashboard (everything red),
-// /status = STATUS.md + streamed check runs. The rail lists every mounted
-// tool (from /hub.json) — legacy pages (graphs, studio) get the same rail
-// injected server-side until they migrate.
-import { makeAutoObservable, runInAction } from 'mobx'
+// THE page (Bun.serve HTML import — no vite, no build step). One surface
+// per repo (his rules 2026-07-23): media atelier + asks + creds + posts +
+// health + graphs as foldable sections, one severity filter persisted at
+// /?f=needs · /?f=red (legacy /?needs=1 reads as needs). Section title =
+// collection view (grid of cards), row = item view. mobx+react per
+// build/app-state-tree: HubSt is the single root (window.app), services
+// own state, components read and call.
+import { runInAction } from 'mobx'
 import { observer } from 'mobx-react-lite'
-import { StrictMode } from 'react'
+import { StrictMode, useEffect } from 'react'
 import { createRoot } from 'react-dom/client'
+import { ColCard, ColGrid, GraphView, StatusCard } from './col-card.tsx'
+import { HubSt } from './hub-st.ts'
+import { AssetStage, CatGrid, Drawer, InfoChips, MediaTopbar, RollStrip } from './media-view.tsx'
+import type { SideAsset } from './hub-types.ts'
 
-type HubTool = { path: string; label: string; desc: string }
-type AttentionLine = { text: string; href?: string }
-type AttentionSection = { title: string; tone: 'red' | 'warn'; lines: AttentionLine[]; href?: string }
+const app = new HubSt()
+// the root as a global — app code, console debugging (build/app-state-tree)
+;(window as unknown as { app: HubSt }).app = app
+app.boot()
 
-const RAIL_ICONS: Record<string, string> = { '/': '⚡', '/graph/wiki': '🕸', '/graph/agent': '🤖', '/assets/': '🖼', '/status': '📊' }
-
-class HubStore {
-    name = ''
-    tools: HubTool[] = []
-    sections: AttentionSection[] | null = null
-    statusMd: string | null = null
-    running = false
-    note = ''
-    error: string | null = null
-
-    constructor() {
-        makeAutoObservable(this)
-    }
+// ── sidebar: media categories + one foldable section per collection ──────
+const AssetRow = observer(({ a }: { a: SideAsset }) => (
+    <div className={`arow${a.id === app.media.curId ? ' sel' : ''}`} onClick={() => app.selectAsset(a.id)}>
+        <div className="lb"><b>{a.label}</b><span>{a.rolls} rolls</span></div>
+        {app.media.pending.includes(a.id)
+            ? <div className="spin" />
+            : <div className={`dot ${a.stale ? 'stale' : a.picked ? 'done' : a.rolls > 0 ? 'some' : a.manual ? 'miss' : ''}`}
+                title={a.manual && a.rolls === 0 ? 'manual asset — nothing uploaded yet' : undefined} />}
+    </div>
+))
 
-    get redCount(): number {
-        return (this.sections ?? []).filter((s) => s.tone === 'red').reduce((n, s) => n + s.lines.length, 0)
-    }
+const MediaSection = observer(() => {
+    const m = app.media
+    if (m.dead != null) return <div className="gname"><span className="warnline">media API down: {m.dead}</span></div>
+    if (m.assets.length === 0) return null // kit-less repo — no media section, same page
+    return (
+        <>
+            {m.cats.map((c) => {
+                // a live search must SHOW its matches — folds yield while it runs
+                const open = m.openCats.has(c) || app.query.trim() !== ''
+                const inCat = m.visibleAssets.filter((a) => a.cat === c)
+                return (
+                    <div key={c}>
+                        <div className="gname" id={`sec-cat-${c}`}>
+                            <span>
+                                <span className="fold" onClick={() => m.toggleFold(c)}>{open ? '▾' : '▸'}</span>{' '}
+                                <span className="cn" title="grid view" onClick={() => app.showCat(c)}>{c}</span>
+                            </span>
+                            {inCat.every((a) => a.manual) ? null : (
+                                <span className="catgen">{[1, 2, 3].map((n) => <button key={n} onClick={() => void m.genCat(c, n)}>+{n}</button>)}</span>
+                            )}
+                        </div>
+                        {open ? inCat.map((a) => <AssetRow key={a.id} a={a} />) : null}
+                    </div>
+                )
+            })}
+        </>
+    )
+})
 
-    async load(): Promise<void> {
-        try {
-            const hub = (await (await fetch('/hub.json')).json()) as { name: string; tools: HubTool[] }
-            const att = (await (await fetch('/api/attention.json')).json()) as { sections: AttentionSection[] }
-            runInAction(() => {
-                this.name = hub.name
-                this.tools = hub.tools
-                this.sections = att.sections
-            })
-            if (location.pathname === '/status') {
-                const s = (await (await fetch('/api/status.json')).json()) as { statusMd: string | null }
-                runInAction(() => { this.statusMd = s.statusMd })
-            }
-        } catch (e) {
-            runInAction(() => { this.error = (e as Error).message })
-        }
-    }
+const ColSections = observer(() => {
+    const c = app.cols
+    return (
+        <>
+            {c.sidebarCols.map((col) => {
+                const items = c.visibleInstances(col)
+                // every section header ALWAYS renders, 0 items included — a
+                // quiet section must stay reachable (his order 2026-07-23:
+                // done asks, present secrets)
+                const open = c.isOpen(col)
+                const health = col.id === 'health'
+                return (
+                    <div key={col.id}>
+                        <div className="gname" id={`sec-${col.id}`}>
+                            <span>
+                                <span className="fold" onClick={() => c.toggleFold(col)}>{open ? '▾' : '▸'}</span>{' '}
+                                <span className="cn" onClick={() => (health ? app.showStatus() : app.showCol(col.id))}
+                                    title={health ? 'STATUS.md + run check' : 'collection view'}>{col.title}</span>
+                            </span>
+                            <span className="cnt">{items.length}</span>
+                        </div>
+                        {open ? items.map((i) => (
+                            // a health line's action IS the runner — an echo card would be a dead end
+                            <div key={i.id} className={`arow${app.sel?.t === 'item' && app.sel.id === i.id ? ' sel' : ''}`}
+                                onClick={() => (health ? app.showStatus() : c.select(col.id, i.id))}>
+                                <div className="lb"><b>{i.text}</b>{i.file != null ? <span>{i.file}</span> : null}</div>
+                                <div className={`cdot ${i.severity ?? ''}`} />
+                            </div>
+                        )) : null}
+                    </div>
+                )
+            })}
+        </>
+    )
+})
 
-    async runCheck(): Promise<void> {
-        this.running = true
-        this.note = 'running…'
-        let text = ''
-        try {
-            const r = await fetch('/status/run', { method: 'POST' })
-            const rd = r.body!.getReader()
-            const dec = new TextDecoder()
-            for (;;) {
-                const { done, value } = await rd.read()
-                if (done) break
-                text += dec.decode(value, { stream: true })
-                runInAction(() => { this.statusMd = text })
-            }
-            runInAction(() => { this.note = 'done — STATUS.md refreshed on disk' })
-            void this.load() // red counts moved — refresh the dashboard data
-        } catch (e) {
-            runInAction(() => {
-                this.statusMd = `${text}\nFAIL stream broke: ${(e as Error).message}`
-                this.note = 'stream broke'
-            })
-        }
-        runInAction(() => { this.running = false })
-    }
-}
+// segmented severity filter — all · needs (yellow+red) · red, the address
+// rides at /?f=… so a filtered view is shareable
+const SegFilter = observer(() => (
+    <span className="seg">
+        {(['all', 'needs', 'red'] as const).map((f) => (
+            <button key={f} className={app.filter === f ? 'on' : ''} onClick={() => app.setFilter(f)}>{f}</button>
+        ))}
+    </span>
+))
 
-const store = new HubStore()
-void store.load()
+const Sidebar = observer(() => (
+    <aside>
+        <div className="shead">
+            {app.name !== '' ? app.name : 'hub'}
+            <SegFilter />
+        </div>
+        <div className="ssearch">
+            <input placeholder="filter… (⌘J to jump)" value={app.query}
+                onChange={(e) => app.setQuery(e.target.value)}
+                onKeyDown={(e) => { if (e.key === 'Escape') app.setQuery('') }} />
+        </div>
+        <MediaSection />
+        <ColSections />
+    </aside>
+))
 
+// ── the icon rail: quick jump to a section header (his order 2026-07-23:
+// scroll + unfold, NEVER a navigation) — red dot = the section holds a red ──
+const RAIL_ICON: Record<string, string> = { asks: '🙋', creds: '🔑', posts: '📣', health: '📊', graphs: '🕸' }
 const Rail = observer(() => {
-    const items = [{ path: '/', label: 'attention', desc: 'everything red' }, ...store.tools.filter((t) => t.path !== '/')]
+    const c = app.cols
+    const m = app.media
+    // unfold flips state; the scroll waits for react to paint the rows
+    const jump = (id: string): void => { setTimeout(() => document.getElementById(id)?.scrollIntoView({ block: 'start' }), 0) }
     return (
         <nav className="skrail">
-            {items.map((t) => {
-                const on = location.pathname === t.path || (t.path !== '/' && location.pathname.startsWith(t.path))
-                return (
-                    <a key={t.path} className={on ? 'on' : ''} href={t.path} title={`${t.label} — ${t.desc}`}>
-                        {RAIL_ICONS[t.path] ?? '·'}
-                        {t.path === '/' && store.redCount > 0 ? <i /> : null}
-                    </a>
-                )
-            })}
+            {m.assets.length > 0 ? (
+                <span className="ric" title="assets" onClick={() => { m.openAllCats(); if (m.cats[0] != null) jump(`sec-cat-${m.cats[0]}`) }}>
+                    🖼{c.mediaHasRed ? <i /> : null}
+                </span>
+            ) : null}
+            {c.sidebarCols.map((col) => (
+                <span key={col.id} className="ric" title={col.title} onClick={() => { c.openSection(col); jump(`sec-${col.id}`) }}>
+                    {RAIL_ICON[col.id] ?? '•'}{c.hasRed(col) ? <i /> : null}
+                </span>
+            ))}
         </nav>
     )
 })
 
-const Attention = observer(() => {
-    const live = (store.sections ?? []).filter((s) => s.lines.length > 0)
+// ── cmd+j palette: every jump target behind one input ────────────────────
+const Palette = observer(() => {
+    if (!app.palOpen) return null
     return (
-        <div className="wrap">
-            <div className="crumb">shipkit hub · attention</div>
-            <h1>{store.name}<small>everything that needs you, one page</small></h1>
-            {store.sections == null ? <div className="sub">loading…</div>
-                : live.length === 0 ? <div className="clear">✅ all clear — nothing needs you</div>
-                : live.map((s) => (
-                    <section key={s.title} className={s.tone}>
-                        <h2>{s.href != null ? <a href={s.href}>{s.title}</a> : s.title}<em>{s.lines.length}</em></h2>
-                        {s.lines.map((l, i) => (
-                            <div key={i} className="line">{l.href != null ? <a href={l.href}>{l.text}</a> : l.text}</div>
-                        ))}
-                    </section>
-                ))}
-            <div className="sub">refreshes on reload · checks refresh via <a href="/status">status → run check</a></div>
+        <div className="palov" onClick={() => app.palClose()}>
+            <div className="pal" onClick={(e) => e.stopPropagation()}>
+                <input autoFocus placeholder="jump to…" value={app.palQuery}
+                    onChange={(e) => app.setPalQuery(e.target.value)}
+                    onKeyDown={(e) => {
+                        if (e.key === 'ArrowDown') { e.preventDefault(); app.palMove(1) }
+                        else if (e.key === 'ArrowUp') { e.preventDefault(); app.palMove(-1) }
+                        else if (e.key === 'Enter') app.palRun()
+                        else if (e.key === 'Escape') app.palClose()
+                    }} />
+                <div className="prows">
+                    {app.palResults.map((jp, n) => (
+                        <div key={jp.id} className={`prow${n === app.palIdx ? ' on' : ''}`}
+                            onMouseEnter={() => app.setPalIdx(n)}
+                            onClick={() => { app.palClose(); jp.run() }}>
+                            <span className="plabel">{jp.label}</span>
+                            <span className="pchip">{jp.section}</span>
+                        </div>
+                    ))}
+                    {app.palResults.length === 0 ? <div className="prow none">no match</div> : null}
+                </div>
+            </div>
         </div>
     )
 })
 
-const wireClass = (l: string): string => {
-    const t = l.trimStart()
-    if (t.startsWith('FAIL') || t.startsWith('✗')) return 'fail'
-    if (t.startsWith('WARN') || t.startsWith('⚠')) return 'warn'
-    if (t.startsWith('ok') || t.startsWith('✓')) return 'ok'
-    if (t.startsWith('skip') || t.startsWith('fix:') || t.startsWith('#')) return 'dim'
-    return ''
-}
-
-const Status = observer(() => (
-    <div className="wrap">
-        <div className="crumb">shipkit hub · status</div>
-        <h1>{store.name}<small>STATUS.md</small></h1>
-        <div className="bar">
-            <button disabled={store.running} onClick={() => void store.runCheck()}>run check</button>
-            <span className="note">{store.note !== '' ? store.note : <>shells <code>shipkit check</code>, wire lines stream in below</>}</span>
+// remark box on the ASSET view too — his words land in .rv-assets/notes.md
+// and come back as `remarks` (exchange both ways, media included)
+const AssetRemarks = observer(() => {
+    const m = app.media
+    const c = app.cols
+    if (m.curId == null) return null
+    const remarks = c.mediaRemarks(m.curId)
+    return (
+        <div className="assetrem">
+            {remarks.length > 0 ? <div className="rem">{remarks.join('\n')}</div> : null}
+            <div className="row">
+                <input placeholder="remark → lands in .rv-assets/notes.md, agents read it" value={c.remarkDraft}
+                    onChange={(e) => runInAction(() => { c.remarkDraft = e.target.value })} />
+                <button className="ghost" onClick={() => void c.remark({ kind: 'media', id: m.curId })}>remark</button>
+            </div>
+            {c.actErr !== '' ? <div className="err">✗ {c.actErr}</div> : null}
         </div>
-        <pre>
-            {(store.statusMd ?? 'no STATUS.md yet — hit "run check" (or run: shipkit check)')
-                .split('\n')
-                .map((l, i) => <span key={i} className={wireClass(l)}>{l}{'\n'}</span>)}
-        </pre>
-    </div>
-))
+    )
+})
 
-const App = observer(() => (
-    <div className="app">
-        <Rail />
-        {store.error != null ? <div className="wrap err">hub api unreachable: {store.error}</div>
-            : location.pathname === '/status' ? <Status /> : <Attention />}
-    </div>
-))
+const Main = observer(() => {
+    const m = app.media
+    const errs = m.errors.length > 0 ? <div className="errs">{m.errors.join('\n')}</div> : null
+    if (app.sel?.t === 'item') return (
+        <main>
+            {errs}
+            {app.sel.col === 'graphs'
+                ? <GraphView app={app} id={app.sel.id} />
+                : <div className="stagewrap"><ColCard app={app} col={app.sel.col} id={app.sel.id} /></div>}
+        </main>
+    )
+    if (app.sel?.t === 'col') return <main>{errs}<ColGrid app={app} id={app.sel.id} /></main>
+    if (app.sel?.t === 'status') return <main>{errs}<div className="stagewrap"><StatusCard app={app} /></div></main>
+    if (app.sel?.t === 'cat') return <main>{errs}<CatGrid app={app} /></main>
+    if (app.sel?.t === 'asset') return (
+        <main>
+            {errs}
+            <MediaTopbar app={app} />
+            <InfoChips app={app} />
+            <AssetStage app={app} />
+            <RollStrip app={app} />
+            <AssetRemarks />
+            <Drawer app={app} />
+            <div className="help"><kbd>←</kbd><kbd>→</kbd> roll · <kbd>Enter</kbd> pick · <kbd>A</kbd> alt · <kbd>X</kbd> discard — picks ship via the kit's ship hook when present · category title = grid view</div>
+        </main>
+    )
+    // a filtered view with zero hits is the WIN state — say so, never point at a void
+    const allClear = app.filter !== 'all' && m.visibleAssets.length === 0 && app.cols.sidebarCols.every((col) => app.cols.visibleInstances(col).length === 0)
+    return (
+        <main>
+            {errs}
+            <div className="stagewrap"><div className="ph">
+                {allClear ? (app.filter === 'red' ? 'no reds — nothing is blocked ✨' : 'all clear — nothing needs you ✨')
+                    : m.assets.length > 0 ? 'Pick an asset or an item on the left.' : 'Pick an item on the left.'}
+            </div></div>
+        </main>
+    )
+})
+
+const App = observer(() => {
+    useEffect(() => {
+        const onKey = (e: KeyboardEvent): void => {
+            // ⌘J/^J beats the focus check — the palette must open from anywhere
+            if ((e.metaKey || e.ctrlKey) && !e.shiftKey && e.key.toLowerCase() === 'j') {
+                e.preventDefault()
+                app.palToggle()
+                return
+            }
+            const t = e.target as HTMLElement
+            if (t.tagName === 'TEXTAREA' || t.tagName === 'INPUT') return
+            if (app.palOpen) return // the palette input owns its keys
+            if (app.sel?.t !== 'asset') return
+            if (app.media.key(e.key)) e.preventDefault()
+        }
+        document.addEventListener('keydown', onKey)
+        return () => document.removeEventListener('keydown', onKey)
+    }, [])
+    return (
+        <div className="app">
+            <Rail />
+            <Sidebar />
+            <Main />
+            <Palette />
+        </div>
+    )
+})
 
 createRoot(document.getElementById('root')!).render(
     <StrictMode>

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

@@ -0,0 +1,169 @@
+// HubSt — the ONE root store (build/app-state-tree: one central tree,
+// instantiated once at boot, services with backrefs, exposed as
+// window.app). Owns cross-service state: selection, the severity filter
+// (an ADDRESS: /?f=needs · /?f=red; legacy /?needs=1 reads as needs),
+// hash deep-links (#<asset-id> · #cat-<Category>).
+import { makeAutoObservable } from 'mobx'
+import { ColsSvc } from './cols-svc.ts'
+import { HealthSvc } from './health-svc.ts'
+import { MediaSvc } from './media-svc.ts'
+
+export type Sel =
+    | { t: 'asset'; id: string }
+    | { t: 'cat'; cat: string }
+    | { t: 'col'; id: string }
+    | { t: 'item'; col: string; id: string }
+    | { t: 'status' }
+    | null
+
+/** one cmd+j target — run() fires the SAME action clicking would */
+export type Jump = { id: string; label: string; section: string; run: () => void }
+
+/** all · needs (yellow+red) · red — one severity ladder for every section */
+export type Filter = 'all' | 'needs' | 'red'
+const parseFilter = (search: string): Filter => {
+    const sp = new URLSearchParams(search)
+    const f = sp.get('f')
+    if (f === 'needs' || f === 'red') return f
+    return sp.get('needs') === '1' ? 'needs' : 'all' // legacy address keeps working
+}
+
+export class HubSt {
+    name = ''
+    media = new MediaSvc(this)
+    cols = new ColsSvc(this)
+    health = new HealthSvc(this)
+    sel: Sel = null
+    filter: Filter = parseFilter(location.search)
+    /** sidebar search — live substring filter over asset + collection rows */
+    query = ''
+    palOpen = false
+    palQuery = ''
+    palIdx = 0
+    private booted = false
+
+    constructor() {
+        makeAutoObservable<this, 'booted'>(this, { media: false, cols: false, health: false, booted: false })
+    }
+
+    boot(): void {
+        void fetch('/hub.json')
+            .then((r) => r.json() as Promise<{ name: string }>)
+            .then((h) => { this.setName(h.name) })
+            .catch(() => {})
+        this.media.start()
+        this.cols.start()
+        void this.health.load()
+        window.addEventListener('hashchange', () => this.applyHash())
+    }
+    private setName(n: string): void {
+        this.name = n
+        document.title = `${n} · hub`
+    }
+
+    setFilter(v: Filter): void {
+        this.filter = v
+        const u = new URL(location.href)
+        u.searchParams.delete('needs') // legacy param never survives a click
+        v === 'all' ? u.searchParams.delete('f') : u.searchParams.set('f', v)
+        history.replaceState(null, '', u)
+    }
+    setQuery(v: string): void {
+        this.query = v
+    }
+
+    // ── cmd+j palette ─────────────────────────────────────────────────────
+    palToggle(): void {
+        this.palOpen = !this.palOpen
+        this.palQuery = ''
+        this.palIdx = 0
+    }
+    palClose(): void {
+        this.palOpen = false
+    }
+    setPalQuery(v: string): void {
+        this.palQuery = v
+        this.palIdx = 0
+    }
+    setPalIdx(n: number): void {
+        this.palIdx = n
+    }
+    palMove(d: number): void {
+        const n = this.palResults.length
+        if (n > 0) this.palIdx = (this.palIdx + d + n) % n
+    }
+    palRun(): void {
+        const j = this.palResults[this.palIdx]
+        if (j == null) return
+        this.palOpen = false
+        j.run()
+    }
+    /** every jump target: section titles, media assets, collection instances */
+    get jumps(): Jump[] {
+        const out: Jump[] = []
+        for (const cat of new Set(this.media.assets.map((a) => a.cat)))
+            out.push({ id: `cat:${cat}`, label: cat, section: 'media', run: () => this.showCat(cat) })
+        for (const a of this.media.assets)
+            out.push({ id: `asset:${a.id}`, label: a.label, section: a.cat, run: () => this.selectAsset(a.id) })
+        for (const col of this.cols.sidebarCols) {
+            const health = col.id === 'health'
+            out.push({ id: `col:${col.id}`, label: col.title, section: 'section', run: () => (health ? this.showStatus() : this.showCol(col.id)) })
+            for (const i of col.instances)
+                out.push({ id: `item:${i.id}`, label: i.text, section: col.title, run: () => (health ? this.showStatus() : this.cols.select(col.id, i.id)) })
+        }
+        return out
+    }
+    /** ranked: prefix matches first, then substring; capped at 12 */
+    get palResults(): Jump[] {
+        const q = this.palQuery.trim().toLowerCase()
+        if (q === '') return this.jumps.slice(0, 12)
+        const pre: Jump[] = []
+        const sub: Jump[] = []
+        for (const j of this.jumps) {
+            const l = j.label.toLowerCase()
+            if (l.startsWith(q)) pre.push(j)
+            else if (l.includes(q)) sub.push(j)
+        }
+        return [...pre, ...sub].slice(0, 12)
+    }
+
+    // ── selection + hash deep-links ───────────────────────────────────────
+    selectAsset(id: string, writeHash = true): void {
+        this.sel = { t: 'asset', id }
+        if (writeHash) this.setHash(id)
+        void this.media.select(id)
+    }
+    showCat(cat: string, writeHash = true): void {
+        this.sel = { t: 'cat', cat }
+        this.media.openCats.add(cat)
+        if (writeHash) this.setHash(`cat-${cat}`)
+        void this.media.fillCat()
+    }
+    showStatus(): void {
+        this.sel = { t: 'status' }
+        void this.health.load()
+    }
+    /** collection view — one card per instance (health has StatusCard instead) */
+    showCol(id: string): void {
+        this.sel = { t: 'col', id }
+    }
+    private setHash(h: string): void {
+        if (location.hash.slice(1) !== h) location.hash = h
+    }
+    applyHash(): void {
+        const h = decodeURIComponent(location.hash.slice(1))
+        if (h === '') return
+        if (h.startsWith('cat-')) {
+            const c = h.slice(4)
+            if (this.media.assets.some((a) => a.cat === c) && this.media.catMode !== c) this.showCat(c, false)
+            return
+        }
+        if (this.media.assets.some((a) => a.id === h) && this.media.curId !== h) this.selectAsset(h, false)
+    }
+    /** first heartbeat has the asset list — only then can a hash resolve */
+    afterFirstBeat(): void {
+        if (this.booted) return
+        this.booted = true
+        this.applyHash()
+    }
+}

package/src/serve/hub-app/hub-types.ts

@@ -0,0 +1,72 @@
+// Wire types the hub app reads — mirrors of the server shapes
+// (studio-server.ts, collection-types.ts). Kept structural on purpose: the
+// page renders what the API sends, the file is the truth.
+
+export type SideAsset = {
+    id: string
+    cat: string
+    label: string
+    prompt: string
+    rolls: number
+    picked: boolean
+    icon: boolean
+    media: 'image' | 'audio'
+    manual: boolean
+    derived: boolean
+    stale: boolean
+}
+
+export type RollRow = { name: string; picked: boolean; alt: boolean; hasMeta: boolean }
+
+export type AssetInfo = {
+    backend: string
+    deterministic: boolean
+    workflow: { id: string | null; path: string | null; note?: string } | null
+    ship: { mode: string; path?: string; note?: string }
+    metaFile: string | null
+    kindId: string
+    kitSource: string
+}
+
+export type CustomPanelRef = { id: string; kind: string; url: string }
+
+export type AssetDetail = {
+    asset: { id: string; label?: string; prompt: string; cat: string; geometry: boolean; custom: CustomPanelRef[] } & Record<string, unknown>
+    info: AssetInfo
+    rolls: RollRow[]
+}
+
+export type Leg = { x: number; y: number; w: number; h: number }
+export type Rect = { x: number; y: number; w: number; h: number; size: number; flip?: boolean; legs?: Leg[]; legColor?: string; art?: unknown }
+
+export type CatRow = { id: string; label: string; name: string; rect: Rect | null; prop: boolean; icon: boolean }
+
+export type QueueState = {
+    generating: boolean
+    current: string | null
+    done: number
+    total: number
+    queued: number
+    progress: { value: number; max: number } | null
+    pending: string[]
+    errors: string[]
+    assets: SideAsset[]
+}
+
+export type Candidate = { id: string; label: string; hint?: string }
+export type Artifact = { copy?: string; url?: string; steps?: string[] }
+export type ColInstance = {
+    id: string
+    text: string
+    severity?: 'red' | 'yellow'
+    href?: string
+    artifact?: Artifact
+    candidates?: Candidate[]
+    file?: string
+    img?: string
+    remarks?: string[]
+    /** the truth file's markdown BODY (frontmatter stripped) — clamped card
+     *  in the grid, full in the item view */
+    md?: string
+}
+export type Col = { id: string; title: string; media: string; instances: ColInstance[] }