rvlib-shipkit 2.3.0 → 2.5.0

package/src/serve/hub-app/review.css

@@ -118,7 +118,7 @@
 .rv-word{margin-top:var(--s2)}
 .rv-raised{padding:var(--s2) var(--s3);border:1px solid var(--line);border-left:4px solid var(--warn);border-radius:4px;background:var(--panel)}
 .rv-raisedimg{display:block;max-width:100%;max-height:320px;margin-top:var(--s2);border-radius:4px}
-.rv-pairgrid{margin:0 auto;display:grid;gap:var(--s2)}
+.rv-pairgrid{display:grid;gap:var(--s2)}
 .rv-cell{display:flex;flex-direction:column;align-items:center;gap:var(--s0);min-width:0}
 .rv-frame{position:relative;width:100%;max-width:100%;border-radius:4px;border:1px solid var(--line);overflow:hidden;
  background:repeating-conic-gradient(var(--chk1) 0 25%,var(--chk2) 0 50%) 0 0/16px 16px}
@@ -148,7 +148,7 @@
 .rv-tile{display:flex;flex-direction:column;gap:var(--s1);padding:var(--s1);border-radius:6px;border:2px solid var(--line)}
 .rv-tile[class*=' re-']{border-color:var(--tone);background:color-mix(in srgb,var(--tone) 8%,transparent)}
 .rv-tile.big{width:100%}
-.rv-tileimg{border-radius:4px;cursor:zoom-in;margin:0 auto;width:100%;background:repeating-conic-gradient(var(--chk1) 0 25%,var(--chk2) 0 50%) 0 0/12px 12px}
+.rv-tileimg{border-radius:4px;cursor:zoom-in;width:100%;background:repeating-conic-gradient(var(--chk1) 0 25%,var(--chk2) 0 50%) 0 0/12px 12px}
 .rv-tile.big .rv-tileimg{cursor:zoom-out}
 .rv-tileimg img{display:block;width:100%;height:100%;object-fit:contain}
 .rv-tilelabel{font-size:11px;font-weight:600;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
@@ -159,19 +159,64 @@
 .rv-sound button{padding:0 var(--s1);line-height:22px}
 .rv-sound input{width:72px}
 .rv-phonepair{display:flex;flex-direction:column;gap:var(--s2)}
+/* options: one thin row a view, one below the other; the row playing or last touched has the line, the picked one its tone */
+.rv-opts{display:flex;flex-direction:column;gap:var(--s1)}
+.rv-opt{scroll-margin-top:8px;padding:var(--s1) var(--s2);border-radius:6px;border:1px solid var(--line);border-left:4px solid transparent;background:var(--panel)}
+.rv-opt.active{border-left-color:var(--accent)}
+.rv-opt[class*=' re-']{border-left-color:var(--tone)}
+.rv-opt.picked{--tone:var(--ok);border-color:var(--tone);border-left-color:var(--tone);background:color-mix(in srgb,var(--tone) 9%,var(--panel))}
+.rv-optrow{display:flex;flex-wrap:wrap;gap:var(--s1) var(--s2);align-items:center;min-height:32px}
+.rv-optn{flex:none;width:16px;text-align:right;font:600 12px ui-monospace,Menlo,monospace;color:var(--dim)}
+.rv-optplay{flex:none;width:32px;height:28px;padding:0;font-size:13px}
+.rv-optplay.on{color:var(--bg);background:var(--accent);border-color:var(--accent)}
+.rv-optlabel{flex:0 1 auto;min-width:48px;max-width:30%;font-size:13px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.rv-optthumb{flex:none;height:32px;max-width:72px;border-radius:3px;overflow:hidden;cursor:zoom-in;border:1px solid var(--line);background:var(--panel2)}
+.rv-optthumb.img{width:48px}
+.rv-optthumb img{display:block;width:100%;height:100%;object-fit:cover}
+.rv-strip{position:relative;flex:1 1 140px;min-width:120px;height:28px;border-radius:3px;cursor:pointer;touch-action:none;background:var(--panel2);border:1px solid var(--line);overflow:hidden}
+.rv-stripdone{position:absolute;inset:0 auto 0 0;background:var(--wash)}
+/* a waveform is a mask filled with tokens: --dim to play (5.0:1 on --panel2 light, 5.3:1 dark), --accent played
+   (4.9:1 both) */
+.rv-stripwave{position:absolute;inset:0;background:var(--dim)}
+.rv-stripwave.done{background:var(--accent)}
+.rv-stripwave.full{background:var(--accent)}
+.rv-wavebox{position:relative;width:100%;border-radius:4px;background:var(--panel2)}
+.rv-striphead{position:absolute;top:0;bottom:0;width:2px;transform:translateX(-1px);background:var(--accent)}
+.rv-opttime{flex:none;font-size:11px;color:var(--dim)}
+.rv-optacts{flex:none;display:inline-flex;gap:var(--s1);align-items:center;margin-left:auto}
+.rv-optacts > button{padding:0 var(--s1);line-height:22px}
+.rv-optacts > button.on{border-color:var(--accent)}
+.rv-stars{display:inline-flex}
+.rv-stars button{border:0;background:none;padding:0;font-size:16px;line-height:22px;color:var(--dim)}
+.rv-stars button.on{color:var(--warn)}
+.rv-pick{font-weight:700;padding:0 var(--s3)!important;color:var(--ok);border-color:color-mix(in srgb,var(--ok) 55%,var(--line))}
+.rv-pick.on{color:var(--bg);background:var(--ok);border-color:var(--ok)}
+.rv-optnote{margin:var(--s0) 0 0 var(--s4);font-size:12.5px;color:var(--ink)}
+.rv-opt .rv-word{margin:var(--s1) 0 0 var(--s4);width:calc(100% - var(--s4))}
+.rv-optbody{margin-top:var(--s2)}
 
 /* ── the answer ── */
 .rv-form{display:flex;flex-direction:column;gap:var(--s2);padding:var(--s3)}
-.rv-status{padding:var(--s1) var(--s3);border-radius:4px;border:1px solid color-mix(in srgb,var(--tone) 45%,var(--line));border-left:4px solid var(--tone);background:color-mix(in srgb,var(--tone) 10%,var(--panel))}
-.rv-statushead{font-weight:800;color:var(--tone);display:flex;gap:var(--s1);align-items:center;flex-wrap:wrap}
-.rv-title{margin:0;font-size:17px;line-height:1.3}
-.rv-what{font-size:13px}
-.rv-what ul{margin:var(--s1) 0;padding-left:var(--s4)}
-.rv-what p{margin:var(--s1) 0}
+.rv-title{margin:0;font-size:16px;line-height:1.3;color:var(--ink)}
+/* the card's header: the title, one tight line of state, then what the agent says at full ink; --dim holds 5.6:1 or
+   more on --bg and --panel in both themes */
+.rv-head{display:flex;flex-direction:column;gap:var(--s1)}
+.rv-meta{display:flex;flex-wrap:wrap;gap:var(--s1) var(--s2);align-items:center;font-size:12px;color:var(--dim);line-height:18px}
+.rv-meta .rv-badge{font-size:10px;line-height:18px;max-width:none}
+.rv-copyid{display:inline-flex;align-items:center;padding:var(--s0);color:var(--dim)}
+.rv-copyid:hover{color:var(--ink)}
+.rv-toast{position:fixed;left:50%;bottom:var(--s4);transform:translateX(-50%);z-index:40;max-width:calc(100% - 2 * var(--s4));padding:var(--s1) var(--s3);border-radius:6px;border:1px solid var(--line);background:var(--panel);color:var(--ink);font-size:12.5px;box-shadow:0 6px 20px var(--shadow)}
+.rv-what{font-size:13.5px;line-height:1.45;color:var(--ink)}
+.rv-what ul{margin:var(--s0) 0;padding-left:var(--s4)}
+.rv-what p{margin:var(--s0) 0}
+.rv-why{color:var(--dim);font-size:12px}
+.rv-headverdicts{display:flex;flex-wrap:wrap;gap:var(--s1);align-items:center;margin-top:var(--s1)}
+.rv-headverdicts .rv-verdict{padding:0 var(--s2);line-height:24px;font-size:12.5px}
+.rv-head .rv-comment{margin-top:var(--s1);width:100%}
 .rv-keeps{color:var(--ok);font-size:13px}
 .rv-facts{display:flex;flex-direction:column}
-.rv-fact{display:flex;gap:var(--s2);align-items:center;min-height:24px;font-size:12.5px}
-.rv-factl{width:64px;flex:none;color:var(--dim);font-size:11px}
+.rv-fact{display:flex;gap:var(--s2);align-items:center;min-height:22px;font-size:12.5px}
+.rv-factl{width:64px;flex:none;color:var(--dim);font-size:12px}
 .rv-factv{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .rv-linked{padding:var(--s1) var(--s2);border:1px solid var(--line);border-radius:4px;background:var(--panel)}
 .rv-linkedrow{display:flex;gap:var(--s2);align-items:center;font-size:12px}
@@ -184,9 +229,6 @@
 .rv-outbadge.rect{--tone:var(--warn)}
 .rv-outbadge.rect.on{--tone:var(--blue)}
 .rv-x{flex:none;padding:0 var(--s1);border:0}
-.rv-label{font-size:12px;font-weight:600;margin-top:var(--s1)}
-.rv-listenrow{display:flex;gap:var(--s2);align-items:center;font-size:11px}
-.rv-verdicts{display:flex;flex-direction:column;gap:var(--s1)}
 .rv-verdict{text-align:left;padding:var(--s1) var(--s3);font-size:13px;border-color:color-mix(in srgb,var(--tone) 60%,var(--line))}
 .rv-verdict .rv-vglyph{color:var(--tone);font-weight:800}
 .rv-verdict.chosen{background:var(--tone);color:var(--bg);border-color:var(--tone)}
@@ -208,6 +250,17 @@
 .rv-verdictbar{flex:none;display:flex;gap:var(--s1);padding:var(--s2);border-top:1px solid var(--line);background:var(--panel)}
 .rv-verdictbar .rv-verdict{flex:1;text-align:center;font-size:14px;padding:var(--s2) var(--s1);color:var(--tone)}
 .rv-verdictbar .rv-verdict.chosen{color:var(--bg)}
+.rv-phone .rv-views{gap:var(--s3)}
+.rv-phone .rv-toast{top:var(--s4);bottom:auto}
+/* a row on a phone: ▶, the label and the time on one line, the strip and the acts under them */
+.rv-phone .rv-optrow{flex-wrap:wrap;row-gap:var(--s1)}
+.rv-phone .rv-optlabel{flex:1;max-width:none}
+.rv-phone .rv-strip{order:5;flex:1 1 100%;height:32px}
+.rv-phone .rv-optthumb{order:4}
+.rv-phone .rv-optacts{order:6;flex:1 1 100%;justify-content:space-between}
+.rv-phone .rv-stars button{font-size:22px;padding:0 var(--s1)}
+.rv-phone .rv-optplay{width:40px;height:34px}
+.rv-phone .rv-optnote,.rv-phone .rv-opt .rv-word{margin-left:0;width:100%}
 
 /* ── the trailer page ── */
 .tr-cuts{display:flex;flex-direction:column;gap:var(--s2);padding:var(--s3)}
@@ -323,6 +376,13 @@
 .rv-boardrow .rv-linkedtitle{display:block}
 .rv-kindview{display:flex;flex-direction:column;gap:var(--s2);margin:var(--s2) 0}
 .rv-kindtext{font:12px/1.5 ui-monospace,Menlo,monospace;background:var(--panel);border:1px solid var(--line);border-radius:3px;padding:var(--s2) var(--s3);margin:0;white-space:pre-wrap;overflow-wrap:anywhere}
+.rv-part{border:1px solid var(--line);border-radius:4px;padding:var(--s2) var(--s3);margin-top:var(--s2);background:var(--panel)}
+.rv-parthead{display:flex;align-items:center;gap:var(--s2);margin-bottom:var(--s2)}
+.rv-particon{width:20px;height:20px;border-radius:5px;flex:none}
+.rv-partbadge{margin-left:auto;font-size:11px;font-weight:700;border:1px solid;border-radius:3px;padding:0 var(--s1)}
+.rv-partbody{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:var(--s3);align-items:start}
+.rv-partbody img,.rv-partbody video{width:100%;max-height:320px;object-fit:contain;border-radius:6px;display:block}
+.rv-parttext{font-size:13px;line-height:1.45;white-space:pre-wrap;overflow-wrap:anywhere}
 .rv-anim select{font-size:12px}
 /* a sound view (review-views.tsx SoundBody): its waveform over the player, a row a side on a pair */
 .rv-sound{display:flex;flex-direction:column;gap:var(--s2)}

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

@@ -0,0 +1,190 @@
+// the wikis page's state, one per repo: the search bar over the open wiki
+// (its title and full text, graph-pages.ts on the server), the hit under the
+// arrows, and the page open in the preview panel. The graph is an iframe that
+// only draws (wiki/graph-page.ts): a click on a ball arrives as a message,
+// and opening a page answers with a focus message, so the ball and the
+// preview always show the same page.
+import { makeAutoObservable, runInAction } from 'mobx'
+import type { WikiHit, WikiPage } from '../../wiki/graph-pages.ts'
+import type { RepoSt } from './repo-st.ts'
+
+const WIDTH_KEY = 'hub:wiki-preview-width'
+const HEIGHT_KEY = 'hub:wiki-preview-height'
+const PLACE_KEY = 'hub:wiki-preview-place'
+export const PREVIEW = { min: 260, max: 1200, def: 460 }
+/** the preview below the graph: its height */
+export const PREVIEW_H = { min: 160, max: 1200, def: 360 }
+/** where the preview sits against the graph, toggled from its own head */
+export const PLACES = ['left', 'right', 'bottom'] as const
+export type PreviewPlace = (typeof PLACES)[number]
+/** the wait after a keystroke before the search asks the server */
+const SEARCH_MS = 120
+
+function loadSize(key: string, b: { min: number; max: number; def: number }): number {
+    try {
+        const n = Number(globalThis.localStorage?.getItem(key))
+        return Number.isFinite(n) && n >= b.min && n <= b.max ? n : b.def
+    } catch {
+        return b.def
+    }
+}
+
+function loadPlace(): PreviewPlace {
+    try {
+        const v = globalThis.localStorage?.getItem(PLACE_KEY) ?? ''
+        return (PLACES as readonly string[]).includes(v) ? (v as PreviewPlace) : 'left'
+    } catch {
+        return 'left'
+    }
+}
+
+function keep(key: string, v: string): void {
+    try {
+        globalThis.localStorage?.setItem(key, v)
+    } catch { /* private window: the choice lasts the tab */ }
+}
+
+export class WikiSt {
+    /** the open wiki's route, `/graph/<id>`: every read is under it */
+    href: string | null = null
+    query = ''
+    hits: WikiHit[] = []
+    /** the hit under the arrows */
+    cursor = 0
+    /** the dropdown shows */
+    listOpen = false
+    page: WikiPage | null = null
+    error = ''
+    width = loadSize(WIDTH_KEY, PREVIEW)
+    height = loadSize(HEIGHT_KEY, PREVIEW_H)
+    place: PreviewPlace = loadPlace()
+    /** the copy button said copied, for a moment */
+    copied = false
+    private frame: Window | null = null
+    private timer: ReturnType<typeof setTimeout> | null = null
+    private asked = 0
+
+    constructor(private readonly st: RepoSt) {
+        makeAutoObservable<this, 'st' | 'frame' | 'timer' | 'asked'>(this, { st: false, frame: false, timer: false, asked: false })
+    }
+
+    /** the wiki shown changed: its search starts over, and its index opens */
+    bind(href: string | null): void {
+        if (href === this.href) return
+        this.href = href
+        this.query = ''
+        this.hits = []
+        this.page = null
+        this.error = ''
+        this.listOpen = false
+        if (href != null) void this.open('')
+    }
+
+    /** the graph's iframe, to send it focus and theme */
+    setFrame(w: Window | null): void {
+        this.frame = w
+    }
+
+    send(msg: { type: 'wiki-graph:focus'; id: string } | { type: 'wiki-graph:theme'; theme: 'dark' | 'light' }): void {
+        this.frame?.postMessage(msg, '*')
+    }
+
+    setQuery(q: string): void {
+        this.query = q
+        this.cursor = 0
+        this.listOpen = q.trim() !== ''
+        if (this.timer != null) clearTimeout(this.timer)
+        if (q.trim() === '') {
+            this.hits = []
+            return
+        }
+        this.timer = setTimeout(() => void this.search(q), SEARCH_MS)
+    }
+
+    private async search(q: string): Promise<void> {
+        if (this.href == null) return
+        const n = ++this.asked
+        try {
+            const r = await fetch(this.st.url(`${this.href}/search?q=${encodeURIComponent(q)}`))
+            if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
+            const hits = (await r.json()) as WikiHit[]
+            // an answer to an older query never replaces a newer one
+            if (n === this.asked) runInAction(() => { this.hits = hits; this.error = '' })
+        } catch (e) {
+            if (n === this.asked) runInAction(() => (this.error = `search failed: ${(e as Error).message}`))
+        }
+    }
+
+    /** the search input's keys: up and down walk the hits, enter opens one, escape closes the list */
+    key(k: string): boolean {
+        if (k === 'Escape') {
+            if (!this.listOpen) return false
+            this.listOpen = false
+            return true
+        }
+        if (this.hits.length === 0) return false
+        if (k === 'ArrowDown') this.cursor = Math.min(this.hits.length - 1, this.cursor + 1)
+        else if (k === 'ArrowUp') this.cursor = Math.max(0, this.cursor - 1)
+        else if (k === 'Enter') void this.open(this.hits[this.cursor]!.id)
+        else return false
+        if (k !== 'Enter') this.listOpen = true
+        return true
+    }
+
+    /** a page opens in the preview, and its ball is focused in the graph; '' = the wiki's index */
+    async open(id: string): Promise<void> {
+        const href = this.href
+        if (href == null) return
+        this.listOpen = false
+        if (id !== '') this.send({ type: 'wiki-graph:focus', id })
+        try {
+            const r = await fetch(this.st.url(`${href}/page?node=${encodeURIComponent(id)}`))
+            if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
+            const p = (await r.json()) as WikiPage
+            // the wiki changed while the page was read: it is not this one's
+            if (href !== this.href) return
+            runInAction(() => { this.page = p; this.error = '' })
+            if (id === '') this.send({ type: 'wiki-graph:focus', id: p.id })
+        } catch (e) {
+            runInAction(() => (this.error = `${id === '' ? 'the index' : id} would not open: ${(e as Error).message}`))
+        }
+    }
+
+    setPlace(p: PreviewPlace): void {
+        this.place = p
+        keep(PLACE_KEY, p)
+    }
+
+    /** the open page's path on disk, to the clipboard */
+    async copyPath(): Promise<void> {
+        if (this.page == null) return
+        try {
+            await navigator.clipboard.writeText(this.page.file)
+            runInAction(() => (this.copied = true))
+            setTimeout(() => runInAction(() => (this.copied = false)), 1500)
+        } catch (e) {
+            runInAction(() => (this.error = `the path was not copied: ${(e as Error).message}`))
+        }
+    }
+
+    close(): void {
+        this.page = null
+    }
+
+    /** a drag of the preview's separator ended at this size: its width beside the graph, its height under it */
+    setSize(px: number): void {
+        if (this.place === 'bottom') {
+            this.height = Math.round(Math.min(PREVIEW_H.max, Math.max(PREVIEW_H.min, px)))
+            keep(HEIGHT_KEY, String(this.height))
+        } else {
+            this.width = Math.round(Math.min(PREVIEW.max, Math.max(PREVIEW.min, px)))
+            keep(WIDTH_KEY, String(this.width))
+        }
+    }
+
+    /** a message from the graph: a ball was clicked */
+    onMessage(data: unknown): void {
+        const m = data as { type?: unknown; id?: unknown } | null
+        if (m != null && m.type === 'wiki-graph:pick' && typeof m.id === 'string') void this.open(m.id)
+    }
+}

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

@@ -1,7 +1,16 @@
 // The wikis page: one tab per mounted markdown wiki, one link graph at a
 // time, embedded from its own /graph/<id> route. A tab is an item of the
 // wikis collection, so the open wiki is in the url like any other page.
+// Over the graph a search bar (title and full text, a dropdown the arrows
+// walk); a hit, or a click on a ball, opens the page in a resizable panel on
+// the right, whose refs open their page in turn and focus its ball (wiki-st.ts).
 import { observer } from 'mobx-react-lite'
+import { useEffect, useRef, type MouseEvent } from 'react'
+import { Group, Panel, Separator, type Layout } from 'react-resizable-panels'
+import { renderWikiPage } from './md.ts'
+import { editorHref } from './check-words.ts'
+import { Icon, ICON } from './icons.tsx'
+import { PLACES, PREVIEW, PREVIEW_H, type PreviewPlace, type WikiSt } from './wiki-st.ts'
 import type { RepoSt } from './repo-st.ts'
 import type { Resource } from './hub-types.ts'
 
@@ -33,8 +42,13 @@ export function openWikis(app: RepoSt): void {
     else app.showCol(WIKIS)
 }
 
+const PANEL = { overflow: 'hidden' } as const
+
 export const WikisView = observer(({ app, id }: { app: RepoSt; id: string }) => {
     const i = app.cols.find(WIKIS, id)
+    const w = app.wiki
+    const href = i?.href ?? null
+    useEffect(() => w.bind(href), [w, href])
     const tabs = (
         <span className="seg">
             {wikiTabs(app).map((t) => <button key={t.id} className={t.on ? 'on' : ''} onClick={t.go}><span className={`tl ${t.state}`}>{t.label}</span></button>)}
@@ -45,13 +59,128 @@ export const WikisView = observer(({ app, id }: { app: RepoSt; id: string }) =>
         <div className="graphview">
             <div className="gvhead">
                 {tabs}
+                {href == null ? null : <WikiSearch w={w} />}
                 <span className={`gvtext tl ${i.state}`}>{i.text}</span>
             </div>
-            {i.href == null ? <div className="ph">this wiki carries no page to embed</div> : (
-                // the spinner sits under the frame: the graph page paints its
-                // own background over it the moment it has something to show
-                <div className="gvframe"><span className="gvwait"><span className="spin" />reading the wiki…</span><iframe src={app.url(i.href)} title={i.title} /></div>
-            )}
+            {w.error !== '' ? <div className="hnote">{w.error}</div> : null}
+            {href == null ? <div className="ph">this wiki carries no page to embed</div> : <WikiBody app={app} w={w} href={href} title={i.title} />}
+        </div>
+    )
+})
+
+/** the graph and, once a page is open, its preview on the right; the preview's width is dragged and kept */
+const WikiBody = observer(({ app, w, href, title }: { app: RepoSt; w: WikiSt; href: string; title: string }) => {
+    const el = useRef<HTMLDivElement | null>(null)
+    const frame = useRef<HTMLIFrameElement | null>(null)
+    const theme = app.home.theme.resolved
+    // the theme the graph first paints in rides its url; a later change is a message, never a reload
+    const first = useRef(theme)
+    useEffect(() => w.send({ type: 'wiki-graph:theme', theme }), [w, theme])
+    useEffect(() => {
+        const on = (ev: MessageEvent): void => {
+            if (ev.source != null && ev.source === frame.current?.contentWindow) w.onMessage(ev.data)
+        }
+        addEventListener('message', on)
+        return () => removeEventListener('message', on)
+    }, [w])
+    const sep = href.includes('?') ? '&' : '?'
+    const below = w.place === 'bottom'
+    const graph = (
+        <Panel key="graph" id="wiki-graph" minSize={below ? 160 : 280} style={PANEL}>
+            {/* the spinner sits under the frame: the graph page paints its own background over it the moment it has something to show */}
+            <div className="gvframe"><span className="gvwait"><span className="spin" />reading the wiki…</span>
+                <iframe ref={(f) => { frame.current = f; w.setFrame(f?.contentWindow ?? null) }} src={`${app.url(href)}${sep}theme=${first.current}`} title={title}
+                    onLoad={() => {
+                        w.setFrame(frame.current?.contentWindow ?? null)
+                        w.send({ type: 'wiki-graph:theme', theme: app.home.theme.resolved })
+                        if (w.page != null) w.send({ type: 'wiki-graph:focus', id: w.page.id })
+                    }} />
+            </div>
+        </Panel>
+    )
+    const preview = w.page == null ? null : (
+        <Panel key="preview" id="wiki-preview" defaultSize={below ? w.height : w.width} minSize={below ? PREVIEW_H.min : PREVIEW.min} maxSize={below ? PREVIEW_H.max : PREVIEW.max}
+            groupResizeBehavior="preserve-pixel-size" style={PANEL}>
+            <WikiPreview w={w} />
+        </Panel>
+    )
+    const line = preview == null ? null : <Separator key="sep" className={below ? 'rsep hsep' : 'rsep'} />
+    return (
+        // the group is remade when the preview moves: its panels change order and axis
+        <Group key={w.place} className="gvbody" orientation={below ? 'vertical' : 'horizontal'} elementRef={el}
+            onLayoutChanged={(layout: Layout, meta) => {
+                const pct = layout['wiki-preview']
+                const r = el.current?.getBoundingClientRect()
+                const whole = below ? r?.height : r?.width
+                if (meta.isUserInteraction && pct != null && whole != null && whole > 0) w.setSize((pct / 100) * whole)
+            }}>
+            {w.place === 'left' ? [preview, line, graph] : [graph, line, preview]}
+        </Group>
+    )
+})
+
+/** the search bar: the hits drop under it, the arrows walk them, enter or a click opens one */
+const WikiSearch = observer(({ w }: { w: WikiSt }) => (
+    <span className="wsearch">
+        <input type="search" placeholder="search the wiki: a title, a word…" aria-label="search the wiki" value={w.query}
+            onChange={(e) => w.setQuery(e.currentTarget.value)}
+            onFocus={() => { if (w.hits.length > 0) w.key('ArrowUp') }}
+            onBlur={() => w.key('Escape')}
+            onKeyDown={(e) => { if (w.key(e.key)) e.preventDefault() }} />
+        {w.listOpen && w.query.trim() !== '' ? (
+            <div className="wslist" role="listbox">
+                {w.hits.length === 0 ? <div className="wsnone">no page matches</div> : w.hits.map((h, n) => (
+                    // mouse down, not click: the input's blur would close the list first
+                    <div key={h.id} role="option" aria-selected={n === w.cursor} className={`wshit${n === w.cursor ? ' on' : ''}`}
+                        onMouseDown={(e) => { e.preventDefault(); void w.open(h.id) }}>
+                        <div className="wshead"><b>{h.title}</b><span className="wspath">{h.id}</span></div>
+                        {h.snippet === '' || h.inTitle && h.snippet === '' ? null : <div className="wssnip">{h.snippet}</div>}
+                    </div>
+                ))}
+            </div>
+        ) : null}
+    </span>
+))
+
+const PLACE_ICON: Record<PreviewPlace, keyof typeof ICON> = { left: 'paneLeft', right: 'paneRight', bottom: 'paneBottom' }
+
+/** the open page: its title and path, where the panel sits, the editor and
+ *  the copy, the close; then the markdown, whose refs open their own page */
+const WikiPreview = observer(({ w }: { w: WikiSt }) => {
+    const p = w.page!
+    const editor = editorHref('', p.file)
+    const click = (e: MouseEvent<HTMLDivElement>): void => {
+        const t = e.target as HTMLElement
+        const a = t.closest('a[data-wiki]')
+        if (a != null) {
+            e.preventDefault()
+            void w.open(a.getAttribute('data-wiki')!)
+            return
+        }
+        // a ref in a code span opens its page by its text
+        const code = t.closest('code')
+        const to = code == null ? undefined : p.links[code.textContent ?? '']
+        if (to != null) void w.open(to)
+    }
+    return (
+        <div className="wprev">
+            <div className="wphead">
+                <b className="wptitle">{p.title}</b>
+                <span className="wspath" title={p.file}>{p.id}</span>
+                <span className="seg wpplace" aria-label="where the preview sits">
+                    {PLACES.map((pl) => (
+                        <button key={pl} className={w.place === pl ? 'on' : ''} aria-label={`the preview on the ${pl}`} title={`the preview on the ${pl}`} onClick={() => w.setPlace(pl)}>
+                            <Icon d={ICON[PLACE_ICON[pl]]} />
+                        </button>
+                    ))}
+                </span>
+                {editor == null ? null : (
+                    <a className="wpbtn" href={editor} title={`open ${p.file} in VS Code`}><Icon d={ICON.editor} /><span>VS Code</span></a>
+                )}
+                <button className="wpbtn" title={`copy ${p.file}`} onClick={() => void w.copyPath()}><Icon d={ICON.copy} /><span>{w.copied ? 'copied' : 'copy path'}</span></button>
+                <button className="ghost wpclose" aria-label="close the preview" title="close the preview" onClick={() => w.close()}>×</button>
+            </div>
+            <div className="wpbody md readme-body" onClick={click} dangerouslySetInnerHTML={{ __html: renderWikiPage(p.md, p.links) }} />
         </div>
     )
 })

package/src/serve/hub-runtime.ts

@@ -146,15 +146,15 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
     // agent working here obeys that wiki, so a reader can open it.
     const graphs: GraphMount[] = []
     if (c.serve?.wikiGraph != null)
-        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, lint: c.serve.wikiGraph.lint != null ? { checks: c.serve.wikiGraph.lint } : { root } })
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, dir: c.serve.wikiGraph.dir ?? root, lint: c.serve.wikiGraph.lint != null ? { checks: c.serve.wikiGraph.lint } : { root } })
     else if (existsSync(join(root, 'wiki')))
-        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: `${c.name} wiki`, load: () => scanMdGraph({ root }), lint: { root } })
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: `${c.name} wiki`, load: () => scanMdGraph({ root }), dir: root, lint: { root } })
     const baseWiki = baseWikiRoot(root)
     if (baseWiki != null)
-        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), lint: null })
+        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), dir: baseWiki, lint: null })
     const agentRoot = join(root, 'agent')
     if (existsSync(agentRoot))
-        graphs.push({ id: 'agent', label: 'agent/', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), lint: { root: agentRoot, index: c.serve?.agentIndex } })
+        graphs.push({ id: 'agent', label: 'agent/', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), dir: agentRoot, lint: { root: agentRoot, index: c.serve?.agentIndex } })
     // ONE page for every repo: 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, and a repo

package/src/serve/project-gutter-route.ts

@@ -30,6 +30,8 @@ export type { Gate }
 export const POLL_MS = 5_000
 /** the app icon preview: sharp on a 2x screen at the admin page's 128px */
 const PREVIEW_PX = 256
+/** the rail's app icon, cropped to the plate: 40px at 2x, the largest rail size */
+const RAIL_PX = 96
 /** how long a release answer holds for a checkout whose `.git` is not a
  *  folder, since no stat can say when it moved */
 export const RELEASE_TTL_MS = 60_000
@@ -74,6 +76,8 @@ export type ProjectRow = {
     live: string | null
     /** the colours its repo.config.ts declares (SK024), null when it declares none */
     identity: Identity | null
+    /** its app icon cropped to the plate (core/app-icon.ts), what the folded rail draws; null with no mark */
+    appIcon: string | null
     /** epoch ms of the newest of: the last commit, the last shipkit run, the
      *  newest Claude Code transcript. null when none of them exists */
     activity: number | null
@@ -298,6 +302,15 @@ export function projectGutter(d: GutterDeps) {
     }
 
     const iconUrl = (r: WiredRepo): string | null => (r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`)
+    // the url names the mark's stamp and both colours, so a new mark or a colour change is a new url, cached a day
+    const railIconUrl = (r: WiredRepo, id: Identity): string | null => {
+        const mark = appIconOf(r.path)
+        if (mark == null) return null
+        const q = new URLSearchParams({ plate: '1', light: id.colorLight, dark: id.colorDark, v: String(iconStamp(mark)) })
+        return `/api/projects/app-icon/${encodeURIComponent(r.name)}?${q}`
+    }
+    /** drawn plates, by url: a page load asks for every repo's at once */
+    const plates = new Map<string, Promise<Buffer>>()
 
     async function measure(): Promise<ProjectsAnswer> {
         const t0 = performance.now()
@@ -334,6 +347,7 @@ export function projectGutter(d: GutterDeps) {
                 release: facts[i]!.release,
                 live: liveUrlOf(config),
                 identity: identityOfText(config),
+                appIcon: railIconUrl(r, identityOfRoot(r.path)),
                 activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
                 commit: facts[i]!.commitAt,
             }
@@ -386,12 +400,22 @@ export function projectGutter(d: GutterDeps) {
             const r = findAny(decodeURIComponent(path.slice('/api/projects/app-icon/'.length)))
             if (r == null) return new Response('not a house repo', { status: 404 })
             const icon = appIconOf(r.path)
-            if (icon == null) return new Response('no png mark: the app wears the default icon', { status: 404 })
+            if (icon == null) return new Response('no mark: the app wears the default icon', { status: 404 })
             // the colours a picker is on right now, before they are saved; else the config's
             const q = new URL(req.url).searchParams
             const asked = { colorLight: q.get('light') ?? '', colorDark: q.get('dark') ?? '' }
             const id = identityProblem(asked) == null ? asked : identityOfRoot(r.path)
             try {
+                if (q.get('plate') === '1') {
+                    const key = `${r.path}?${q}`
+                    let png = plates.get(key)
+                    if (png == null) {
+                        png = readFile(icon).then(async (b) => (await appIconPngs(b, id, [RAIL_PX], 'plate'))[0]!)
+                        plates.set(key, png)
+                        png.catch(() => plates.delete(key))
+                    }
+                    return new Response(new Uint8Array(await png), { headers: { 'content-type': 'image/png', 'cache-control': 'max-age=86400' } })
+                }
                 const [png] = await appIconPngs(await readFile(icon), id, [PREVIEW_PX])
                 return new Response(new Uint8Array(png!), { headers: { 'content-type': 'image/png', 'cache-control': 'max-age=60' } })
             } catch (e) {

package/src/serve/project-gutter.ts

@@ -48,7 +48,7 @@ export function houseIndex(repo: string, home: string): string | null {
 
 /** a repo's own icon, first hit wins. `.shipkit/identity/icon.png` is the rail
  *  icon a repo with no public surface carries, the identity kit writes public/ */
-export const ICON_FILES = ['.shipkit/identity/icon.png', 'public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
+export const ICON_FILES = ['.shipkit/identity/icon.png', '.shipkit/identity/icon.svg', 'public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
 
 export const ICON_TYPES: Record<string, string> = { png: 'image/png', svg: 'image/svg+xml', ico: 'image/x-icon' }
 

package/src/serve/run-serve.ts

@@ -5,7 +5,11 @@
 import { basename } from 'path'
 import { reclaimPreviousImage } from '../core/instance.ts'
 import { isLinkedWorktree } from '../core/git-root.ts'
+import { heldNow, heldText, OWN_LIB, setHeld } from '../core/last-good.ts'
 import { diskLibVersion, LIB_VERSION } from '../core/lib-version.ts'
+import { bootEntries, probeLoad, TreeProbe } from '../core/load-probe.ts'
+import { LibWatch } from '../home/lib-watch.ts'
+import type { LoadVerdict } from './stale-restart.ts'
 import { reexecBlocker, reexecSelf } from '../core/reexec.ts'
 import { attachToHome } from '../home/attach.ts'
 import { daemonUp, WORKER_ENV } from '../home/home-paths.ts'
@@ -21,6 +25,14 @@ export type { ServeIo }
 /** how often a hub of its own looks at its plan */
 export const PLAN_TICK_MS = 2_000
 
+/** does the lib this hub would restart onto load: probed again after every
+ *  write to its tree, not only when the version moves */
+export function serveProbe(lib: string): { loads: () => LoadVerdict; stop: () => void } {
+    const w = new LibWatch(lib)
+    const p = new TreeProbe(() => probeLoad(lib, bootEntries(lib, 'serve')), () => `${w.seq}|${diskLibVersion()}`)
+    return { loads: () => p.loads(), stop: () => w.close() }
+}
+
 /** what a `shipkit serve` does with its hub. On a machine with a home, no
  *  hub runs outside it: a home that answers takes it, and an installed one
  *  that does not is started first. `serve` only inside the home, a linked
@@ -104,6 +116,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     // a file table the watch restarts leaked: it re-executes itself in
     // place (same pid, argv, port) once no run is in flight. Only a
     // restart that throws is said, in the hub's own status
+    const probe = serveProbe(OWN_LIB)
     const stale = new StaleRestart({
         boot: LIB_VERSION,
         disk: diskLibVersion,
@@ -114,6 +127,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             if (blocked != null) throw new Error(blocked)
             io.print(`ok: ${why}: restarting in place`)
             stale.stop()
+            probe.stop()
             clearInterval(planClock)
             rt.stop()
             hub.stop()
@@ -126,6 +140,16 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             }
         },
         say: (text) => deps.hubProblems?.set('stale', text == null ? null : { text, severity: 'red' }),
+        // a version move restarts only onto code that loads; the held line is the hub's (serve-hub.ts)
+        loads: () => probe.loads(),
+        hold: (v) => {
+            if (v == null) return setHeld(null)
+            const was = heldNow()
+            if (was?.file === v.file && was.error === v.error) return
+            const h = { since: was?.since ?? Date.now(), file: v.file, error: v.error, from: OWN_LIB, copyAt: null }
+            io.printErr(`WARN ${heldText(h)}`)
+            setHeld(h)
+        },
     })
     stale.start()
     // a watch restart that leaked sheds it before the first run spawns anything
@@ -140,6 +164,7 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     for (const sig of ['SIGINT', 'SIGTERM'] as const)
         process.on(sig, () => {
             stale.stop()
+            probe.stop()
             clearInterval(planClock)
             plan.stop()
             rt.stop()